@testperch/playwright

Playwright Test integration for TestPerch.

Use this package to:

• report Playwright runs, tests, steps, output, and attachments to TestPerch
• exclude remotely quarantined tests from CI runs
• run only previously failed or flaky tests during CI build retries

Installation

pnpm add -D @testperch/playwright @playwright/test

@playwright/test is a peer dependency. If Playwright is already installed in your project, install only @testperch/playwright.

Credentials

Create a TestPerch API key for your project and expose these values to Playwright:

• TESTPERCH_API_KEY
• TESTPERCH_URL

The reporter does not load .env files. Load environment variables in your Playwright config or a shared config module before creating the reporter options.

// testperch.config.ts
import type { TestPerchConnectionOptions } from "@testperch/playwright";

function requiredEnv(name: string) {
	const value = process.env[name];

	if (!value) {
		throw new Error(`${name} is required.`);
	}

	return value;
}

export const testPerchConfig = {
	apiKey: requiredEnv("TESTPERCH_API_KEY"),
	url: requiredEnv("TESTPERCH_URL"),
} satisfies TestPerchConnectionOptions;

Report Playwright Results

Add the TestPerch reporter to playwright.config.ts.

import { defineConfig } from "@playwright/test";
import { testPerchReporter } from "@testperch/playwright";

import { testPerchConfig } from "./testperch.config";

export default defineConfig({
	reporter: [["html", { open: "never" }], testPerchReporter(testPerchConfig)],
});

Run Playwright normally. The reporter sends results to TestPerch as the run executes. Each event is retried once for transient network failures, request timeouts, 408, 429, and 5xx responses.

pnpm exec playwright test

Remote Test Exclusions

The reporter automatically applies TestPerch quarantine and failed-only retry behavior before Playwright shards or runs the discovered suite. Excluded tests do not execute and do not appear in Playwright reports or TestPerch ingestion.

CI logs include the number of failed/flaky matches, quarantine exclusions and branch exceptions, and the final number of test cases that remain after filtering.

Tests continue to import test and expect directly from @playwright/test.

Local runs always execute quarantined tests. In CI, quarantined tests are excluded unless the quarantine allows the detected branch. Branch matching is exact and case-sensitive.

A quarantine matches tests by project-relative file path and Playwright title path, so it applies across Playwright projects and browsers.

When a CI build ID is available, failed-only retries are enabled by default. TestPerch looks up completed runs with the same CI build ID and runs only tests with a failed, timed-out, interrupted, or unreported attempt, including tests that later recovered and became flaky. If no completed source run exists yet, all tests run normally. If completed source runs had no failures, the retry run excludes every test and completes successfully.

If a remote quarantine or failed-test lookup fails, the reporter logs a warning and lets tests run.

Disable failed-only retry filtering with:

reporter: [
	testPerchReporter({
		...testPerchConfig,
		onlyRunFailedTestsForCiBuildRetries: false,
	}),
];

CI Metadata

GitHub Actions metadata is detected automatically from native GitHub environment variables:

• CI status from GITHUB_ACTIONS
• attempt from GITHUB_RUN_ATTEMPT
• branch from GITHUB_HEAD_REF or GITHUB_REF_NAME
• CI build ID from GITHUB_RUN_ID
• git SHA from GITHUB_SHA
• pull request number from GITHUB_EVENT_PATH or GITHUB_REF

Run attempts are one-based. GitHub's first GITHUB_RUN_ATTEMPT value is 1, and the reporter passes it through unchanged. Explicit attempt values lower than 1 are ignored.

For non-GitHub CI providers or custom environment variable names, pass explicit metadata:

testPerchReporter({
	...testPerchConfig,
	attempt: process.env.CI_ATTEMPT ? Number(process.env.CI_ATTEMPT) : undefined,
	branch: process.env.GIT_BRANCH,
	ciBuildId: process.env.CI_BUILD_ID,
	ciProvider: process.env.CI_PROVIDER,
	gitSha: process.env.GIT_SHA,
});

Options

| Option | Description | | ------------------------------------- | ---------------------------------------------------------------------------------- | | apiKey | Required TestPerch project API key. | | url | Required TestPerch app URL. | | attempt | One-based CI attempt number. Defaults to 1 when no CI value is detected. | | branch | Branch name for run metadata and quarantine branch matching. | | ci | Whether the run is executing in CI. Defaults to detected CI environment variables. | | ciBuildId | CI build identifier used for run grouping and failed-only retries. | | ciProvider | CI provider name, such as github-actions. | | gitAuthor | Explicit author metadata for the run. | | gitSha | Commit SHA for the run. | | pullRequestNumber | Pull request number for the run. | | runId | UUID v7 run ID. Generated automatically when omitted. | | shardIndex / shardTotal | One-based positive shard metadata when reporting a sharded Playwright run. | | requestTimeoutMs | Timeout for TestPerch API requests. Defaults to 10000. | | attachmentUploadTimeoutMs | Timeout for attachment uploads. Defaults to 30000. | | onlyRunFailedTestsForCiBuildRetries | Set to false to disable failed-only retry behavior. |

Advanced Contract Exports

Most Playwright projects should use the main package exports shown above. Advanced integrations that need to validate TestPerch Playwright payloads can import schemas and types from @testperch/playwright/contract.