karatelabs/karate · error · DriverException

waitForText timeout: expected

Error message

waitForText timeout: ${locator} expected: ${expected}

What it means

W3cDriver.waitForText polls the element's text, comparing it to the expected value, every retry interval until timeout; each poll swallows exceptions because the element may not exist yet. If the element's text never equals/contains the expected string within the timeout, a DriverException naming the locator and expected text is thrown.

Solutions

1. Print the actual text (driver.text(locator)) and compare with expected to spot formatting mismatches
2. Increase the timeout via waitForText(locator, expected, timeout)
3. Normalize the expected string (trim/case) or match on a stable substring if the API supports contains semantics
4. Fix the selector if it resolves to the wrong element

Example fix

// before
driver.waitForText('#status', 'Saved!'); // actual text is 'Saved !' with space
// after
driver.waitForText('#status', 'Saved', 15000); // match stable substring

String actual = driver.exists(locator) ? driver.text(locator) : null;
if (actual != null && actual.contains(expected)) { /* already satisfied */ }

try {
    driver.waitForText(locator, expected, timeout);
} catch (DriverException e) {
    // capture driver.text(locator) into the failure report for diagnosis
}

When it happens

Trigger: Calling driver.waitForText(locator, expected) where the element never exists, or exists but its text never matches expected, within options.getTimeoutDuration().

Common situations: Expected text differs in whitespace/casing from rendered text; text is set by async JS that finishes after timeout; localized i18n strings differ between environments; selector matches a container whose inner text updates later.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• timeout waiting for text
• waitFor timeout
• waitForAny timeout
• waitForEnabled timeout
• waitUntil timeout: expression

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/ed7b11b0edc762e4. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java:575

    public Element waitForText(String locator, String expected) {
        return waitForText(locator, expected, options.getTimeoutDuration());
    }

    @Override
    public Element waitForText(String locator, String expected, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        while (System.currentTimeMillis() < deadline) {
            try {
                String text = text(locator);
                if (text != null && text.contains(expected)) {
                    return BaseElement.existing(this, locator);
                }
            } catch (Exception e) {
                // Element may not exist yet
            }
            sleep(options.getRetryInterval());
        }
        throw new DriverException("waitForText timeout: " + locator + " expected: " + expected);
    }

    @Override
    public Element waitForEnabled(String locator) {
        return waitForEnabled(locator, options.getTimeoutDuration());
    }

    @Override
    public Element waitForEnabled(String locator, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        while (System.currentTimeMillis() < deadline) {
            try {
                if (enabled(locator)) {
                    return BaseElement.existing(this, locator);
                }
            } catch (Exception e) {
                // Element may not exist yet
            }

View on GitHub (pinned to a22eb90246)