Error: Timed Retry (4000ms) - Expected URL Equal: url in Cypress

The "Timed retrying 4000ms: expected URL equal" error in Cypress occurs when the test runner expects a specific URL but the browser navigates to a different path, often due to asynchronous redirects or server-side logic that takes longer than the default timeout. To resolve this, you must adjust the cy.url() assertion with explicit waiting strategies, ensure proper handling of 2FA redirects, and verify that network intercepts are not masking the true navigation target.

Understanding the Timeout Mechanism

Cypress commands are asynchronous and automatically retry until they pass or time out. The default command timeout is 4000 milliseconds, which is why the error message explicitly states "Timed retrying 4000ms." When you use cy.url().should('equal', 'expected-url'), Cypress polls the current URL every 50 milliseconds. If the URL does not match the expected string within four seconds, the assertion fails. This behavior is designed to prevent flaky tests by allowing for natural delays in application rendering. However, it becomes problematic during Two-Factor Authentication (2FA) flows because the redirect from the verification page back to the dashboard is often unpredictable. The server might take extra time to validate the OTP, or the client-side router might delay the transition to ensure state consistency. In these scenarios, a rigid equality check against a static URL string is too brittle. Instead of relying on exact string matching, consider using partial matches or regular expressions if the query parameters change dynamically while the base path remains constant. For more complex authentication issues, such as certificate mismatches during login, refer to our guide on SSL Certification Verification during Login: A Tech Support Overview to rule out underlying connectivity issues that might cause unexpected redirects.

Common Causes in 2FA Flows

The most frequent cause of this error in 2FA implementations is a mismatch between the expected final destination and the intermediate state. After entering the code, the application typically performs a POST request to validate the token. During this validation, the browser might briefly display a loading spinner or a generic success message before redirecting. If your test asserts the URL immediately after submitting the form, it may catch the intermediate state rather than the final dashboard URL. Another common cause is incorrect URL encoding. If the expected URL contains special characters or query parameters, Cypress's strict equality check will fail if the browser encodes them differently (e.g., spaces becoming %20). Additionally, some Single Page Applications (SPAs) handle routing client-side without a full page reload. In these cases, the URL bar updates via the History API, which Cypress can sometimes miss if the assertion runs before the DOM update cycle completes. It is crucial to distinguish between a hard redirect and a soft navigation event. If your application uses hash-based routing (#), ensure your expected URL includes the hash fragment, as standard equality checks treat hashes as distinct parts of the URL string.

Solution 1: Increase Command Timeout

If the redirect simply takes longer than four seconds due to slow server response times or heavy client-side processing, increasing the timeout is the most straightforward fix. You can override the default timeout for a single command using the timeout option. This approach is useful when you know the delay is consistent and short, perhaps up to ten seconds.

cy.url().should('eq', 'https://example.com/dashboard', {
  timeout: 10000
});

While effective, this method does not address the root cause of the delay. It merely gives the application more time to complete its work. If the redirect is failing entirely or going to the wrong page, increasing the timeout will only result in a longer wait before failure. Use this solution sparingly and only after confirming that the correct URL is eventually reached.

Solution 2: Use Explicit Waits Before Assertion

A more robust approach is to decouple the action from the assertion. Instead of asserting the URL immediately after clicking the submit button, insert an explicit wait for a known element that appears only after successful redirection. This ensures that the navigation has fully completed before you check the URL. For example, wait for the presence of a user profile icon or a specific header text that exists exclusively on the post-login dashboard.

cy.get('#user-profile-icon').should('be.visible');
cy.url().should('include', '/dashboard');

Using cy.wait() based on elements is generally safer than arbitrary time waits because it adapts to the actual performance of the application. If the app speeds up, the test proceeds faster; if it slows down, the test waits appropriately. This pattern significantly reduces flakiness in 2FA flows where the visual confirmation of success is a reliable indicator of navigation completion.

Solution 3: Intercept Network Requests

For precise control over navigation timing, intercept the network request that triggers the redirect. By stubbing or verifying the API call that validates the 2FA token, you can ensure the backend process is finished before checking the frontend URL. This method is particularly powerful when the redirect is handled asynchronously via JavaScript fetch requests rather than traditional form submissions.

cy.intercept('POST', '/api/verify-otp').as('verifyOtp');
cy.get('#submit-btn').click();
cy.wait('@verifyOtp');
cy.url().should('include', '/dashboard');

This strategy guarantees that the assertion runs only after the server has acknowledged the OTP. Note that chaining commands correctly is vital; cy.wait() must be a separate command following the interaction, not chained directly to the previous click without proper separation in logical flow. This ensures the test runner processes the interception alias correctly before moving to the URL check.

Frequently Asked Questions

Why does cy.url() fail even when I am on the correct page?

It often fails because of trailing slashes or query parameter ordering. Cypress performs strict string comparison by default, so /dashboard and /dashboard/ are considered different URLs. Always normalize your expected URLs or use should('include') to check for substrings rather than exact matches.

Can I disable retries for cy.url() assertions?

No, you cannot disable retries for built-in assertions like should() because their reliability depends on automatic polling. However, you can use cy.location('pathname') followed by a custom assertion if you need immediate feedback without retry logic, though this is not recommended for production tests as it increases flakiness.

How do I handle redirects with dynamic session tokens?

When redirects include dynamic tokens like ?session_id=xyz, avoid using should('equal'). Instead, use should('match', /\/dashboard\?session_id=\w+/) to validate the path structure while ignoring the variable query parameter values that change per login attempt.

What if the 2FA step opens a new tab?

Cypress handles multiple tabs poorly. If your 2FA verification opens a new window, switch context using cy.window().then(win => win.open(...)) or refactor the test to keep everything in one tab. Opening new tabs often causes Cypress to lose track of the original command chain, leading to unexpected URL errors.

Is it better to wait for an element or increase timeout?

Waiting for an element is always superior. Increasing the timeout masks performance issues and makes tests slower unnecessarily. Element-based waits provide a deterministic signal that the application state has changed, ensuring your tests run as fast as the application allows while remaining stable.