Testing

Selenide Fluent API: Assertions and Conditions Reference

21 Sep 2026 — 3 min read

Selenide's assertion API is what makes it worth using over raw Selenium. The fluent should / shouldHave / shouldBe methods combine waiting and assertion into a single call, with failure messages that tell you what actually happened.

Core Assertion Methods

Every SelenideElement exposes three assertion methods:

Method	Use for
`shouldBe(condition)`	State conditions: visible, enabled, checked
`shouldHave(condition)`	Content conditions: text, attribute, value
`shouldNotBe(condition)`	Negation of state
`shouldNotHave(condition)`	Negation of content

$(".submit-btn").shouldBe(visible);
$(".submit-btn").shouldBe(enabled);
$("input[name=email]").shouldHave(value("user@example.com"));
$(".error-msg").shouldHave(text("Invalid password"));
$(".loading").shouldNotBe(visible);

Visibility and State Conditions

import static com.codeborne.selenide.Condition.*;

// Visibility
element.shouldBe(visible);
element.shouldBe(hidden);
element.shouldNotBe(visible);

// Interaction state
element.shouldBe(enabled);
element.shouldBe(disabled);
element.shouldBe(focused);
element.shouldBe(readonly);

// Form elements
$("input[type=checkbox]").shouldBe(checked);
$("input[type=checkbox]").shouldNotBe(checked);

// Existence in DOM (vs visibility)
element.should(exist);
element.shouldNot(exist);

// Empty
$("ul.results").shouldBe(empty);

Text Conditions

// Exact text match (trims whitespace)
element.shouldHave(text("Submit"));

// Partial match
element.shouldHave(text("Subm"));

// Exact text, no trimming
element.shouldHave(exactText("  Submit  "));

// Case-insensitive
element.shouldHave(textCaseSensitive("SUBMIT"));

// Own text (excludes child elements)
element.shouldHave(ownText("Parent text only"));

Attribute and CSS Conditions

// Attribute presence and value
element.shouldHave(attribute("data-id", "42"));
element.shouldHave(attribute("href"));           // just presence
element.shouldNotHave(attribute("disabled"));

// CSS class
element.shouldHave(cssClass("active"));
element.shouldNotHave(cssClass("loading"));

// CSS property value
element.shouldHave(cssValue("color", "rgb(255, 0, 0)"));

// Input value
$("input[name=username]").shouldHave(value("john"));
$("textarea").shouldHave(value(""));

// Selected option in dropdown
$("select#country").shouldHave(value("US"));
$("select#country").shouldHave(selectedText("United States"));

Combining Conditions

Chain multiple conditions with and:

element.shouldBe(visible.and(enabled));
element.shouldHave(text("Submit").and(cssClass("btn-primary")));

Or use varargs syntax:

element.shouldHave(text("Submit"), cssClass("btn-primary"));

Custom Timeout Per Assertion

Override the global timeout for slow elements:

import java.time.Duration;

$(".data-table").shouldBe(visible, Duration.ofSeconds(20));
$(".export-complete").shouldHave(text("Done"), Duration.ofMinutes(2));

Collections

$$ returns ElementsCollection for asserting groups of elements:

ElementsCollection items = $$(".product-card");

// Size
items.shouldHave(CollectionCondition.size(10));
items.shouldHave(CollectionCondition.sizeGreaterThan(0));
items.shouldHave(CollectionCondition.sizeLessThan(50));

// Content
items.shouldHave(CollectionCondition.texts("Apple", "Banana", "Cherry"));
items.shouldHave(CollectionCondition.containsText("Banana"));
items.shouldHave(CollectionCondition.itemWithText("Cherry"));

// All/none match
items.shouldHave(CollectionCondition.allMatch("visible", el -> el.isDisplayed()));

Filtering:

// Filter to matching elements
$$(".item").filterBy(text("Active")).shouldHave(size(3));
$$(".item").excludeWith(cssClass("disabled")).shouldHave(sizeGreaterThan(0));

Custom Conditions

Write your own condition when built-ins don't cover your case:

import com.codeborne.selenide.Condition;
import org.openqa.selenium.WebElement;

Condition hasDataId = new Condition("has data-id attribute") {
    @Override
    public boolean apply(Driver driver, WebElement element) {
        return element.getAttribute("data-id") != null;
    }
};

$(".product").shouldHave(hasDataId);

Failure Messages

When an assertion fails, Selenide reports:

Element should be visible {By.cssSelector: .submit-btn}
Element: '<button class="submit-btn" style="display: none;">Submit</button>'
Screenshot: /build/reports/tests/my_test/1234567890.png

You get the actual HTML of the element, not just "expected visible but was hidden". This makes diagnosing failures fast.

Soft Assertions

Collect all failures instead of stopping at the first:

import com.codeborne.selenide.junit5.SoftAssertsExtension;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SoftAssertsExtension.class)
class SoftAssertTest {

    @Test
    void checkMultipleFields() {
        open("https://example.com/profile");

        $(".name").shouldHave(text("John"));         // failure recorded
        $(".email").shouldHave(text("john@ex.com")); // failure recorded
        $(".role").shouldHave(text("Admin"));         // failure recorded
        // All three failures reported at end of test
    }
}

Practical Example

@Test
void checkoutFormValidation() {
    open("/checkout");

    // Submit empty form
    $("button[type=submit]").click();

    // All required field errors appear
    $("#email-error").shouldBe(visible).shouldHave(text("Email is required"));
    $("#name-error").shouldBe(visible).shouldHave(text("Name is required"));
    $("button[type=submit]").shouldBe(enabled);  // form stays submittable

    // Fill email, error clears
    $("input[name=email]").setValue("user@example.com");
    $("#email-error").shouldNotBe(visible);

    // Name error persists
    $("#name-error").shouldBe(visible);
}

The fluent API makes assertions self-documenting. Any developer reading the test understands exactly what's being verified.