@testrelic/playwright-analytics 1.0.0

package/README.md

@@ -0,0 +1,304 @@
+# @testrelic/playwright-analytics
+
+A Playwright custom reporter and navigation-tracking fixture that produces a structured JSON timeline of every page visit, network request, and test result in your test suite.
+
+## What It Does
+
+When you run your Playwright tests with this SDK, it generates a single JSON report that captures:
+
+- **Navigation timeline** — Every URL visited during each test, in chronological order
+- **Network statistics** — Total requests, bytes transferred, and breakdowns by resource type (scripts, images, stylesheets, fonts, XHR, etc.)
+- **Test results** — Pass/fail status, duration, retry count, and tags for every test
+- **Failure diagnostics** — Error messages, stack traces, and source code snippets pointing to the exact line that failed
+- **CI metadata** — Automatic detection of GitHub Actions, GitLab CI, Jenkins, and CircleCI with build ID, commit SHA, and branch
+- **SPA detection** — Tracks `pushState`, `replaceState`, `popstate`, and `hashchange` navigations in single-page applications
+- **Sensitive data redaction** — Automatically scrubs AWS keys, Bearer tokens, private keys, and credential URLs from the report
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **Playwright** >= 1.35.0
+- **Package manager**: npm, pnpm, or yarn
+
+## Installation
+
+```bash
+npm install @testrelic/playwright-analytics
+```
+
+```bash
+pnpm add @testrelic/playwright-analytics
+```
+
+```bash
+yarn add @testrelic/playwright-analytics
+```
+
+## Quick Start
+
+### 1. Add the reporter to your Playwright config
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['list'],
+    ['@testrelic/playwright-analytics', {
+      outputPath: './test-results/analytics-timeline.json',
+      includeStackTrace: true,
+      includeCodeSnippets: true,
+      includeNetworkStats: true,
+    }],
+  ],
+});
+```
+
+### 2. Use the fixture in your tests
+
+Replace your Playwright `test` import with the TestRelic fixture to enable automatic navigation tracking:
+
+```typescript
+// my-test.spec.ts
+import { test, expect } from '@testrelic/playwright-analytics/fixture';
+
+test('homepage loads correctly', async ({ page }) => {
+  await page.goto('https://example.com');
+  await expect(page.locator('h1')).toBeVisible();
+});
+```
+
+That's it. Run your tests as usual:
+
+```bash
+npx playwright test
+```
+
+The JSON report will be written to `./test-results/analytics-timeline.json` (or wherever you set `outputPath`).
+
+## Configuration Options
+
+All options are passed as the second element of the reporter tuple in your Playwright config:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `outputPath` | `string` | `./test-results/analytics-timeline.json` | Where to write the JSON report |
+| `includeStackTrace` | `boolean` | `false` | Include full stack traces in failure diagnostics |
+| `includeCodeSnippets` | `boolean` | `true` | Include source code snippets around the failure line |
+| `codeContextLines` | `number` | `3` | Number of lines above/below the failure line to include |
+| `includeNetworkStats` | `boolean` | `true` | Track network requests and byte sizes per navigation |
+| `navigationTypes` | `NavigationType[] \| null` | `null` (all) | Filter timeline to specific navigation types only |
+| `redactPatterns` | `(string \| RegExp)[]` | Built-in patterns | Additional patterns to redact from error messages and stacks |
+| `testRunId` | `string \| null` | `null` (auto UUID) | Override the test run ID |
+| `metadata` | `Record<string, unknown> \| null` | `null` | Attach custom metadata to the report |
+
+### Configuration Example
+
+```typescript
+['@testrelic/playwright-analytics', {
+  outputPath: './reports/timeline.json',
+  includeStackTrace: true,
+  includeCodeSnippets: true,
+  codeContextLines: 5,
+  includeNetworkStats: true,
+  navigationTypes: ['goto', 'navigation', 'back', 'forward'],
+  metadata: {
+    team: 'frontend',
+    environment: 'staging',
+  },
+  redactPatterns: [
+    /my-secret-pattern/g,
+    'literal-string-to-redact',
+  ],
+}]
+```
+
+## Output Format
+
+The report is a single JSON file with this structure:
+
+```jsonc
+{
+  "schemaVersion": "1.0.0",
+  "testRunId": "797128f5-c86d-466c-8d6d-8ec62dfc70b6",
+  "startedAt": "2026-02-07T10:41:28.759Z",
+  "completedAt": "2026-02-07T10:41:36.794Z",
+  "totalDuration": 8035,
+  "summary": {
+    "total": 6,
+    "passed": 5,
+    "failed": 1,
+    "flaky": 0,
+    "skipped": 0
+  },
+  "ci": null,                // Auto-populated in CI environments
+  "metadata": null,          // Custom metadata from config
+  "timeline": [
+    {
+      "url": "https://en.wikipedia.org/wiki/Main_Page",
+      "navigationType": "goto",
+      "visitedAt": "2026-02-07T10:41:29.844Z",
+      "duration": 216,
+      "specFile": "sdk-validation.spec.ts",
+      "domContentLoadedAt": "2026-02-07T10:41:30.200Z",
+      "networkIdleAt": null,
+      "networkStats": {
+        "totalRequests": 40,
+        "failedRequests": 0,
+        "totalBytes": 1289736,
+        "byType": {
+          "xhr": 0,
+          "document": 1,
+          "script": 9,
+          "stylesheet": 2,
+          "image": 27,
+          "font": 2,
+          "other": 0
+        }
+      },
+      "tests": [
+        {
+          "title": "sdk-validation.spec.ts > SDK E2E Validation > homepage visit",
+          "status": "passed",
+          "duration": 1028,
+          "startedAt": "2026-02-07T10:41:29.133Z",
+          "completedAt": "2026-02-07T10:41:30.161Z",
+          "retryCount": 0,
+          "tags": [],
+          "failure": null
+        }
+      ]
+    }
+    // ... more timeline entries
+  ],
+  "shardRunIds": null        // Populated when merging shard reports
+}
+```
+
+### Timeline Entry Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `url` | `string` | The URL that was navigated to |
+| `navigationType` | `string` | How the navigation happened (see navigation types below) |
+| `visitedAt` | `string` | ISO-8601 timestamp of the navigation |
+| `duration` | `number` | Milliseconds until the next navigation or test end |
+| `specFile` | `string` | Relative path to the spec file |
+| `domContentLoadedAt` | `string \| null` | When DOMContentLoaded fired |
+| `networkIdleAt` | `string \| null` | When network became idle |
+| `networkStats` | `object \| null` | Network request statistics for this navigation |
+| `tests` | `array` | Test results associated with this navigation |
+
+### Navigation Types
+
+| Type | Description |
+|---|---|
+| `goto` | `page.goto()` call |
+| `navigation` | Browser frame navigation (link click, form submit) |
+| `back` | `page.goBack()` call |
+| `forward` | `page.goForward()` call |
+| `refresh` | `page.reload()` call |
+| `spa_route` | `history.pushState()` detected |
+| `spa_replace` | `history.replaceState()` detected |
+| `hash_change` | URL hash change |
+| `popstate` | Browser back/forward via popstate event |
+
+### Network Stats
+
+When `includeNetworkStats` is enabled, each timeline entry includes:
+
+```json
+{
+  "totalRequests": 40,
+  "failedRequests": 0,
+  "totalBytes": 1289736,
+  "byType": {
+    "xhr": 0,
+    "document": 1,
+    "script": 9,
+    "stylesheet": 2,
+    "image": 27,
+    "font": 2,
+    "other": 0
+  }
+}
+```
+
+### Failure Diagnostics
+
+When a test fails, the report includes diagnostic details:
+
+```json
+{
+  "message": "expect(received).toBe(expected) // Object.is equality\n\nExpected: 3\nReceived: 2",
+  "line": 70,
+  "code": "  67 |   test('deliberate failure', async ({ page }) => {\n  68 |     await page.goto('https://example.com');\n  69 |     // This assertion will fail\n> 70 |     expect(1 + 1).toBe(3);\n  71 |   });",
+  "stack": "Error: expect(received).toBe(expected)\n    at /path/to/spec.ts:70:19"
+}
+```
+
+### CI Metadata
+
+When running in a supported CI environment, the `ci` field is auto-populated:
+
+```json
+{
+  "provider": "github-actions",
+  "buildId": "12345678",
+  "commitSha": "abc123def456",
+  "branch": "main"
+}
+```
+
+Supported providers: **GitHub Actions**, **GitLab CI**, **Jenkins**, **CircleCI**.
+
+## Merging Shard Reports
+
+When running Playwright with sharding, each shard produces its own report. Use the CLI to merge them:
+
+```bash
+npx testrelic merge shard-1.json shard-2.json shard-3.json -o merged-report.json
+```
+
+Or programmatically:
+
+```typescript
+import { mergeReports } from '@testrelic/playwright-analytics/merge';
+
+const merged = await mergeReports(
+  ['shard-1.json', 'shard-2.json'],
+  { output: 'merged-report.json' }
+);
+```
+
+The merged report combines all timelines chronologically, recalculates the summary, and records the original shard run IDs.
+
+## Security
+
+The reporter automatically redacts sensitive data from error messages, stack traces, and code snippets before writing the report:
+
+- AWS access key IDs (`AKIA...`)
+- Bearer tokens (`Bearer eyJ...`)
+- Private keys (`-----BEGIN PRIVATE KEY-----`)
+- Credential URLs (`//user:password@host`)
+
+You can add custom redaction patterns via the `redactPatterns` config option.
+
+## How It Works
+
+The SDK has two components that work together:
+
+1. **Fixture** (`@testrelic/playwright-analytics/fixture`) — Wraps the Playwright `page` object with a `NavigationTracker` that intercepts `goto`, `goBack`, `goForward`, and `reload` calls, listens for `framenavigated` events, injects a script to detect SPA navigations, and optionally tracks network responses. All tracked data is written as test annotations.
+
+2. **Reporter** (`@testrelic/playwright-analytics`) — A Playwright custom reporter that collects test results and navigation annotations in `onTestEnd`, then on `onEnd` builds the final JSON timeline, detects CI metadata, applies redaction, and writes the report atomically (write to temp file, then rename).
+
+The reporter never throws during test execution — all hooks are wrapped in try/catch to ensure it never crashes your test run.
+
+## Using Without the Fixture
+
+The reporter works without the fixture, but navigation tracking will not be available. Tests will still be captured with their pass/fail status, duration, and failure diagnostics. The timeline entries will show `about:blank` as the URL with `dummy` navigation type.
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/merge.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_core = require("@testrelic/core");
+async function mergeReports(files, options) {
+  const reports = [];
+  for (const file of files) {
+    let raw;
+    try {
+      raw = (0, import_node_fs.readFileSync)(file, "utf-8");
+    } catch (err) {
+      throw (0, import_core.createError)(
+        import_core.ErrorCode.MERGE_READ_FAILED,
+        `Failed to read file: ${file}`,
+        err
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw (0, import_core.createError)(
+        import_core.ErrorCode.MERGE_INVALID_SCHEMA,
+        `Invalid JSON in file: ${file}`,
+        err
+      );
+    }
+    if (!(0, import_core.isValidTestRunReport)(parsed)) {
+      throw (0, import_core.createError)(
+        import_core.ErrorCode.MERGE_INVALID_SCHEMA,
+        `Invalid report schema in file: ${file}`
+      );
+    }
+    reports.push(parsed);
+  }
+  const shardRunIds = reports.map((r) => r.testRunId);
+  const allTimelines = [];
+  for (const report of reports) {
+    allTimelines.push(...report.timeline);
+  }
+  allTimelines.sort(
+    (a, b) => new Date(a.visitedAt).getTime() - new Date(b.visitedAt).getTime()
+  );
+  const summary = recalculateSummary(reports);
+  const startedAt = reports.reduce(
+    (earliest, r) => r.startedAt < earliest ? r.startedAt : earliest,
+    reports[0]?.startedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  );
+  const completedAt = reports.reduce(
+    (latest, r) => r.completedAt > latest ? r.completedAt : latest,
+    reports[0]?.completedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  );
+  const totalDuration = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+  const merged = {
+    schemaVersion: reports[0]?.schemaVersion ?? "1.0.0",
+    testRunId: options.testRunId ?? (0, import_node_crypto.randomUUID)(),
+    startedAt,
+    completedAt,
+    totalDuration,
+    summary,
+    ci: reports.find((r) => r.ci !== null)?.ci ?? null,
+    metadata: reports.find((r) => r.metadata !== null)?.metadata ?? null,
+    timeline: allTimelines,
+    shardRunIds
+  };
+  const dir = (0, import_node_path.dirname)(options.output);
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  (0, import_node_fs.writeFileSync)(options.output, JSON.stringify(merged, null, 2), "utf-8");
+  return merged;
+}
+function recalculateSummary(reports) {
+  let total = 0;
+  let passed = 0;
+  let failed = 0;
+  let flaky = 0;
+  let skipped = 0;
+  for (const report of reports) {
+    total += report.summary.total;
+    passed += report.summary.passed;
+    failed += report.summary.failed;
+    flaky += report.summary.flaky;
+    skipped += report.summary.skipped;
+  }
+  return { total, passed, failed, flaky, skipped };
+}
+
+// src/cli.ts
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    printUsage();
+    process.exit(0);
+  }
+  if (args[0] !== "merge") {
+    process.stderr.write(`Unknown command: ${args[0]}
+`);
+    printUsage();
+    process.exit(1);
+  }
+  const mergeArgs = args.slice(1);
+  const outputIndex = mergeArgs.findIndex((a) => a === "-o" || a === "--output");
+  if (outputIndex === -1 || outputIndex === mergeArgs.length - 1) {
+    process.stderr.write("Error: -o <output> is required\n");
+    printUsage();
+    process.exit(1);
+  }
+  const output = mergeArgs[outputIndex + 1];
+  const files = [
+    ...mergeArgs.slice(0, outputIndex),
+    ...mergeArgs.slice(outputIndex + 2)
+  ];
+  if (files.length === 0) {
+    process.stderr.write("Error: No input files specified\n");
+    printUsage();
+    process.exit(1);
+  }
+  try {
+    const merged = await mergeReports(files, { output });
+    process.stderr.write(
+      `Merged ${files.length} reports (${merged.summary.total} tests) \u2192 ${output}
+`
+    );
+  } catch (err) {
+    process.stderr.write(
+      `Error: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    process.exit(1);
+  }
+}
+function printUsage() {
+  process.stderr.write(
+    `Usage: testrelic merge <files...> -o <output>
+
+  Merge multiple shard report JSON files into one.
+
+  Example:
+    npx testrelic merge shard-1.json shard-2.json -o merged.json
+`
+  );
+}
+main();