Currents Integration Skill for Claude Code

Overview

Per currents-docs (opens in new window):

"Playwright reports explain a single run. Currents explains your test suite over time, and more."

Currents.dev is a SaaS test analytics platform that ingests per-run results via runner-specific reporters and provides longitudinal views (flake rate over time, slowest-test trends, PR-level deltas). It's commonly paired with Playwright and Cypress.

This skill covers the Playwright integration; the Cypress integration follows the same shape with @currents/cypress (see references/ci-and-cypress-integration.md).

When to use

A Playwright suite has 100+ tests and the team needs over-time analytics: which tests flake, which tests slow down across PRs, which tests fail on certain CI runners only.
The team wants per-PR test diffs (this PR's failures vs main's failures) without building a custom dashboard.
The team is on Cypress (use @currents/cypress with the same shape).

If the suite is small (<50 tests) and the team only needs the per-run report, Playwright's built-in HTML reporter is enough - no SaaS dependency.

How to use

Confirm the suite is large enough to need over-time analytics (see When to use); a small suite is fine on Playwright's HTML reporter.
Install @currents/playwright.
Author currents.config.ts (recordKey from env, projectId inline) and register currentsReporter() in playwright.config.ts.
Enable trace / video / screenshot artifacts so Currents has per-test data to analyze.
Run npx pwc; open the dashboard URL it prints.
Wire the same run into CI, recording both main (baseline) and PR runs - the full workflow, per-PR-vs-main rationale, and the Cypress sister integration are in references/ci-and-cypress-integration.md.

Install

Per currents-pw-quickstart (opens in new window):

npm i -D @currents/playwright
# Equivalent for pnpm / yarn / bun.

Configure `currents.config.ts`

Place next to playwright.config.ts. Per currents-pw-quickstart (opens in new window):

import { CurrentsConfig } from "@currents/playwright";

const config: CurrentsConfig = {
  recordKey: process.env.CURRENTS_RECORD_KEY!,
  projectId: "your project id goes here",
};

export default config;

The recordKey is the project's record-write secret - never check it into the repo. The projectId is non-secret (visible in the Currents dashboard URL); it's safe to inline.

Register the reporter

In playwright.config.ts, per currents-pw-quickstart (opens in new window):

import { defineConfig } from "@playwright/test";
import { currentsReporter } from "@currents/playwright";

export default defineConfig({
  reporter: [currentsReporter()],
  // ... other config ...
});

The reporter forwards every test event (start, finish, attachments) to the Currents API.

Enable artifacts

Per currents-pw-quickstart (opens in new window), the use section should enable the three artifact types Currents consumes:

use: {
  trace: "on",
  video: "on",
  screenshot: "on",
}

The defaults Playwright ships with (trace: "on-first-retry") cap the artifact volume; Currents wants every test's trace to drive its analytics. For a high-volume suite, consider trace: "retain-on-failure" as a middle ground.

Run

Per currents-pw-quickstart (opens in new window):

# Reads recordKey from env, projectId from config:
npx pwc

# Or pass on the CLI:
npx pwc --key XXX --project-id YYY

pwc is the Currents-aware Playwright wrapper. It runs Playwright with the Currents reporter active and streams results in real-time; on completion, it prints a dashboard URL.

Worked example

A 120-test Playwright suite, first Currents run:

npm i -D @currents/playwright.
currents.config.ts alongside playwright.config.ts:

import { CurrentsConfig } from "@currents/playwright";

const config: CurrentsConfig = {
  recordKey: process.env.CURRENTS_RECORD_KEY!,
  projectId: "abc123def",
};

export default config;

In playwright.config.ts, add the reporter and turn artifacts on:

reporter: [currentsReporter()],
use: { trace: "on", video: "on", screenshot: "on" },

Export the secret and run:

export CURRENTS_RECORD_KEY=...     # from the Currents dashboard
npx pwc

pwc streams each test event to Currents and prints a dashboard URL on completion. After the second run on main, the dashboard's trend graphs start showing flake rate and slowest-test movement across runs.

Operating in CI

Run npx pwc from the CI job with CURRENTS_RECORD_KEY supplied as a secret, and trigger on both push to main and pull_request so the dashboard has a baseline (main) to compare each PR run against. Keep Playwright's HTML report as an if: always() artifact fallback for when the dashboard is unreachable. The full GitHub Actions workflow, the per-PR-vs-main baseline rationale, and the Cypress sister integration are in references/ci-and-cypress-integration.md.

Anti-patterns

Anti-pattern	Why it fails	Fix
Hardcoding `recordKey` in `currents.config.ts`	Secret leaks into git; bad actors can pollute the dashboard.	Read from env (see Configure `currents.config.ts`).
Running both Playwright's default HTML reporter and `currentsReporter` without artifact handling	Doubled artifact size; CI runner disk pressure.	Keep both reporters; rely on the `if: always()` upload (see Operating in CI).
Sending production / staging real-user CI runs to Currents	Mixes test signal with monitoring signal; analytics pollute.	Send only test runs; production observability lives elsewhere.
Disabling `trace: "on"` to "save space"	Currents's value is per-test trace inspection; disabled traces gut the analytics.	Use `retain-on-failure` as a middle ground (see Enable artifacts).
Recording PR runs without recording main runs	No baseline; per-PR diff is meaningless.	Record main on every push too (see Operating in CI).
Treating `pwc`'s exit code as gate-only	The dashboard surfaces flake / regression context the CI exit code hides.	Read both: pass/fail from CI; flake / regression from the dashboard or its API.

Limitations

SaaS dependency. Currents is a managed service. Air-gapped / offline CI can't use it directly.
Per-run cost. Recording every PR push to a public repo with 100s of tests can hit the plan's recorded-test-count quota. Consider main-only recording for low-traffic projects.
No first-party Jest / Mocha integration. The platform is Playwright + Cypress focused; other runners need custom JUnit XML ingestion (which loses per-test artifacts).
Doc URL drift. Per the redirect chain observed in this skill's source-fetch (currents.dev → docs.currents.dev → versioned paths), Currents docs occasionally move. Pin a version of the SDK package and re-verify URLs at each upgrade.

References

currents-docs (opens in new window) - Currents.dev overview, "test suite over time, and more" positioning, supported runners (Playwright explicit; Cypress in the references file).
currents-pw-quickstart (opens in new window) - Playwright integration: install, currents.config.ts shape (recordKey + projectId), reporter registration, artifact config (trace / video / screenshot), npx pwc run command.
references/ci-and-cypress-integration.md - full GitHub Actions workflow, per-PR-vs-main baselines, and the Cypress sister integration.
junit-xml-analysis - pair with Currents to keep CI gating self-hosted (JUnit) while Currents handles longitudinal analytics.
test-management-sync - sibling test-management integrations (different role: test management vs analytics).

Reference

Currents CI wiring and the Cypress integration

View source

Deep reference for the currents-integration SKILL.md. Consult when wiring Currents into GitHub Actions, coordinating per-PR vs main baselines, or setting up the Cypress sister integration.

CI integration

# .github/workflows/e2e.yml
name: e2e
on:
  pull_request:
  push:
    branches: [main]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps

      - name: Run tests with Currents
        env:
          CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }}
        run: npx pwc

      - name: Upload Playwright HTML report (fallback)
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

if: always() on the artifact upload preserves the local report even when the Currents stream succeeds - useful when the dashboard is unreachable.

Per-PR vs main runs

The Currents dashboard separates main runs (baseline) from PR runs (comparison). For the analytics to make sense:

Main: every push to main records a run. This becomes the baseline for trend graphs.
PR: every PR push records a run; the dashboard cross-references by test name to identify "this PR introduced the flake on cart.spec.ts:42".

Set the CI workflow's branch + PR triggers (the CI integration example above) to record both.

Cypress shape (sister integration, same pattern)

The Cypress integration follows the same shape with @currents/cypress instead of @currents/playwright:

npm i -D @currents/cypress

Then in cypress.config.ts:

import { defineConfig } from 'cypress';
import { currentsConfig } from '@currents/cypress';

export default defineConfig({
  ...currentsConfig({
    recordKey: process.env.CURRENTS_RECORD_KEY!,
    projectId: 'your-project-id',
  }),
});

Run via npx cypress-cloud run (the Cypress equivalent of pwc).