![\"npm](\"https://img.shields.io/npm/v/@actboard/playwright-reporter?color=crimson&label=npm\")
\n ![\"downloads\"](\"https://img.shields.io/npm/dm/@actboard/playwright-reporter?color=blue\")
\n ![\"Playwright](\"https://img.shields.io/npm/dependency-version/@actboard/playwright-reporter/peer/%40playwright%2Ftest?label=%40playwright%2Ftest\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
\n\n
\n A Playwright reporter that captures full test history, tracks pass-rate trends, and surfaces flaky tests — sending every run to your ActBoard dashboard for deep analysis.\n
\n\n---\n\n### What you get\n\n- **Full test history** — every run stored, browsable, and searchable\n- **Pass rate trends** — see whether your suite is getting healthier over time\n- **Flaky test detection** — tests that flip between pass/fail are automatically flagged\n- **Branch & commit tracking** — compare runs across branches and deployments\n- **CI-ready** — works with GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure DevOps, and more\n- **Self-hostable** — one Docker command, your data stays on your infra\n\n---\n\n## Installation\n\n```bash\nnpm install --save-dev @actboard/playwright-reporter\n# or\nyarn add -D @actboard/playwright-reporter\n# or\npnpm add -D @actboard/playwright-reporter\n```\n\n## Quick Start\n\n### 1. Start ActBoard\n\n**Cloud:** Sign up at [actboard.io](https://actboard.io) and get an API key.\n\n**Self-hosted (Docker):**\n```bash\ndocker run -p 3141:3141 -v actboard_data:/app/data actboard/server:latest\n# Then seed demo data:\ndocker exec actboard node scripts/seed.js\n```\n\n**Self-hosted (Node.js):**\n```bash\nnpx actboard-server # starts on http://localhost:3141\nnpx actboard-server seed # seed demo data\n```\n\n### 2. Configure the reporter\n\n```ts\n// playwright.config.ts\nimport { defineConfig } from '@playwright/test';\n\nexport default defineConfig({\n reporter: [\n ['list'], // keep the terminal reporter\n ['@actboard/playwright-reporter', {\n serverUrl: 'http://localhost:3141', // or https://actboard.io\n apiKey: process.env.ACTBOARD_API_KEY,\n project: 'e2e-production', // must match your project slug\n branch: process.env.GITHUB_REF_NAME || 'local',\n commitSha: process.env.GITHUB_SHA,\n triggeredBy: process.env.CI ? 'ci' : 'local',\n }],\n ],\n});\n```\n\n### 3. Run your tests\n\n```bash\nACTBOARD_API_KEY=act_yourkey npx playwright test\n```\n\nResults appear in the ActBoard dashboard immediately after the run completes.\n\n---\n\n## Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `apiKey` | `string` | ✓ | `ACTBOARD_API_KEY` env | Project API key from ActBoard dashboard |\n| `serverUrl` | `string` | | `http://localhost:3141` | ActBoard server URL |\n| `project` | `string` | | `ACTBOARD_PROJECT` env | Project slug (from Settings → Project) |\n| `branch` | `string` | | `GITHUB_REF_NAME` or `'local'` | Git branch name |\n| `commitSha` | `string` | | `GITHUB_SHA` | Full commit SHA |\n| `commitMessage` | `string` | | `CI_COMMIT_MESSAGE` | Short commit message |\n| `triggeredBy` | `string` | | `'ci'` / `'local'` | What triggered the run |\n| `browsers` | `string[]` | | auto-detected | Override browser list |\n| `metadata` | `object` | | `{}` | Extra key-value data attached to the run |\n| `timeout` | `number` | | `30000` | HTTP request timeout (ms) |\n| `verbose` | `boolean` | | `true` | Print ActBoard status to stdout |\n\n---\n\n## Environment Variables\n\nThe reporter reads these automatically — no code changes needed in CI:\n\n```bash\nACTBOARD_API_KEY=act_myproject_abc123 # required\nACTBOARD_SERVER_URL=https://actboard.io # optional, default: localhost:3141\nACTBOARD_PROJECT=e2e-production # optional, use if project not set in config\n```\n\n---\n\n## CI Integration Examples\n\n### GitHub Actions\n\n```yaml\n# .github/workflows/playwright.yml\nname: Playwright Tests\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - uses: actions/setup-node@v4\n with:\n node-version: 20\n cache: npm\n\n - run: npm ci\n - run: npx playwright install --with-deps\n\n - name: Run Playwright Tests\n env:\n ACTBOARD_API_KEY: ${{ secrets.ACTBOARD_API_KEY }}\n ACTBOARD_SERVER_URL: ${{ secrets.ACTBOARD_SERVER_URL }}\n run: npx playwright test\n```\n\nAdd `ACTBOARD_API_KEY` and `ACTBOARD_SERVER_URL` to **Settings → Secrets and variables → Actions**.\n\n---\n\n### GitLab CI\n\n```yaml\n# .gitlab-ci.yml\nplaywright:\n image: mcr.microsoft.com/playwright:v1.44.0-jammy\n stage: test\n variables:\n ACTBOARD_API_KEY: $ACTBOARD_API_KEY\n ACTBOARD_SERVER_URL: $ACTBOARD_SERVER_URL\n script:\n - npm ci\n - npx playwright test\n artifacts:\n when: always\n paths:\n - playwright-report/\n expire_in: 1 week\n```\n\n---\n\n### CircleCI\n\n```yaml\n# .circleci/config.yml\nversion: 2.1\n\njobs:\n playwright:\n docker:\n - image: mcr.microsoft.com/playwright:v1.44.0-jammy\n steps:\n - checkout\n - run: npm ci\n - run:\n name: Run Playwright Tests\n command: npx playwright test\n environment:\n ACTBOARD_API_KEY: $ACTBOARD_API_KEY\n ACTBOARD_SERVER_URL: $ACTBOARD_SERVER_URL\n```\n\n---\n\n### Jenkins\n\n```groovy\n// Jenkinsfile\npipeline {\n agent any\n environment {\n ACTBOARD_API_KEY = credentials('actboard-api-key')\n ACTBOARD_SERVER_URL = 'https://actboard.yourcompany.com'\n }\n stages {\n stage('Test') {\n steps {\n sh 'npm ci'\n sh 'npx playwright install --with-deps chromium'\n sh 'npx playwright test'\n }\n }\n }\n post {\n always {\n publishHTML(target: [reportDir: 'playwright-report', reportFiles: 'index.html', reportName: 'Playwright Report'])\n }\n }\n}\n```\n\n---\n\n### Azure DevOps\n\n```yaml\n# azure-pipelines.yml\ntrigger:\n - main\n\npool:\n vmImage: ubuntu-latest\n\nvariables:\n ACTBOARD_API_KEY: $(ACTBOARD_API_KEY)\n ACTBOARD_SERVER_URL: $(ACTBOARD_SERVER_URL)\n\nsteps:\n - task: NodeTool@0\n inputs:\n versionSpec: '20.x'\n\n - script: npm ci\n displayName: Install dependencies\n\n - script: npx playwright install --with-deps\n displayName: Install browsers\n\n - script: npx playwright test\n displayName: Run Playwright tests\n```\n\nAdd `ACTBOARD_API_KEY` and `ACTBOARD_SERVER_URL` as pipeline variables (mark as secret).\n\n---\n\n## How It Works\n\n1. The reporter hooks into Playwright's lifecycle via `onBegin` / `onTestEnd` / `onEnd`\n2. Results are buffered in memory during the run (zero impact on test performance)\n3. When `onEnd` fires, results are POSTed to `POST /api/runs` on your ActBoard server\n4. The server stores results in SQLite (self-host) or PostgreSQL (cloud) and finalizes the run record\n5. The dashboard immediately reflects the new run\n\nIf the server is unreachable, the reporter logs a warning and exits gracefully — your test run always completes regardless.\n\n---\n\n## Troubleshooting\n\n**Reporter not publishing results:**\n- Check `ACTBOARD_API_KEY` is set in your CI environment\n- Verify `serverUrl` is reachable from your CI runner (firewall / VPN?)\n- Run with `verbose: true` (default) and check stdout for error messages\n\n**`Invalid API key` error:**\n- Copy the key exactly from Settings → API Keys in the dashboard\n- Keys are shown only once when created — generate a new one if lost\n\n**Connection timeout:**\n- Increase `timeout` option (default: 30 seconds)\n- Check that your ActBoard server is healthy: `curl http://your-server/api/health`\n\n---\n\n## License\n\nMIT © [ActBoard](https://actboard.io)\n","readmeFilename":"README.md"}