playwright-dynamic-tagger-plugin

A Playwright reporter plugin that automatically assigns dynamic tags to tests based on their execution results and rewrites test source files to persist those tags.

After each test run the plugin updates tag arrays in your test source files. In CI environments it only emits warnings — source files are never modified.

Installation

npm install --save-dev playwright-dynamic-tagger-plugin

Quick Start

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import DynamicTaggerReporter from 'playwright-dynamic-tagger-plugin/reporter';

export default defineConfig({
  reporter: [
    ['html'],
    new DynamicTaggerReporter({ prefix: '@auto' }),
  ],
});

// tests/checkout.test.ts
import { test, expect } from '@playwright/test';
import { tag } from 'playwright-dynamic-tagger-plugin';

test('checkout flow', async ({ page }) => {
  await page.goto('/checkout');
  tag('checkout'); // ← explicitly tag this test at runtime
  await expect(page.locator('h1')).toBeVisible();
});

After the run, the source file is rewritten to:

test('checkout flow', { tag: ['@auto:checkout'] }, async ({ page }) => {

Subsequent runs replace only the @auto: tags; manually added tags are preserved.

Configuration

new DynamicTaggerReporter({
  prefix?: string;     // default: '@auto'
  taggers?: TaggerFn[]; // default: []
  dryRun?: boolean;    // default: auto-detected from CI env vars
})

prefix

The prefix applied to all tags managed by this plugin. All tags that begin with this prefix in source files are considered owned by the plugin and may be replaced on subsequent runs.

Must start with @. Default: '@auto'.

taggers

An array of functions that automatically compute tags from test results. Each function receives the final TestResult and TestCase and returns an array of tag names (without the prefix).

Tags returned by all taggers are merged (deduplicated) with any tags added via tag().

import type { TaggerFn } from 'playwright-dynamic-tagger-plugin';

// Mark slow tests
const slowTagger: TaggerFn = (result) =>
  result.duration > 5000 ? ['slow'] : [];

// Mark flaky tests (failed but eventually passed via retry)
const flakyTagger: TaggerFn = (result) =>
  result.retry > 0 && result.status === 'passed' ? ['flaky'] : [];

// Mark consistently failing tests
const failingTagger: TaggerFn = (result) =>
  result.status === 'failed' || result.status === 'timedOut' ? ['failing'] : [];

new DynamicTaggerReporter({
  prefix: '@auto',
  taggers: [slowTagger, flakyTagger, failingTagger],
});

Tagger functions may also be async.

dryRun

When true, the plugin emits console warnings showing what would have changed but does not modify any source files.

Automatically set to true when any of the following environment variables are detected: CI, CONTINUOUS_INTEGRATION, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, BUILDKITE, BUILD_NUMBER, DRY_RUN.

Explicit Tagging with tag()

The tag() function can be called from anywhere during a test run — inside a test body, a Page Object method, a helper function, etc. — without needing to inject any fixture.

import { tag } from 'playwright-dynamic-tagger-plugin';

// Inside a test
test('my test', async ({ page }) => {
  if (featureFlag) {
    tag('feature-x');
  }
});

// Inside a Page Object
class CheckoutPage {
  async completePayment() {
    tag('payment-flow');
    // ...
  }
}

The tag name is provided without the prefix. The reporter applies the configured prefix when writing back to source files.

Duplicate calls with the same name are silently ignored.

How It Works

1. During the test run, tag() writes tag names to a temporary file per test (identified by Playwright's internal testId).
2. Automatic taggers are called in onTestEnd with the final result of each test.
3. At the end of the run (onEnd), the plugin merges all tags and rewrites source files atomically.
4. Only tests that ran in the current session are updated. Tests that did not run retain their existing tags.
5. Re-running a test clears its previous @prefix: tags and replaces them with the new computed set.

Source File Changes

The plugin handles all common forms of the test() call:

// Before — no options
test('name', async ({ page }) => {})
// After
test('name', { tag: ['@auto:slow'] }, async ({ page }) => {})

// Before — existing options without tag
test('name', { timeout: 5000 }, async ({ page }) => {})
// After — other options preserved
test('name', { timeout: 5000, tag: ['@auto:slow'] }, async ({ page }) => {})

// Before — managed tags updated, manual tags preserved
test('name', { tag: ['@auto:old', '@manual'] }, async ({ page }) => {})
// After
test('name', { tag: ['@manual', '@auto:slow'] }, async ({ page }) => {})

Works with test, test.only, test.skip, test.fixme, and any custom test extended with fixtures.

CI / Dry Run

In CI environments, no files are modified. The plugin prints a warning for each test that would have been updated:

[playwright-dynamic-tagger] DRY RUN — would set tags [@auto:slow] on "my test" (tests/my.test.ts:10)

To force dry-run mode locally:

DRY_RUN=1 npx playwright test

Contributing

See CONTRIBUTING.md.

License

MIT © Emanuele Minotto