Playwright

@testflake/playwright is the testflake CLI — a wrapper around the command you already run, which asks TestFlake which tests belong to the current shard and reports back how long each one took.

As with the PHPUnit integration there is no reporter or extension to add: Playwright’s own JSON report already carries a row per attempt, and the wrapper reads what it reports out of that. Nothing is recorded by installing the package alone — the CLI is what talks to TestFlake.

Requirements

Node 18 or later, and Playwright 1.40 or later. @playwright/test is a peer dependency, so the package uses whichever version your project already has and stays out of your version constraints.

1. Install the package

   npm

   npm install --save-dev @testflake/playwright

   pnpm

   pnpm add -D @testflake/playwright

   yarn

   yarn add --dev @testflake/playwright

2. Point the client at your project. TESTFLAKE_KEY attributes the run; TESTFLAKE_HOST is the API to talk to. Wrap the command you already run.

   npm

   TESTFLAKE_KEY=your-key TESTFLAKE_HOST=https://app.testflake.com \
     npx testflake npx playwright test

   pnpm

   TESTFLAKE_KEY=your-key TESTFLAKE_HOST=https://app.testflake.com \
     pnpm testflake pnpm playwright test

   yarn

   TESTFLAKE_KEY=your-key TESTFLAKE_HOST=https://app.testflake.com \
     yarn testflake yarn playwright test

   That is enough to start recording durations. Nothing is sharded yet — the run has no --shard, so it joins as a single shard holding the whole suite. The next section is what splits it.

Sharding across CI machines

Pass --shard as you normally would; TestFlake decides which tests belong to which shard, by how long each one took on earlier runs.

npm

TESTFLAKE_KEY=your-key npx testflake npx playwright test --shard=2/8

pnpm

TESTFLAKE_KEY=your-key pnpm testflake pnpm playwright test --shard=2/8

yarn

TESTFLAKE_KEY=your-key yarn testflake yarn playwright test --shard=2/8

--shard is consumed by the wrapper and never reaches Playwright — it must not, or the suite would be split twice: once by TestFlake and again by Playwright’s own sharding, leaving most tests unrun.

Put Playwright options in the config file, not on the command line

The wrapper re-issues everything up to and including the test argument, plus its own selection flags. Anything you add after test is read for --shard and then dropped:

# --project and --workers are silently discarded
npx testflake npx playwright test --project=chromium --workers=4

Set projects and workers in playwright.config.ts instead, or run separate wrapped commands per project.

--reporter is the one option that behaves the other way round. The wrapper has to pass one — the JSON report is where it reads the run from — and Playwright’s flag replaces the list in your config rather than adding to it. So a reporter list in playwright.config.ts is not used on a wrapped run. Pass it on the command line and it is kept, with json added:

# runs dot and json; passing none gets Playwright's own default plus json
npx testflake npx playwright test --reporter=dot

The first run has no timing data and falls back to an alphabetical split. From the second run on, shards are balanced by recorded duration.

Sharding happens at spec level: a spec that runs under several projects stays whole, because Playwright’s -g cannot express “this title, but only in chromium”.

Setting it up in CI

Every shard of one run has to agree on a run id, or each becomes its own pipeline holding the whole suite. On GitLab that is automatic; elsewhere you pass it.

Complete pipelines for GitLab CI, GitHub Actions, CircleCI, Jenkins and Travis are in Continuous integration.

Environment variables

Variable	Default	Purpose
TESTFLAKE_KEY	—	Attributes runs to a project. Treat as a credential.
TESTFLAKE_HOST	—	API base URL.
TESTFLAKE_RUN_ID	detected on GitLab and GitHub	Ties the shards of one run together.
TESTFLAKE_BRANCH	detected on GitLab and GitHub	Branch the run belongs to.

When TestFlake is unreachable

Your build still passes. Any failure — an unreachable host, a non-2xx response, a malformed body — makes the client warn on stderr and run the entire suite, unsharded, exactly as if the wrapper were not there. You get a slow build, never a red one, and the exit code is always Playwright’s own.