# Playwright Tags

{% hint style="info" %}
**Note**

* Run-level tagging is available in [currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") version **0.7.0+**
* Project-level and test-level tagging is available in [currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") version **0.10.0+**
  {% endhint %}

{% hint style="info" %}
A tag is limited to 128 characters
{% endhint %}

Using tags is a common technique for better classifying recorded test results and getting relevant insights about the test suite. Here are several examples of how software teams use tags:

* manage ownership - e.g. use the team name as a tag
* categorize product features - e.g. tagging `onboarding` flow tests
* manage tests lifecycle - e.g. tag newly introduced tests as `ustable`

The tags are available for producing meaningful reports, exploring metrics, narrowing down Slack notifications, filtering the results, API responses and more.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FmQOZth1k3g3h9DlAeFUG%2FScreenshot%202026-01-15%20at%2018.30.45.png?alt=media&#x26;token=887bed82-d827-4fed-8f98-fc489195e3f1" alt=""><figcaption><p>Example of using Tags for narrowing down Flakiness chart in Currents Dashboard</p></figcaption></figure>

### Playwright Tags

{% hint style="info" %}
[currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") version **0.10.0+** is required for test title tags
{% endhint %}

#### Test title tags

Currents parses the test titles and recognizes the conventional [Playwright Tags](https://playwright.dev/docs/test-annotations#tag-tests) that appear in test definitions. For example, recording the results of the following tests to Currents:

```typescript
test('Test login page @tagA', async ({ page }) => {
  // ...
});

test('Test full report @tagB', async ({ page }) => {
  // ...
});
```

...will create a run with tags: **`tagA`** and **`tagB`**

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FcNbWAdsF79lKwNCPYffL%2FScreenshot%202026-01-15%20at%2018.41.06.png?alt=media&#x26;token=4ee1ce36-ea4e-496a-a776-a5febede1d26" alt=""><figcaption><p>Example of Currents run created with tags @fast and @slow</p></figcaption></figure>

#### Test group tags

Tagging a test group (`test.describe`) will "apply" the tag to every included individual test, as well as to the created run. For example, given the following test definition:

```typescript
test.describe("test group @run", () => { // 👈🏻 note the test group tag

  test('Test login page @tagA', async ({ page }) => {
    // ...
  });
  test('Test full report @tagB', async ({ page }) => {
    // ...
  });
})
```

Currents will assign the following tags to the created items:

<table><thead><tr><th>Item</th><th>Tags</th></tr></thead><tbody><tr><td>Run</td><td><code>run</code>, <code>tagA</code>, <code>tagB</code></td></tr><tr><td><pre><code>Test login page @tagA
</code></pre></td><td><code>run</code>, <code>tagA</code></td></tr><tr><td><pre><code>Test full report @tagB
</code></pre></td><td><code>run</code>, <code>tagB</code></td></tr></tbody></table>

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FLtMNeviBz8L7rsshRznm%2FScreenshot%202026-01-15%20at%2023.04.40.png?alt=media&#x26;token=fa4c66a8-66e6-4cce-8a39-b128f2d8727a" alt=""><figcaption><p>Example of a run created with various tags when tagging a test group</p></figcaption></figure>

#### Tags with `--grep` applied

If certain tags are excluded from the execution, for example by using `--grep` CLI option, only the included tests (and their tags) will be used for tagging.

```
$ npx playwright test --grep @coverage
```

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FvW0E9SrFNIljYAI7lvD6%2FScreenshot%202026-01-15%20at%2018.45.18.png?alt=media&#x26;token=7f1658fc-2411-48f0-b5b3-8b73707807c8" alt=""><figcaption><p>Applying tags when certain tests are excluded using --grep CLI option</p></figcaption></figure>

#### Removing tags from test titles

It is often desired to ignore the tags included in the test title to have a consistent view of the test history or preserve the metrics.

For example, let's say you have a test named `Test login page @slow` , eventually, you add another tag and the test title becomes `Test login page @slow @login`. However, adding the tag will change the test name - as a result, the history of previous executions and metrics will be lost.

To remove the tags from the recorded test titles, add `--pwc-remove-title-tags` CLI option or `removeTitleTags` reporter configuration. Activating the removal will strip the tags from test titles (including test group names) when recording to Currents dashboard.

In the example above, `Test login page @slow` and `Test login page @slow @login` will be recorded as `Test login page` and tags `slow` + `login` will be attached to the test recording.

#### Disabling parsing test title tags

You can disable parsing test title tags altogether by adding `--pwc-disable-title-tags` CLI option. See [currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") for additional configuration options, available in versions `0.11.0+` .

### Run-level Tags

{% hint style="info" %}
[currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") version **0.7.0+** is required to use run-level tags
{% endhint %}

In addition to encoding tags in test titles, you can explicitly tag the whole run (or a playwright project). There are multiple ways to explicitly tag a run.

#### Tagging a run using `pwc` CLI option

If you're using `pwc` executable script to run the tests, use `--tag` CLI option:

```
npx pwc --tag tagA,tagB --tag tagC
```

You can provide a comma-separated list of tags, provide multiple `--tag` options, or use both.

#### Tagging a run using Reporter configuration

You can tag playwright execution by providing a list of `tag` values to Currents Reporter in your `playwright.config.ts` file. For example:

```typescript
import { currentsReporter } from '@currents/playwright';

// ...
reporter: [
  currentsReporter({
    ciBuildId: process.env.CURRENTS_CI_BUILD_ID,
    recordKey: process.env.CURRENTS_RECORD_KEY,
    projectId: process.env.CURRENTS_PROJECT_ID,
    tag: ["runTagA", "runTagB"],
  }),
  /* other reporters, if exist, e.g.:
  ["html"]
  */
]
```

#### Tagging a run using `CURRENTS_TAG` environment variable

You can tag playwright execution by setting the `CURRENTS_TAG` environment variable value to a comma-separated list of tags, for example, with [currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") reporter configured:

```
CURRENTS_TAG=tagA,tagB npx playwright run ...
```

#### Precedence of configuration options

If there are multiple definitions of run-level tags, Currents will pick the tags as follows:

* Use comma-separated tags of `CURRENTS_TAG` environment variable, if provided; otherwise
* Use `--tag` CLI option values, if provided; otherwise
* Use reporter configuration values, if provided; otherwise
* add no run tags

### Project-level Tags

{% hint style="info" %}
[currents-playwright](https://docs.currents.dev/resources/reporters/currents-playwright "mention") version **0.10.0+** is required for project-level tags
{% endhint %}

You can tag Playwright projects by using **`metadata.pwc.tags`** field in the project's configuration. For example, given the following Playwright project configuration:

```typescript
// playwright.config.ts

// ...
{
   projects: [
      {
        name: "Desktop Chrome",
        metadata: {
          pwc: {
            tags: ["desktop", "chrome"], // 👈🏻 note the tags
          },
        },
        use: {
          ...devices["Desktop Chrome"],
        },
      },
      // ...
  ]
}
```

Currents will create a run tagged with `desktop`, `chrome` + all the tags extracted from individual tests.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2F3H2WSdpYIeWy1RrT9F3O%2FScreenshot%202026-01-15%20at%2018.08.15.png?alt=media&#x26;token=b087c632-3781-4b99-ba63-5d880af7f0a3" alt=""><figcaption><p>Example of using project-level tags</p></figcaption></figure>

### How Tags are Applied

Currents stores the recorded results as Runs, Groups, Spec Files and Tests. The items are available in the dashboard and also in [API](https://app.gitbook.com/o/-MT4mUcrnbXWgd1xvl_x/s/lcxad7NaXT7D2V6owvHN/ "mention") responses.

* Run - is a high-level abstraction that represents a CI execution of a test suite
* Group - is a subset of recorded tests - representing a playwright project
* Spec File - a recorded execution of tests in a file
* Test Recording - a recorded execution of a test case

Each of the items can have multiple tags attached, and tagging a particular item can affect the tags of another item. When applying tags, Currents follows the rules below:

* Apply explicit run-level and project-level tags "downwards" to all the included items
* Apply individual test tags "upwards" to spec files, projects and runs

The table below shows the details of how the tags are applied:

<table><thead><tr><th width="225">Item</th><th>Tags Applied</th></tr></thead><tbody><tr><td>Run</td><td><ul><li>Own run-level tags</li><li>Tags of all the included projects</li><li>Tags of all the included test cases</li></ul></td></tr><tr><td>Group/Project</td><td><ul><li>Run-level tags</li><li>Own project-level tags</li><li>Tags of all the included test cases</li></ul></td></tr><tr><td>Spec File Recording</td><td><ul><li>Run-level tags</li><li>Project-level tags</li><li>Tags of all the included test cases</li></ul></td></tr><tr><td>Test Case Recording</td><td><ul><li>Run-level tags</li><li>Project-level tags</li><li>Own test title tags</li></ul></td></tr></tbody></table>

For example, given the following tests:

```typescript
test('Test login A @tagA', async ({ page }) => {
  // ...
});
test('Test login B @tagB', async ({ page }) => {
  // ...
});
```

And adding a run-level tag `runTag01` using the command: `pwc ... --tag runTag01` will result in the following tags:

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FWH8rdBlEqzksngEVyFDx%2Ftags-example-application.png?alt=media&#x26;token=27bb8132-2f0a-4f4f-95fd-8436618a2d42" alt=""><figcaption><p>Application of tags example</p></figcaption></figure>

<table><thead><tr><th>Item</th><th>Applied Tags</th></tr></thead><tbody><tr><td>Run</td><td><code>runTag01</code>, <code>tagA</code>, <code>tagB</code></td></tr><tr><td><pre><code>Test login A
</code></pre></td><td><code>runTag01, tagA</code></td></tr><tr><td><pre><code>Test login B
</code></pre></td><td><code>runTag01, tagB</code></td></tr></tbody></table>


---

# 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/guides/playwright-tags.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.