Skip to main content

Selenium Grid

Playwright can connect to Sauce Labs remotely via its Selenium Grid support to launch the Google Chrome or Microsoft Edge browser.

Playwright connects to the browser using the Chrome DevTools Protocol (CDP). Selenium 4 currently exposes this capability.

note

Playwright support via Selenium Grid utilizes the Chrome DevTools Protocol (CDP). While this provides immediate compatibility, we are actively developing a native WebSocket integration for enhanced performance. For the most reliable experience today, follow the guidelines shown below.

What You'll Need​

  • A Sauce Labs account (if you don't have one, start a free trial)
  • Your Sauce Labs Username and Access Key
  • Playwright installed in your project
  • Supported browsers: Google Chrome or Microsoft Edge

Connect Playwright to Sauce Labs​

Playwright can connect to Sauce Labs using environment variables or direct configuration in your test code. The recommendations below demonstrate both approaches across multiple programming languages.

We have crafted code setups and fixtures that will improve how your Playwright tests perform and look on Sauce Labs. These examples include best practices that help you get more information from your tests, making them easier to debug. The enhanced test metadata, proper configuration, and structured approach ensure better visibility into test execution and results in the Sauce Labs dashboard.

The following examples demonstrate how to configure Playwright to connect to Sauce Labs in different programming languages.

We recommend using the following fixture, which can run your tests locally or on Sauce Labs. The fixture extends Playwright's test to swap the page fixture for a Sauce Labs remote page.

The fixture builds the Sauce session capabilities and metadata (name, build). You can tweak the capabilities to fit your needs in terms of browser, platform, and other options.
Sauce Session Capabilities and Metadata
loading...
The fixture also helps creating and tearing down the remote Sauce session, updating the job status based on the test result. The fixture also logs a direct link to the job in the Sauce Labs UI. Your test code remains unchanged as they use the same page API locally and on Sauce.

To use the fixture, place it in your project and import it in your test files:
Sauce Session Capabilities and Metadata
loading...
You can see the full fixture code in our demo repository. For complete working examples and setup instructions, visit our JS/TS Demo Repository.

Using Environment Variables​

Set the SELENIUM_REMOTE_URL and SELENIUM_REMOTE_CAPABILITIES environment variables to connect Playwright to Sauce Labs:

export SELENIUM_REMOTE_URL=https://ondemand.us-west-1.saucelabs.com:443/wd/hub
export SELENIUM_REMOTE_CAPABILITIES='{"platformName":"Windows 11","browserName":"chrome","sauce:options":{"devTools":true,"username":"'$SAUCE_USERNAME'","accessKey":"'$SAUCE_ACCESS_KEY'"}}'
npx playwright test --headed --project "chromium"

Best Practices​

tip

If you're using our recommended fixtures/extensions, many of these best practices are already implemented for you, including test metadata, session management, and job status updates.

Use Headed Mode​

Playwright must run in headed mode for Sauce Labs to capture video recordings. Ensure your test configuration or command includes the headed flag:

npx playwright test --headed

Set Meaningful Test Metadata​

Always include descriptive test names and build identifiers to make results easier to find and debug:

"sauce:options": {
  "name": "Login Flow - Valid Credentials",
  "build": "build-2024-01-15-abc123",
  "tags": ["playwright", "login", "smoke"]
}

Limitations​

Due to the nature of CDP-based communication, there are some limitations when running Playwright via Selenium Grid:

  • Command Display: The commands shown in the Sauce Labs UI may differ from what you typically see when running Playwright locally, this is because the browser communicates with Playwright via CDP. Rest assured that your test is still running successfully and every command is being executed properly. We're actively working on improving how Playwright commands are displayed.

  • Browser Support: Only Google Chrome and Microsoft Edge are supported, as they provide CDP endpoints.

  • Headed Mode Required: Tests must run in headed mode for video capture to work.

Additional Resources​