[RFC] Native Support for Multiple Tabs and Windows by Extending Existing CDP & cy.origin() Architecture

[Mr-Lucasz]

RFC: Support for Multiple Tabs/Windows in Cypress

Status

Status: Proposed
Author: Lucas da Cunha Rodrigues
Date: 03/09/2025
Type: Feature Request

Summary

This RFC proposes adding native support for multiple tabs and windows in Cypress, addressing one of the primary limitations compared to Playwright. The proposal includes a comprehensive architectural analysis, API design, and implementation roadmap.

Motivation

Current Limitations

• Cypress operates in a single page context, unable to interact with popups, new tabs, or multiple windows
• Users must resort to workarounds like cy.window() or external libraries, which are fragile and limited
• This creates a significant competitive disadvantage against Playwright, which has native multi-context support

Use Cases

1. OAuth Flows: Testing login with external providers that open popups
2. Payment Processing: Testing payment flows that redirect to external services
3. File Downloads: Testing download functionality that opens new tabs
4. Multi-step Workflows: Testing complex user journeys spanning multiple windows
5. Third-party Integrations: Testing integrations that require popup-based authentication

Historical Context

Important Note: This RFC addresses a different problem than what was solved by cy.origin().

• Issue max 1 site... support visiting multiple superdomains in one test #944 was closed because cy.origin() was released as the official solution for "supporting multiple superdomains in a test"
• Issue 9.6.0 Experimental Feature: Easily test multi-domain workflows with cy.origin() #21186 demonstrates that while cy.origin() solves cross-domain testing, it does not solve the multiple tabs/windows problem
• These are related but technically distinct challenges:
  • cy.origin(): Cross-domain communication within the same tab
  • This RFC: Multiple tabs/windows management (regardless of domain)

The Cypress team has not yet addressed the multiple tabs/windows use case, making this a legitimate new feature request.

Technical Analysis

Current Architecture Gap

The core issue is Cypress's injection architecture. The Driver is injected into a single page context and lacks inherent visibility or control over other document contexts (tabs, iframes, windows).

Key Gaps:

1. Context Isolation: Each tab/window is an isolated JavaScript environment
2. Communication & Synchronization: No mechanism for commands in one tab to wait for or react to events in another tab
3. Lifecycle Control: Cypress manages the lifecycle of a single page only
4. API Integration: The synchronous, chainable API (cy.get(...).click(...).should(...)) needs to be preserved

Existing Infrastructure Analysis

80% of the required infrastructure already exists in the Cypress codebase:

Target Management (packages/server/lib/browsers/browser-cri-client.ts:545-551)

// Already implemented: List all browser targets
const { targetInfos: targets } = await this.browserClient.send('Target.getTargets')
const target = targets.find((target) => target.url === url)

// Already implemented: Create new tabs
target = await this.browserClient.send('Target.createTarget', { url: 'about:blank' })

// Already implemented: Close specific tabs
await this.browserClient.send('Target.closeTarget', { targetId: this.currentlyAttachedTarget.targetId })

Multiple CDP Connections (packages/server/lib/browsers/browser-cri-client.ts:553-570)

// Already implemented: Create CDP connection with specific target
this.currentlyAttachedTarget = await CriClient.create({
  target: target.targetId,  // Can be ANY targetId
  // ... other parameters
})

// Already implemented: Clone connections for separate protocols
this.currentlyAttachedProtocolTarget = await this.currentlyAttachedTarget.clone()

Context State Management (packages/driver/src/cypress/state.ts:27)

// Already implemented: Active context tracking
(k: 'currentActiveOrigin', v?: string): string

Context Switching Pattern (packages/driver/src/cy/commands/origin/index.ts:94-98)

// Already implemented: Context switching mechanism
cy.state('currentActiveOrigin', origin)
// ... execute commands in new context
cy.state('currentActiveOrigin', undefined)

Component Viability Assessment

Component	Viability	Evidence in Codebase
CDP Manager	✅ 100%	Target.getTargets, Target.createTarget, Target.closeTarget (browser-cri-client.ts:545-551)
Context Stack	✅ 100%	currentActiveOrigin, cy.state() (state.ts:27, origin/index.ts:94)
Multiple Connections	✅ 100%	currentlyAttachedTarget, currentlyAttachedProtocolTarget (browser-cri-client.ts:189-190)
Command Switching	✅ 100%	cy.origin() as proof of concept (origin/index.ts:94-98)
Lifecycle Management	✅ 90%	clone(), close(), cleanup patterns (browser-cri-client.ts:567-570)

Key Insight: This is not an architectural rewrite but an intelligent extension of mature, proven systems.

Detailed Design

Proposed Architecture

Core Components

1. CDP Manager

   • New layer within Cypress responsible for establishing and managing CDP connections with all browser tabs/windows
   • Maintains a map of TargetId → Page
   • Observes target creation/destruction events

2. Context Stack

   • Stack that tracks the current execution context (which tab is active)
   • Commands like cy.* always operate on the context at the top of this stack

3. Cross-Context Event Bridge

   • Event mechanism allowing synchronization between contexts
   • Enables waiting for elements to become visible in one tab before continuing tests in another

API Design

Option 1: Explicit Page Management (Playwright-style)

cy.openNewTab() // Triggers action that opens popup/new tab
  .then((newPage) => {
    cy.wrap(newPage).find('#elementInNewTab').should('be.visible');
    newPage.close(); // Explicitly close the tab
  });

Option 2: Context Switching (Cypress-native)

cy.origin('https://another-tab.com', () => {
  // This callback executes in the NEW TAB context
  cy.get('button').click(); // Searches for button in new tab
});
// Context automatically returns to original tab after callback

Option 3: Imperative Switch Command

cy.switchToTab({ url: 'https://another-tab.com' }); // Switch to tab with this URL
cy.get('body').should('contain', 'Welcome'); // Now searches in new tab
cy.switchToTab({ index: 0 }); // Return to first tab

Recommended Approach: Option 2 (cy.origin for tabs) aligns best with Cypress's philosophy and existing API.

Design Patterns

1. Facade: Simple API (cy.origin) hiding CDP management, events, and context stacking complexity
2. Proxy: The newPage object or internal context within cy.origin acts as a proxy, translating cy commands to target tab via CDP
3. Observer: CDP Manager observes target creation/destruction events to keep internal map updated

Implementation Roadmap

Phase 0: Research and Advocacy (1-2 months) ⭐ CURRENT PHASE

• Activity: Establish deep technical discussion on Cypress GitHub, presenting gap analysis and design proposal
• Deliverable: Formal RFC detailing motivation, use cases, proposed API, and impacts
• Goal: Community consensus and maintainer commitment

Phase 1: CDP Manager Prototype (2-3 months) ✅ HIGHLY VIABLE

• Activity: Extend existing CDP infrastructure to support multiple targets
• Deliverable: Library capable of listing all browser targets and managing multiple CDP connections
• Technical Foundation: Build upon existing Target.getTargets, CriClient.create, and connection management
• Evidence: All required CDP methods already implemented in browser-cri-client.ts

Phase 2: Core Context Integration (3-4 months) ✅ VIABLE

• Activity: Extend existing state management system to support tab context switching
• Deliverable: Basic commands working in non-default context using existing CDP connections
• Technical Foundation: Extend cypress/state.ts following currentActiveOrigin pattern
• Evidence: Context switching mechanism already proven in cy.origin() implementation

Phase 3: High-Level API Implementation (2-3 months)

• Activity: Build Facade layer (cy.origin for tabs or cy.switchToTab)
• Deliverable: Proposed API working, including retry-ability, timeouts, and integrated logging

Phase 4: Lifecycle Management and Robustness (2 months)

• Activity: Implement automatic closing of tabs opened during tests
• Deliverable: Reliable synchronization and graceful error handling

Phase 5: Polish and Release (1-2 months)

• Activity: Extensive documentation, examples, video recordings
• Deliverable: Feature released in stable Cypress version (e.g., v13.0.0)

Risk Analysis and Mitigations

Risk	Impact	Mitigation
High Technical Complexity	Project gets stuck, not completed, or introduces catastrophic bugs	Phase 1 Prototype is non-negotiable. Develop minimal viable Proof of Concept
Maintainer Rejection	All effort wasted	Phase 0 (Advocacy/RFC) is most important. Build proposal collaboratively on GitHub
Breaking Changes	New functionality breaks existing tests	API must be entirely optional. Default Cypress behavior unchanged
Performance Impact	Continuous CDP connection monitoring adds overhead	Performance benchmarks before/after. Lazy connections to tabs
Long-term Maintenance	Feature becomes burden for team	Exhaustive documentation. Follow Cypress code standards rigorously

Definition of Done

Functional Requirements

• ✅ All basic Cypress commands (cy.get, .click, .type, .should, etc.) work in any selected context (tab)
• ✅ Retry-ability and timeout system works perfectly in non-default contexts
• ✅ Tabs opened are automatically closed at test end (prevent state leakage)
• ✅ Clear and informative errors (e.g., "Target tab was closed before command completed")
• ✅ Feature works in all three supported browsers (Chromium, Firefox, WebKit)

Non-Functional Requirements

• ✅ Performance: Feature addition doesn't degrade test suite execution time by more than X%
• ✅ Tests: >90% test coverage for new code, including error scenarios
• ✅ Documentation: Complete guide published on docs.cypress.io with common examples

Release Strategy

Experimental Release

• Launch initially under feature flag: experimentalMultiTabSupport: true in cypress.config.js
• Allows enthusiast users to test in non-critical environments
• Detailed blog post announcing experimental feature, known limitations, and feedback request

Stabilization Period

• Keep feature in experimental mode for at least 1-2 major release cycles
• Only promote to stable after positive feedback and meeting Definition of Done criteria

Alternatives Considered

1. External Plugin Approach: Rejected due to fragility and limited integration with Cypress core
2. Playwright Migration: Not viable due to existing Cypress investment and team constraints
3. Workaround Solutions: Current approaches are insufficient for complex multi-tab scenarios

Conclusion

Implementing native multiple tab support is highly viable because it builds upon existing, proven infrastructure:

1. Extend existing CDP infrastructure: Target management, connection handling, and lifecycle management already implemented
2. Follow established patterns: Use cy.origin() context switching pattern for API consistency
3. Leverage proven architecture: Multiple CDP connections and state management already functional

This roadmap represents a 9-12 month investment of specialized development effort, but with significantly lower risk due to existing infrastructure. The return would be monumental: eliminating Cypress's primary competitive weakness against Playwright and empowering thousands of developers and companies with applications following this pattern.

Next Steps

1. Community Discussion: Open new GitHub discussion (not reusing closed issues) to gather feedback and use cases
2. Maintainer Engagement: Present proposal to Cypress maintainers for initial feedback
3. Proof of Concept: If approved, begin Phase 1 with minimal CDP Manager prototype
4. Iterative Development: Follow phased approach with continuous community feedback

---

Questions for Discussion:

1. Which API approach (Options 1, 2, or 3) resonates most with the community?
2. Are there additional use cases not covered in this proposal?
3. How can this feature build upon the existing cy.origin() architecture?
4. What concerns do maintainers have about the proposed architecture?
5. Would experimental release under feature flag be acceptable for initial testing?
6. Given that Issue max 1 site... support visiting multiple superdomains in one test #944 was closed with cy.origin(), how should we position this as a distinct but complementary feature?