# Configuration

## 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 <mark style="color:yellow;">\*</mark>

* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_CI_BUILD_ID`

<mark style="color:yellow;">Required.</mark> The ID of the build to associate the test run with. See [CI Build ID](/guides/parallelization-guide/ci-build-id.md).

***

### projectId <mark style="color:yellow;">\*</mark>

* Type: `string`
* Default: `undefined`
* Environment variable: `CURRENTS_PROJECT_ID`

<mark style="color:yellow;">Required.</mark> The Currents project ID used for reporting. See [Projects](/dashboard/projects.md).

***

### recordKey <mark style="color:yellow;">\*</mark>

* Type: `string`
* Default: *Required*
* Environment variable: `CURRENTS_RECORD_KEY`

<mark style="color:yellow;">Required.</mark> 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).

***

### 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: `CURRENTS_MACHINE_ID`
* Environment variable: N/A

Optional unique machine identifier. Mostly used internally.

***

### 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'
```

***

### consoleOutput

* Type: `none | summary | detailed`
* Default: `detailed`
* Environment variable: `CURRENTS_CONSOLE_OUTPUT`

Reporter console output: "none" (no stdout), "summary" (intro, one line per test, summary), "detailed" (full per-test output).

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).<br>

#### 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).

<br>

#### 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).

<br>

#### orchestration.onFinish

* Type: `(status: OrchestrationStatus) => Promise<void>`
* 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";
```

<br>

#### 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 workers should be used for the orchestration.

* `auto` infers the batch size from Playwright workers.
* `number` explicitly sets the batch size, must be greater than `0`

{% 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 %}

***

### coverage

Set of configuration items related to [Code Coverage for Playwright](/guides/coverage/code-coverage-for-playwright.md).\ <br>

#### 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

<br>

#### 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: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/resources/reporters/currents-playwright/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.