Running Playwright in remote browsers with Docker

When working with Playwright, there are times when you need to run your tests in a remote environment, such as a Docker container or a CI/CD pipeline. This can be useful for visual regression testing or when you need to isolate your test environment.

In this post, we'll explore how to run Playwright browsers using Docker and WebSocket connections.

Setting up the Docker environment

First, let's look at how to set up a Docker container that can run Playwright browsers. We'll need to:

• Run a Docker container with the necessary dependencies
• Expose port for WebSocket connections
• Run the server script the server to launch the browsers

We will need a some files to make this work, and this will be divided into two parts:

The first part will be our playwright configuration that we will need in order to connect to the server (or the docker container running locally.):

We need to define where we want playwright to connect, so we will define the following constant:

// playwright.config.ts
const WS_SERVER = 'ws://127.0.0.1:3000';
// ...

Now, we need to extend our playwright configuration, and define some new projects which will be the ones to connect to docker.

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

const WS_SERVER = 'ws://127.0.0.1:3000';

export default defineConfig({
    // ...
    projects: [
        {
            name: 'chromium-docker',
            browserName: 'chromium',
            use: {
                ...devices['Desktop Chrome'],
                connectOptions: {
                    wsEndpoint: WS_SERVER,
                },
            },
        },
        {
            name: 'firefox-docker',
            browserName: 'firefox',
            use: {
                ...devices['Desktop Firefox'],
                connectOptions: {
                    wsEndpoint: WS_SERVER,
                },
            },
        },
        {
            name: 'webkit-docker',
            browserName: 'webkit',
            use: {
                ...devices['Desktop Safari'],
                connectOptions: {
                    wsEndpoint: WS_SERVER,
                },
            },
        },
    ],
});

Now that we have the setup, we simply need to start the server inside the docker container, to do that we will run this command:

docker run --add-host=host.docker.internal:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.51.1-noble /bin/sh -c "npx -y [email protected] run-server --port 3000 --host 0.0.0.0"

The command has so many things so lets explain them. First, if you need to be able to connect from the container to your local server, you will use the flag --add-host=host.docker.internal:host-gateway. Then, -p 3000:3000 here you can define the ports of your choice, just remember [your-local-port]:[container:port].

We also need to be careful regarding the version, make sure that the playwright version you are using, is the same as the one you will be using in your tests, otherwise it won't work.

From this script npx -y [email protected] run-server --port 3000 --host 0.0.0.0 you can also modify as needed.

Now that we have our playwright server running, we can simply run our tests, for example, by running in chromium-docker.

To do that, we can run the following script

npx playwright test --project chromium-docker

This will now run our tests inside the docker container, emulating the CI environment.

And that's all! Now you know how to run your tests inside a docker container!