Writing tests

Introduction

CSTesting assertions are designed for the dynamic web. Use assertThat() for page-level checks (title, URL) and assertThat(locator) for element-level checks (visible, attribute, text, value). Assertions throw AssertionError on failure. Use waitForSelector, waitForLoad, or waitForURL when you need to wait for conditions before asserting or acting.

The example below shows how to write a test using assertions, locators, and selectors.

package org.example;

import com.cstesting.CSTesting;
import com.cstesting.CSTestingBrowser;
import com.cstesting.CSTestingOptions;

public class App {
    public static void main(String[] args) {
        CSTestingBrowser browser = CSTesting.createBrowser(
            CSTestingOptions.builder().headless(true).build()
        );
        try {
            browser.gotoUrl("https://example.com");

            // Expect the page title to contain a substring.
            browser.assertThat().hasTitle("Example");

            // Create a locator and expect an attribute to match.
            var link = browser.locator("a").first();
            browser.assertThat(link).hasAttribute("href");

            // Click the link (e.g. "More information...").
            link.click();

            // Wait for navigation and expect a heading to be visible.
            browser.waitForLoad(5_000);
            browser.assertThat(browser.locator("h1")).isVisible();
        } finally {
            browser.close();
        }
    }
}

Assertions

Use browser.assertThat() for the page and browser.assertThat(locator) for elements. Assertions are fluent and throw AssertionError if the condition is not met.

Page assertions:

// Title contains or equals the expected string.
browser.assertThat().hasTitle("Example Domain");

// URL contains the string or matches a pattern (use * as wildcard).
browser.assertThat().hasURL("https://example.com");
browser.assertThat().hasURL("**/example*");

Element assertions:

// Visibility and state.
browser.assertThat(browser.locator("button")).isVisible();
browser.assertThat(browser.locator("#name")).isEditable();
browser.assertThat(browser.locator("input")).isEnabled();
browser.assertThat(browser.locator("[disabled]")).isDisabled();

// Text and value.
browser.assertThat(browser.locator("h1")).hasText("Example");
browser.assertThat(browser.locator("h1")).containText("Example");
browser.assertThat(browser.locator("#search")).hasValue("query");
browser.assertThat(browser.locator("#search")).containValue("query");

// Attributes.
browser.assertThat(browser.locator("a").first()).hasAttribute("href");
browser.assertThat(browser.locator("a").first()).hasAttribute("href", "https://example.com");

// Count of matching elements.
browser.assertThat(browser.locator("button")).count(3);
browser.assertThat(browser.locator("li")).hasCount(5);

Locators

Locators represent a way to find element(s) on the page. Create them with browser.locator(selector) and use them for actions (.click(), .type(), etc.) and assertions. If the selector matches multiple elements, use .first(), .last(), or .nth(index) before performing an action.

Selector formats: CSS (default), XPath (//button or xpath=//button), id=value, name=value, or any attr=value.

// By text (XPath).
var getStarted = browser.locator("//a[contains(.,'Get Started')]").first();
browser.assertThat(getStarted).hasAttribute("href", "/docs/intro");
getStarted.click();

// By CSS or id/name.
browser.assertThat(browser.locator("h1")).isVisible();
browser.assertThat(browser.locator("id=submit")).isEnabled();
browser.locator("name=email").type("user@example.com");

See Locators for the full list of selector formats and locator methods.

Test isolation

Create a new browser for each test so that tests do not share state (cookies, storage, or tabs). Open the browser at the start of the test and close it in a finally block (or use try-with-resources if you wrap the API).

public void testLogin() {
    CSTestingBrowser browser = CSTesting.createBrowser(
        CSTestingOptions.builder().headless(true).build()
    );
    try {
        browser.gotoUrl("https://example.com/login");
        browser.locator("name=user").type("alice");
        browser.locator("name=pass").type("secret");
        browser.locator("button[type=submit]").click();
        browser.assertThat().hasURL("**/welcome");
    } finally {
        browser.close();
    }
}