Skip to content

Testcontainers ​

Turn on container for a backend and Stagehand starts it in a throwaway Docker container from the test run itself, using Testcontainers. There's no services: block in CI and no docker compose up before running tests: the same command works on a laptop and on any CI agent that has Docker.

bash
PW_DB_CONTAINER=true PW_KAFKA_CONTAINER=true npx playwright test --project=integration

Supported: PostgreSQL, MySQL, MSSQL, Redis, MongoDB, Neo4j, Kafka, Mailpit (the inbox mail server) and WireMock (the mock server). SQLite needs no server.

Setup ​

  1. Docker, or any Docker-compatible runtime (Docker Desktop, Colima, Podman with its Docker socket, Rancher Desktop). Testcontainers finds it the same way the docker CLI does, including DOCKER_HOST.

  2. The testcontainers package, an optional peer dependency like the drivers:

    bash
    npm install --save-dev testcontainers
  3. Turn it on per backend, with an environment variable or in config:

    bash
    PW_DB_CONTAINER=true          # databaseClient (PostgreSQL, MySQL or MSSQL: PW_DB_TYPE picks)
    PW_REDIS_CONTAINER=true       # redisClient
    PW_MONGODB_CONTAINER=true     # mongoDbClient
    PW_NEO4J_CONTAINER=true       # neo4jClient
    PW_KAFKA_CONTAINER=true       # kafkaClient
    PW_INBOX_CONTAINER=true       # inboxClient (Mailpit; inboxClient.smtp has its SMTP host and port)
    PW_MOCK_CONTAINER=true        # mockServer (WireMock; mockServer.url is its address)

    A value other than true/false is used as the image, e.g. PW_DB_CONTAINER=postgres:16-alpine.

    jsonc
    // environments.json
    {
        "environments": {
            "local": {
                "database": { "type": "postgresql", "database": "app", "container": { "initScripts": ["db/schema.sql"] } },
                "redis": { "host": "", "port": 6379, "container": true },
                "kafka": { "brokers": [], "container": { "image": "apache/kafka:3.9.0" } }
            }
        }
    }

When container is on, host, port, uri and brokers are ignored: the fixture connects to the container. Everything else in the config still applies.

How it works ​

  • One container per backend per worker. A container starts the first time a test in a Playwright worker uses the fixture. The worker's later tests share it, and it stops when the worker exits. A test that doesn't use a fixture never starts its container.
  • Ready means healthy. Each container uses the same image and health check as Stagehand's CI and compose.test.yaml, so tests start only once the service accepts connections. For databases, that's after the init scripts have run.
  • Random ports. Containers get free host ports, so parallel workers, parallel CI jobs and anything else on your machine don't collide.
  • Nothing left behind. Containers are removed when the worker exits. If the process crashes, Testcontainers' cleanup container (Ryuk) removes them.

With 4 workers, a backend runs in 4 containers, one per worker, so tests in different workers don't share data. Lower workers in a project's projects.ts if a heavy image (MSSQL, Neo4j) strains the machine.

Options ​

container takes true, or an object:

OptionDefaultWhat it does
imageSee the table belowImage to run
initScriptsnoneSQL files run once after the database starts, in order (PostgreSQL, MySQL, MSSQL). Paths are relative to the working directory
startupTimeout60 (120 for MSSQL and Neo4j)Seconds to wait for the health check
reusefalseKeep the container running between runs and reuse it (Testcontainers' reuse mode; also set TESTCONTAINERS_REUSE_ENABLE=true). Not available for Kafka
BackendDefault imageCredentials used
PostgreSQLpostgres:15The config's database/username/password, or testdb/testuser/testpass
MySQLmysql:8.0Same as PostgreSQL; username: root sets the root password instead
MSSQLmcr.microsoft.com/mssql/server:2022-latestsa with the config's password (it must meet SQL Server's policy), or TestPass123!. A non-master database is created for you
Redisredis:7The config's password, if set
MongoDBmongo:7A root user when the config sets username; otherwise no auth
Neo4jneo4j:5neo4j with the config's password (8+ characters), or testpassword
Kafkaapache/kafka:latestSingle KRaft broker, no auth
WireMockwiremock/wiremock:3.13.2No auth; stubs and admin API on one port, mockServer.url
Mailpitaxllent/mailpit:latestNo auth; SMTP on a second mapped port, exposed as inboxClient.smtp

Schema and seed data ​

Databases start empty. Give them a schema with initScripts, or with PW_DB_CONTAINER_INIT (comma-separated) when using variables:

bash
PW_DB_TYPE=postgresql PW_DB_CONTAINER=true PW_DB_CONTAINER_INIT=db/schema.sql,db/seed.sql npx playwright test

PostgreSQL and MySQL run the scripts with their image's /docker-entrypoint-initdb.d. MSSQL runs them with sqlcmd against the configured database.

In CI ​

No services: block, and no container job: run on a VM runner that has Docker, which GitHub's ubuntu-latest does.

yaml
test-integration:
  runs-on: ubuntu-latest
  env:
    CI: true
    PW_DB_TYPE: postgresql
    PW_DB_CONTAINER: "true"
    PW_DB_CONTAINER_INIT: db/schema.sql
    PW_KAFKA_CONTAINER: "true"
    PW_REDIS_CONTAINER: "true"
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with: { node-version: "24" }
    - run: npm ci
    - run: npx playwright test --project=integration

The same works on GitLab (a Docker-in-Docker service, or a shell runner with Docker), Jenkins agents with Docker, Azure Pipelines and CircleCI machine executors, and Bitbucket with the docker service. See Testcontainers' CI guides for each system's Docker settings.

Stagehand's own CI runs every example suite this way in the test-testcontainers job, next to the service-container jobs.

Troubleshooting ​

SymptomCause and fix
MissingPackageError for testcontainersRun npm install --save-dev testcontainers
... is Docker running?Testcontainers can't reach a Docker runtime. Start it, or set DOCKER_HOST
... never became healthyThe service exited at start-up, usually because of credentials. Run the image by hand with the same settings and read docker logs
password is too weak for the SQL Server containerAn environment's config sets a simple password (like test). Set a stronger PW_DB_PASSWORD, or remove it to use the default
Kafka tests time out on a remote Docker hostThe broker advertises the Docker host's address. Make sure the tests can reach it on the mapped port
Slow first runImages are being pulled. Later runs reuse them; reuse: true also keeps containers running between runs

Released under the MIT License.