Skip to main content

​
Overview

The Switch Tab step manages browser tabs during your test. You can create new tabs, switch between existing ones, and organize complex multi-tab workflows. Each tab maintains its own browsing context, allowing you to test scenarios that span multiple pages or windows.

​
When to Use Switch Tab

Use Switch Tab when you need to:
  • Test multi-window workflows: Verify features that open new tabs like “View in new tab” or external links
  • Compare data across pages: Switch between tabs to verify consistency or cross-reference information
  • Test separate user sessions: Create different tabs for different user roles or scenarios
  • Handle external integrations: Test flows that redirect to third-party services in new windows
  • Organize complex tests: Separate different parts of your test into named tabs for clarity

​
How It Works

Switch Tab manages browser tabs by creating named tab references you can switch between throughout your test. When you create a tab, it opens with a blank page in a new browser window. You can then navigate to your desired URL and perform actions just like in your main tab. All subsequent steps execute in whichever tab is currently active. Switching tabs changes which browser window receives your test actions, letting you move between different pages or contexts seamlessly.

​
Using the Switch Tab Step

When you add a Switch Tab step, you’ll see:

​
Managing Existing Tabs

Your currently available tabs appear as clickable buttons, each showing its assigned name. Each tab gets an automatically assigned color for visual distinction. Click any tab button to switch to that tab - all following steps will execute there.

​
Creating New Tabs

To create a new tab:
  1. Enter a descriptive name in the “New Tab Name” field
  2. Click “Add New Tab” or press Enter
  3. The new tab is created and automatically becomes the active tab

​
Editing Tab Names

Click the edit icon next to any tab name to rename it. Use names that reflect the page content or purpose to keep your test organized.

​
Real-World Examples

Step 1: Navigate
  URL: /blog/latest-post

Step 2: Click
  Locator: a[target='_blank'][href*='external-site.com']

Step 3: Switch Tab
  Tab: Create new tab "External Site"

Step 4: Wait for Element
  Locator: .external-site-header

Step 5: Check URL
  Pattern: external-site.com

Step 6: Switch Tab
  Tab: Select existing tab "Main"
Why this works: Click a link that opens a new tab, switch to verify the external site loads, then return to your original tab.

​
Comparing User Dashboards

Step 1: Navigate
  URL: /dashboard

Step 2: Extract Value
  Locator: .total-revenue
  Variable Name: revenueAmount

Step 3: Switch Tab
  Tab: Create new tab "Admin View"

Step 4: Navigate
  URL: /admin/analytics

Step 5: Check Text
  Locator: .aggregated-revenue
  Use variables: revenueAmount
  Assertion: Element has text
Why this works: Extract data from one view, switch to another tab to verify the data appears consistently.

​
Multi-User Testing Scenario

Step 1: Navigate
  URL: /login

Step 2: Fill
  Locator: input[name='email']
  Text: {{USER_1_EMAIL}}

Step 3: Click
  Locator: button[type='submit']

Step 4: Switch Tab
  Tab: Create new tab "User 2 Session"

Step 5: Navigate
  URL: /login

Step 6: Fill
  Locator: input[name='email']
  Text: {{USER_2_EMAIL}}

Step 7: Click
  Locator: button[type='submit']

Step 8: Switch Tab
  Tab: Select existing tab "Main"
Why this works: Test interactions between different user sessions by maintaining separate tabs for each user.

​
OAuth or Third-Party Integration

Step 1: Click
  Locator: button[data-action='connect-google']

Step 2: Switch Tab
  Tab: Create new tab "Google Auth"

Step 3: Wait for Element
  Locator: input[type='email']

Step 4: Fill
  Locator: input[type='email']
  Text: {{TEST_GOOGLE_EMAIL}}

Step 5: Click
  Locator: button[type='submit']

Step 6: Switch Tab
  Tab: Select existing tab "Main"

Step 7: Check Visibility
  Locator: .google-connected-badge
  Assertion: Is visible
Why this works: Handle OAuth flows that open in new windows by switching tabs to complete authentication.

​
Best Practices

​
Name Tabs Descriptively

Choose clear, meaningful names that reflect what’s in each tab:
  • ✅ “Login Page”, “Admin Dashboard”, “Checkout Flow”
  • ❌ “Tab 1”, “New Window”, “Test”
Good names make your test easier to understand and maintain.

​
Plan Your Tab Strategy

Before creating tabs, think about:
  • Which parts of your test need separate browser contexts?
  • When do you need to switch between tabs?
  • What order makes sense for tab creation?
  • How will you track which content is in which tab?

​
Switch Before Acting

Always switch to the correct tab before performing actions:
  • Review which tab is active before adding steps
  • Switch tabs explicitly rather than assuming context
  • Use descriptive tab names to avoid confusion about which tab you’re in

​
Keep Tab Count Reasonable

While you can create multiple tabs, consider:
  • Each tab uses memory and resources
  • Too many tabs can make tests harder to follow
  • Most tests need 2-3 tabs at most
  • Close or reuse tabs when possible for cleaner tests

​
Troubleshooting

​
Forgot Which Tab Is Active

Symptom: Actions happen in the wrong tab Solution:
  • Always add an explicit Switch Tab step before actions in a specific tab
  • Use descriptive tab names to track context
  • Review your test flow to understand tab switching order
  • Add comments or clear step descriptions about which tab you’re targeting

​
New Tab Doesn’t Have Expected Content

Symptom: Switched to new tab but page is blank or wrong Solution:
  • Remember: new tabs start blank - add a Navigate step after creating them
  • If a link opened the tab, the content should already be there
  • Check that external links actually open in new tabs (target="_blank")
  • Verify the tab creation happened before you try to interact with it

​
Lost Track of Tab Names

Symptom: Can’t remember what content is in which tab Solution:
  • Use the tab name editing feature to update names as your test evolves
  • Choose names that reflect current page content
  • Add step descriptions explaining tab purpose
  • Keep a mental model of your tab organization

​
Browser Popup Blockers

Symptom: New tabs don’t open during test execution Solution:
  • Ensure your test runner environment allows popups
  • Check browser settings for popup blocking
  • Verify your application code uses valid methods to open new windows
  • Test manually to confirm tabs open correctly outside of automation

​
Performance Issues

Symptom: Test slows down with multiple tabs Solution:
  • Close unnecessary tabs or reuse existing ones
  • Limit the number of tabs open simultaneously
  • Consider if all tabs are necessary for your test
  • Check system resources if running many parallel tests

​
Tab Lifecycle

​
Creating Tabs

When you create a tab:
  • It opens with a blank page
  • Use Navigate to load content
  • The new tab automatically becomes the active tab
  • Tab names can be edited anytime

​
Switching Tabs

When you switch tabs:
  • The selected tab becomes active
  • All subsequent steps execute in that tab
  • Browser focus moves to the selected tab
  • Content and state persist from previous interactions

​
Tab Persistence

Throughout your test:
  • Tabs remain available for the entire test session
  • Each tab maintains its own page state
  • Cookies, localStorage, and session data are separate per tab
  • The test runner automatically manages tab lifecycle
  • Navigate - Load content in tabs after creation
  • Check URL - Verify URLs in specific tabs
  • Click - Often used before switching tabs for links that open new windows
  • Wait for Element - Wait for content to load after switching tabs