{"record":{"id":"2151eb9a80d57346","repo":"karatelabs/karate","slug":"timeout-waiting-for-url-to-contain-expected","errorCode":null,"errorMessage":"timeout waiting for URL to contain: ${expected}","messagePattern":"timeout waiting for URL to contain: (.+?)","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java","lineNumber":3390,"sourceCode":"    }\n\n    /**\n     * Wait for URL to contain expected string.\n     */\n    public String waitForUrl(String expected) {\n        return waitForUrl(expected, options.getTimeoutDuration());\n    }\n\n    /**\n     * Wait for URL to contain expected string with custom timeout.\n     */\n    public String waitForUrl(String expected, Duration timeout) {\n        String found = pollFor(timeout.toMillis(), options.getRetryInterval(), () -> {\n            String url = getUrl();\n            return url != null && url.contains(expected) ? url : null;\n        });\n        if (found == null) {\n            throw new DriverException(\"timeout waiting for URL to contain: \" + expected);\n        }\n        return found;\n    }\n\n    /**\n     * Wait until a JavaScript expression on an element evaluates to truthy.\n     * The element is available as '_' in the expression.\n     */\n    public Element waitUntil(String locator, String expression) {\n        return waitUntil(locator, expression, options.getTimeoutDuration());\n    }\n\n    /**\n     * Wait until a JavaScript expression on an element evaluates to truthy.\n     */\n    public Element waitUntil(String locator, String expression, Duration timeout) {\n        Element found = pollFor(timeout.toMillis(), options.getRetryInterval(),\n                () -> exists(locator) && Terms.isTruthy(script(locator, expression))","sourceCodeStart":3372,"sourceCodeEnd":3408,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java#L3372-L3408","documentation":"CdpDriver.waitForUrl(expected, timeout) repeatedly reads the current page URL via CDP and returns it once it contains the expected substring; if the poll never matches within the timeout, a DriverException is thrown. This is the designated wait for client-side navigations / SPA route changes.","triggerScenarios":"driver.waitForUrl(\"/dashboard\", Duration.ofSeconds(10)) when navigation did not happen, happened to a different URL, or took longer than the timeout; expected substring spelled differently from the actual URL (query params, hash, trailing slash).","commonSituations":"Login failed so the app stayed on the login page; SPA router redirected to an error route; redirect chain exceeded the wait budget on slow CI; expected substring includes a host while the URL compared is a path, or vice versa.","solutions":["Increase the timeout to cover slow environments","Print the actual URL (driver.getUrl()) after failure and correct the expected substring","Wait for the condition that causes navigation (click/login response) to succeed before waiting on the URL","Use waitForUrl with a stable path fragment rather than volatile query params"],"exampleFix":"// before\nString url = driver.waitForUrl(\"http://localhost:8080/app?token=\", Duration.ofSeconds(5));\n// after\nString url = driver.waitForUrl(\"/app\", Duration.ofSeconds(15));","handlingStrategy":"try-catch","validationCode":"String current = driver.getUrl();\nif (current != null && current.contains(\"/app\")) { /* already there, skip wait */ }","typeGuard":null,"tryCatchPattern":"try {\n    String url = driver.waitForUrl(\"/dashboard\", Duration.ofSeconds(20));\n} catch (DriverException e) {\n    logger.error(\"URL wait failed; actual={}, expected-contains={}\", driver.getUrl(), \"/dashboard\");\n    throw e;\n}","preventionTips":["Match on a stable path fragment, not volatile query params or full URLs","Log the actual URL on failure to distinguish wrong-route vs slow-load","Verify the navigation trigger (click/login) succeeded before waiting"],"tags":["driver","timeout","navigation","url"],"backgroundTag":"request-timeout","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}