karatelabs/karate · error · DriverException

timeout waiting for text

Error message

timeout waiting for text '${expected}' in element: ${locator}

What it means

driver.waitForText(locator, expected, timeout) polls the element's text until it contains the expected string. If the timeout elapses without the text appearing, Karate throws this DriverException naming the expected text and the locator.

Solutions

1. Log or assert the element's actual text on failure to compare with the expectation.
2. Increase the timeout for slow async updates, or trigger/await the underlying request completion first.
3. Match the exact current copy including case/whitespace, or relax to a stable substring.
4. Ensure the correct frame/document is active and the selector targets the element that actually carries the text.

Example fix

// before
driver.waitForText('#status', 'Complete', Duration.ofSeconds(5)); // app shows 'Completed'
// after
driver.waitForText('#status', 'Complete', Duration.ofSeconds(30)); // or match 'Complete' substring actually present

// snapshot current text on failure for diagnosis
String actual = driver.exists(locator) ? driver.text(locator) : "<absent>";

try {
    driver.waitForText(locator, expected, Duration.ofSeconds(30));
} catch (Exception e) {
    if (e.getMessage().contains("timeout waiting for text")) {
        String actual = driver.exists(locator) ? driver.text(locator) : "<absent>";
        throw new AssertionError("expected text '" + expected + "' but saw: " + actual, e);
    } else throw e;
}

When it happens

Trigger: driver.waitForText / * waitForText step where the element exists but its text never contains 'expected' within the timeout — async data never loaded, text differs in case/whitespace, or the expected value is stale.

Common situations: Backend slower than the timeout (slow API, cold cache); expectation out of date after copy changes; text rendered in a child element the polling selector does not cover; localized text differing from the hardcoded English expectation; waiting inside the wrong frame.

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 element
• timeout waiting for any element
• timeout waiting for element to be enabled
• timeout waiting for elements
• waitForText timeout: expected

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java:3350

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

    /**
     * Wait for an element to contain specific text with custom timeout.
     */
    public Element waitForText(String locator, String expected, Duration timeout) {
        Element found = pollFor(timeout.toMillis(), options.getRetryInterval(), () -> {
            if (exists(locator)) {
                String text = text(locator);
                if (text != null && text.contains(expected)) {
                    return BaseElement.existing(this, locator);
                }
            }
            return null;
        });
        if (found == null) {
            throw new DriverException("timeout waiting for text '" + expected + "' in element: " + locator);
        }
        return found;
    }

    /**
     * Wait for an element to be enabled.
     */
    public Element waitForEnabled(String locator) {
        return waitForEnabled(locator, options.getTimeoutDuration());
    }

    /**
     * Wait for an element to be enabled with custom timeout.
     */
    public Element waitForEnabled(String locator, Duration timeout) {
        Element found = pollFor(timeout.toMillis(), options.getRetryInterval(),
                () -> exists(locator) && enabled(locator) ? BaseElement.existing(this, locator) : null);
        if (found == null) {

View on GitHub (pinned to a22eb90246)