How to Handle Multiple Windows in Cypress

Introduction

Handling multiple windows or tabs is one of the most common scenarios when performing end-to-end testing for web applications. This might happen when clicking on a link opens a new tab or a pop-up window. However, Cypress, by default, runs tests in a single browser tab and does not support direct interaction with multiple browser windows or tabs.

In this post, we'll explore how to handle multiple windows in Cypress using a few workarounds and best practices to mimic the multi-tab behavior and keep your tests running smoothly.

Cypress's Single Window Limitation

Cypress doesn't provide native support for multi-window testing due to the way it’s architected to run within a single tab. The reasoning behind this design is to maintain consistency, reliability, and test isolation. However, with some smart tricks, you can still simulate multi-window interactions, as well as verify behavior triggered by new tabs or windows.

Techniques for Handling Multiple Windows in Cypress

Let’s look at a few common approaches to handling multiple windows in Cypress:

1. Intercept and Assert on Links Without Opening New Tabs
2. Stub or Mock New Window Calls
3. Simulate the Window's Location Change

1. Intercept and Assert on Links Without Opening New Tabs
A common scenario is clicking a link that opens a new tab. Instead of letting the browser open the new tab, you can intercept the URL that is supposed to be opened in the new tab, assert the link, and visit the URL in the same tab.

Example:
Imagine you have a webpage with a link like this:

<a href="https://example.com" target="_blank">Visit Example</a>

When you click this link, it would normally open a new tab. To handle this in Cypress:

describe('Handle multiple windows by intercepting', () => {
  it('should intercept the link and open in the same tab', () => {
    cy.visit('/');

    // Find the link and assert that it has the correct href
    cy.get('a[target="_blank"]').should('have.attr', 'href', 'https://example.com');

    // Instead of opening a new tab, you can visit the link in the same window
    cy.get('a[target="_blank"]').invoke('removeAttr', 'target').click();

    // Now verify that you are on the new page
    cy.url().should('include', 'https://example.com');
  });
});

In this example:

The invoke('removeAttr', 'target') ensures the link doesn’t open in a new tab but in the current one.
Cypress can then visit the new page in the same window, making it easy to continue interacting with elements on the new page.

2. Stub or Mock window.open Calls
Some applications use JavaScript to programmatically open new tabs via window.open(). You can intercept these calls and prevent the browser from opening a new window by stubbing the window.open function.

Example:

describe('Handle window.open', () => {
  it('should stub the window.open and visit the URL directly', () => {
    cy.visit('/');

    // Stub the window.open function
    cy.window().then((win) => {
      cy.stub(win, 'open').as('windowOpen');
    });

    // Click the button that triggers window.open
    cy.get('#open-new-tab-button').click();

    // Check that the window.open call was made with the expected URL
    cy.get('@windowOpen').should('be.calledWith', 'https://example.com');

    // Instead of opening a new window, we can visit the URL directly in the current tab
    cy.visit('https://example.com');

    // Now verify the URL and page content
    cy.url().should('include', 'https://example.com');
  });
});

In this example:

We stub the window.open method using Cypress’s cy.stub() and prevent it from opening a new window.
You can then assert that window.open was called with the correct URL and redirect the test to the target URL using cy.visit().

3. Simulate Window Location Change
If the application changes window.location to navigate to a different page or window, Cypress can directly intercept that and handle it. This method is particularly useful when window redirects are involved.

Example:

describe('Simulate window.location change', () => {
  it('should simulate window location change', () => {
    cy.visit('/');

    // Trigger an event that changes the window location
    cy.window().then((win) => {
      win.location.href = 'https://example.com';
    });

    // Assert that the URL has changed
    cy.url().should('include', 'https://example.com');
  });
});

Best Practices for Handling Multiple Windows in Cypress

1. Use Redirects Smartly: Always try to redirect to the new URL using cy.visit() instead of actually opening new windows or tabs. This will help maintain test stability and isolation.
2. Avoid Opening New Windows: Opening a new tab or window might disrupt the controlled test environment that Cypress provides. Instead, remove the target="_blank" attribute or mock window.open.
3. Always Assert URLs: When handling links or window redirects, always assert the URL change to ensure Cypress is on the correct page after the interaction.
4. Stub External Dependencies: For applications that involve multiple windows with external services, consider stubbing the external services or interactions for a more reliable test.

Conclusion

While Cypress doesn’t directly support multi-window testing, you can still handle multiple windows and tabs by intercepting and stubbing the calls that would normally open new tabs or windows. By modifying the behavior to stay within a single tab, you can maintain Cypress’s core principles of test stability and reliability.

These workarounds, such as removing the target="_blank" attribute, stubbing window.open, or simulating window location changes, provide a powerful way to handle multi-window scenarios effectively. Start integrating these techniques into your Cypress tests today to overcome the multi-window challenge with ease!