> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/resources/reporters/currents-playwright/configuration.md).
# Configuration
@currents/playwright configuration reference
## Configuration Sources
`@currents/playwright` accepts configuration from the following sources:
* **⭐️ Preferred:** reading `currents.config.ts` file
* Environment variables, e.g. `CURRENTS_TAG=tagA,tagB`
* CLI command options, e.g. `npx pwc ---tag tagA --tag tagB`
* Inline configuration in `playwright.config.ts` e.g. `reporters: [currentsReporter(options)]`
{% hint style="success" %}
We recommend using `currents.config.ts` as the preferred method for defining the configution — the file is evaluated at runtime, i.e. you can make is smart.
For example:
```typescript
import { OrchestrationStatus, CurrentsConfig } from "@currents/playwright";
function getCIBuildId() {
return "example";
}
const onFinish = async (result: OrchestrationStatus) => {
console.log("Orchestration finished with status", result);
};
const config: CurrentsConfig = {
recordKey: process.env.CURRENTS_RECORD_KEY || throw new Error("oh no!"),
projectId: process.env.CURRENTS_PROJECT_ID,
ciBuildId: getCIBuildId(),
orchestration: {
skipReporterInjection: true,
onFinish,
},
};
export default config;
```
{% endhint %}
### Configuration Overrides
Configuration values will resolve as follows:
* environment variable value if exists, otherwise
* corresponding CLI parameter value if exists, otherwise
* value from `playwright.config.ts` if exists, otherwise
* value from `currents.config.ts` if exists, otherwise
* the default value, otherwise
* throw if the value is mandatory
Example of using environment variables
{% tabs %}
{% tab title="Linux" %}
```javascript
CURRENTS_PROJECT_ID=PROJECT_ID \ // the projectId from https://app.currents.dev
CURRENTS_RECORD_KEY=RECORD_KEY \ // the record key from https://app.currents.dev
CURRENTS_CI_BUILD_ID=hello-currents \ // the CI build ID
CURRENTS_TAG=tagA,tagB \
npx playwright test
```
{% endtab %}
{% tab title="Windows" %}
```typescript
cmd /V /C "set CURRENTS_PROJECT_ID=PROJECT_ID // the projectId from https://app.currents.dev
&& set CURRENTS_RECORD_KEY=RECORD_KEY // the record key from https://app.currents.dev
&& set CURRENTS_CI_BUILD_ID=hello-currents // CI build id
&& set CURRENTS_TAG=tagA,tagB // tags for the created run
&& npx playwright test"
```
{% endtab %}
{% endtabs %}
## Reference
### ciBuildId \*
* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_CI_BUILD_ID`
Required. The ID of the build to associate the test run with. See [CI Build ID](/guides/parallelization-guide/ci-build-id.md).
***
### projectId \*
* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_PROJECT_ID`
Required. The Currents project ID used for reporting. See [Projects](/dashboard/projects.md).
***
### recordKey \*
* Type: `string`
* Default: *Required*
* Environment variable: `CURRENTS_RECORD_KEY`
Required. Secret key used to authenticate and upload results to Currents. See [Record Key](/guides/record-key.md).
***
### tag
* Type: `string[]`
* Default: `[]`
* Environment variable: `CURRENTS_TAG=tagA,tagB`
Tags added to the test run metadata. See [Playwright Tags](/guides/playwright-tags.md).
***
### environment
* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_ENVIRONMENT`
* CLI option: `--pwc-environment`
* Released in: `2.1.0`
Run-level environment label (e.g. `staging`, `production`) attached to the recorded run for filtering and analytics. Override it per Playwright project with `projects[].metadata.pwc.environment` in `playwright.config.ts`. See [Environments](/guides/environments.md).
***
### removeTitleTags
* Type: `boolean`
* Default: `false`
* Environment variable: N/A
Remove inline tags like `@smoke` from test titles when processing test results on Currents servers. Helps to keep the test title consistent and keep test history when tags change.
***
### disableTitleTags
* Type: `boolean`
* Default: `false`
* Environment variable: `CURRENTS_DISABLE_TITLE_TAGS`
Prevent parsing tags like @smoke from test titles.
***
### disableTestTags
* Type: `boolean`
* Default: `false`
* Environment variable: `CURRENTS_DISABLE_TEST_TAGS`
Prevent reporting tags parsed from test title and the conventional [Playwright Tags](https://playwright.dev/docs/test-annotations#tag-tests) that appear in test definitions.
***
### cancelAfterFailures
* Type: `number | false`
* Default: `false`
* Environment variable: `CURRENTS_CANCEL_AFTER_FAILURES`
Stop the run after a number of failures. The number of failures is determined from all the results reported to the associated run (i.e. from multiple machines). Pass false to disable. See [Failing Fast](/guides/ci-optimization/fail-fast-strategy.md).
***
### testSuiteFile
* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_TEST_SUITE_FILE`
Full path to the test suite file used for orchestration and reporting. Mostly used internally.
***
### machineId
* Type: `string`
* Default: a generated id, one per reporter process
* Environment variable: `CURRENTS_MACHINE_ID`, which takes precedence over this option
Identifies the process that reports the run — one CI job, or one `--shard` of one. The reporter generates an id for each process it runs in, so shards and parallel jobs are already counted apart without setting this.
Set it to a name you recognise, such as the runner or job name, and the dashboard shows that name for every spec file the machine ran. See [Named Runners](/getting-started/ci-setup/github-actions/named-runners.md) for a GitHub Actions example.
Give each CI job its own value. Two jobs sharing one id are counted as a single machine, which distorts the machine count and the busy time reported for the run.
***
### orchestrationId
* Type: `string`
* Default: Auto-generated
* Environment variable: `CURRENTS_ORCHESTRATION_ID`
Unique orchestration ID for the run. Mostly used internally.
***
### outputFile
* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_OUTPUT_FILE`
File path for the JSON output summary. The TypeScript definition of the contents is available:
```typescript
import type { ExecutionJSONSummary } from '@currents/playwright'
```
***
### ciUrl
* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_CI_URL`
* Released in: `2.1.3`
Overrides or provides the CI job/run URL shown in the [Run Details](/dashboard/runs/run-details.md). By default Currents auto-detects the CI URL from your provider's environment variables (GitHub Actions, GitLab CI, CircleCI, Jenkins, etc.). Set this to override the auto-detected URL, or to supply one when auto-detection is unavailable (e.g. Docker containers, custom runners, or self-hosted CI).
{% hint style="info" %}
Whitespace is automatically trimmed. If the value is empty or contains only whitespace, it is ignored.
{% endhint %}
***
### consoleOutput
* Type: `none | summary | compact | detailed`
* Default: `detailed`
* Environment variable: `CURRENTS_CONSOLE_OUTPUT`
What the reporter prints to the console:
* `none`: nothing.
* `summary`: the intro, one line per test, and the end-of-run summary. It doesn't print test stdout or stderr.
* `compact` (released in `2.6.0`): the same as `summary`, plus the error of each failed or interrupted test, printed once under its line. The error comes from the last attempt that has one; when that isn't the final attempt, an `attempt N error` line names it. A retried test's line shows how many attempts it took, and a flaky test's line is marked `flaky`.
* `detailed`: a start line and a result block for every test attempt, plus each test's stdout and stderr as the test prints it. The result block has the recording URL, the expected result, each attempt's status and duration, the test result once the last attempt ends, and the errors. After each attempt of a retried test, the block prints the errors of all its attempts so far.
Use `compact` when retries make the CI log hard to read. A test that fails all 3 attempts prints its error 6 times with `detailed` and once with `compact`. The example below is the compact output of a test that fails all 6 attempts:
```
failed [chromium] › a.spec.ts:3:5 › Test A (6 attempts)
Error: expect(received).toBe(expected) // Object.is equality
Expected: false
Received: true
2 |
3 | test("Test A", async ({ page }, { retry }) => {
> 4 | expect(true).toBe(false);
| ^
5 | });
6 |
at examples/retries/a.spec.ts:4:16
```
The TypeScript definition of the configuration property is available:
```typescript
import type { ConsoleOutputPreset } from '@currents/playwright'
```
***
### orchestration
Set of configuration items related to [Orchestration Setup](/guides/ci-optimization/playwright-orchestration.md).
#### orchestration.resetSignal
* Type: `SIGUSR1 | SIGUSR2`
* Default: `undefined`
* Environment variable: N/A
Signal used to reset the tests running on the machine. See [Cloud Spot Instances](/guides/ci-optimization/ci-tests-on-spot-instances.md).
#### orchestration.skipReporterInjection
* Type: `boolean`
* Default: `false`
* Environment variable: N/A
Prevents `pwc-p` from automatically configuring Playwright to use Currents reporter . If see, you must add Currents reporter manuall. See [Orchestration Setup](/guides/ci-optimization/playwright-orchestration.md).
#### orchestration.onFinish
* Type: `(status: OrchestrationStatus) => Promise`
* Default: `undefined`
* Environment variable: N/A
Optional async callback called after orchestration completes. The callback runs on each machine that is part of an orchestrated run. The parameter `status` contains aggregated results from all the participating machines. The TypeScript definition of the contents is available:
```typescript
import type { OrchestrationStatus } from "@currents/playwright";
```
#### orchestration.batchSize
* Type: `"auto" | number`
* Default: `auto`
* Environment variable: `CURRENTS_BATCH_SIZE`
* Released in: `1.13.0`
Sets the batch size for orchestration. Batch size defines how many parallel lanes the orchestrator fills per machine.
* `auto` infers the batch size from Playwright workers.
* `number` explicitly sets the batch size, must be greater than `0`
{% hint style="warning" %}
Batch size is the number of parallel lanes the orchestrator fills for the requesting machine — not a hard cap on how many spec files the machine claims. With a batch size of 2 or more, the orchestrator packs the heaviest spec plus additional lighter specs into one claim, so a machine can pick up more files than the batch size. A value of `1` claims exactly one file per request. See [Orchestration and Multiple Workers](/guides/ci-optimization/playwright-orchestration.md).
{% endhint %}
{% hint style="info" %}
Defining this variable will override any project-level batch size/workers definition in `playwright.config.ts` (`workers`, `currentsBatchSize` per project). Available on `@currents/playwright` starting at version `1.14.0`.
{% endhint %}
#### orchestration.createTimeoutMs
* Type: `number`
* Default: `60000` (60 seconds)
* Environment variable: `CURRENTS_OR8N_CREATE_TIMEOUT_MS`
* Released in: `2.5.0`
Milliseconds to wait for orchestration session creation during `pwc-p run`. This timeout covers the discovery phase (`playwright test --list`) and Currents session creation.
For large test suites with thousands of spec files, the default 60-second timeout may be insufficient. Increase this value if you encounter `Failed to start orchestration within 60000ms` errors during orchestration startup.
**Example:**
```typescript
// currents.config.ts
export default {
orchestration: {
createTimeoutMs: 300000, // 5 minutes for large test suites
},
};
```
{% hint style="info" %}
This timeout only affects the initial orchestration session setup. It does not impact individual test execution timeouts or the `orchestration.pendingChildExitTimeoutMs` setting.
{% endhint %}
#### orchestration.pendingChildExitTimeoutMs
* Type: `number`
* Default: `undefined`
* Environment variable: `CURRENTS_OR8N_PENDING_CHILD_EXIT_TIMEOUT_MS`
Maximum time (in milliseconds) to wait for pending Playwright child processes to exit after orchestration has finished. Once the timeout expires, the parent process sends **SIGTERM** to any remaining child processes. If a process is still running **5 seconds later**, it is forcefully terminated with **SIGKILL**.
The orchestration session exits with:
* **0** if all test results were successfully reported, even if some child processes had to be terminated after reporting completed.
* **1** if any test results could not be reported, a task failed, or the run was cancelled.
***
### coverage
Set of configuration items related to [Code Coverage for Playwright](/guides/coverage/code-coverage-for-playwright.md).\
#### coverage.projects
* Type: `boolean | string[]`
* Default: `false`
* Environment variable: N/A
Enable or disable coverage collection for Playwright projects
* `true | []`: enable for all projects
* `string[]`: only enable for specified projects
* `false | undefined`: disabled
#### coverage.dir
* Type: `string`
* Default: `.nyc_output`
* Environment variable: N/A
Directory path for reading coverage reports. See [Code Coverage for Playwright](/guides/coverage/code-coverage-for-playwright.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.currents.dev/resources/reporters/currents-playwright/configuration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.