@stacknext/playwright 0.8.0 → 0.10.0

package/docs/correlation.md

@@ -0,0 +1,66 @@
+---
+title: Correlation
+description: Exact trace injection, probing and the verified/incomplete sample rule.
+---
+
+# Correlation
+
+StackNext never links browser and server activity by time or proximity. Each
+sample is proven by an injected trace context.
+
+## Injection
+
+`createTraceparent()` generates a W3C `traceparent` with a new trace id and
+span id. The fixture adds it to document, fetch and XHR requests whose URL is:
+
+- loopback (`127.0.0.1`, `localhost`, `[::1]`, `::1`); or
+- the Playwright project's `baseURL` origin.
+
+Other resource types and cross-origin requests are left untouched.
+
+## Verification
+
+The collector considers a trace verified only when both are true:
+
+1. it stored a trace with the injected trace id; and
+2. it contains a server span whose parent span id equals the injected span id.
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:35e306be3c7839621b0cb18396b64a12651243d1d324f2c17b11b03ca80b9e99 -->
+
+The fixture probes `GET /api/traces/:traceId` until the
+document trace is found or the timeout expires. It submits at most 20 trace
+references per sample, document requests first.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+If either condition is missing, the sample is `incomplete` with a reason such
+as:
+
+- `trace-not-found`;
+- `injected-parent-not-found`;
+- `no-request-trace-recorded`.
+
+There is no fallback to a nearby request, a time window or a synthetic trace.
+An incomplete sample makes the affected comparison inconclusive.
+
+## Why the server must cooperate
+
+`@stacknext/next` installs the W3C composite propagator during registration. If
+the app does not run StackNext instrumentation, or another provider replaces the
+propagator, the injected trace id never reaches the server and correlation
+fails.
+
+The collector's self-instrumentation filter also excludes requests to
+`/__stacknext/`, so dashboard and MCP traffic cannot be mistaken for application
+requests.
+
+## Limits
+
+- One worker only. Parallel correlation is not verified.
+- Redirects and new tabs may create traces that are not in the submitted set.
+- Browser-side rendering and network timing are not captured.
+- Playwright screenshots, video and trace archives are never read or stored.
+
+See [regression captures](../../regression/docs/captures.md).

package/docs/fixture.md

@@ -0,0 +1,83 @@
+---
+title: Fixture
+description: How the auto stacknextCapture fixture identifies scenarios and submits samples.
+---
+
+# Fixture
+
+Import `test` and `expect` from `@stacknext/playwright` instead of
+`@playwright/test`. The `stacknextCapture` fixture is automatic; you do not add
+it to the test signature.
+
+## Capture lifecycle
+
+1. `resolveCaptureConfig()` reads the capture environment.
+2. If capture is inactive, the fixture is a no-op.
+3. During the test, document/fetch/XHR requests to loopback or the configured
+   `baseURL` origin receive a W3C `traceparent`.
+4. After the test, the fixture waits for the collector to observe the traces.
+5. It submits one sample with the Playwright status, duration, retry/repeat
+   indices and verified trace references.
+
+Skipped tests do not submit a sample. The fixture never replaces Playwright
+assertions or changes the test result.
+
+## Scenario identity
+
+The preferred identity is an explicit annotation:
+
+```ts
+import { test, expect } from '@stacknext/playwright'
+
+test('checkout completes', async ({ page }) => {
+  test.info().annotations.push({
+    type: 'stacknext.scenario',
+    description: 'checkout-complete',
+  })
+
+  await page.goto('/checkout')
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible()
+})
+```
+
+The fixture accepts any annotation whose type starts with `stacknext` and uses
+its description. If none exists, identity falls back to the Playwright `testId`,
+then file + title + project.
+
+Keep the annotation stable. Changing it creates a new scenario with no matching
+baseline.
+
+## Capture environment
+
+The fixture reads:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `STACKNEXT_TEST_RUN_ID` | required when active | Active `run-...` id. |
+| `STACKNEXT_COLLECTOR_URL` | required when active | Loopback collector origin. |
+| `STACKNEXT_TOKEN` | required when active | Collector bearer token. |
+| `STACKNEXT_CAPTURE_SETTLE_MS` | 500 | Wait before the first probe. |
+| `STACKNEXT_CAPTURE_TIMEOUT_MS` | 5000 | Probe deadline per sample. |
+
+`stacknext capture` sets the required values. Do not set them by hand for a
+normal captured run.
+
+## Playwright configuration
+
+- Use **one worker** for captured runs.
+- Use at least three samples per scenario for a comparison
+  (`--repeat-each=3`).
+- Warm routes before capturing a baseline.
+- Keep the test command short and deterministic.
+
+## Exports
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:9b1d429fc146b7836cdccc75d58c560d2e60b18305797d98bcd9841b60c57664 -->
+
+`stackNextFixtures()` is an exported function returning `{ test, expect }`. `resolveCaptureConfig()` returns a
+`CaptureConfig` or `null`; it throws `CaptureTransportError` when capture is
+active but the required values are invalid.
+
+<!-- /coderabbit-ai-generated:v1 -->

package/docs/index.md

@@ -0,0 +1,100 @@
+---
+title: "@stacknext/playwright"
+description: Optional Playwright fixtures that correlate browser scenarios with StackNext server telemetry.
+---
+
+# @stacknext/playwright
+
+`@stacknext/playwright` provides a drop-in Playwright `test` fixture. During
+`stacknext capture`, it injects W3C trace context into browser requests, probes
+the collector for the resulting server trace and submits verified samples for
+the scenario.
+
+## Who should read this
+
+Teams using runtime regression testing. This is an **optional public
+integration package**; projects that do not capture Playwright runs do not need
+it.
+
+## Installation
+
+```bash
+pnpm add -D @stacknext/playwright @playwright/test
+```
+
+`@playwright/test >=1.40.0 <2` is an optional peer dependency. The package is
+inert outside an active capture run.
+
+## Basic setup
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:330156cdeba17c62fdd7205ba9dfb6a1e4eeadd469e4d3cbdc5b72304a6c1817 -->
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  workers: 1,
+  use: { baseURL: 'http://127.0.0.1:4402' },
+})
+```
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+```ts
+// e2e/checkout.spec.ts
+import { test, expect } from '@stacknext/playwright'
+
+test('checkout completes', async ({ page }) => {
+  await page.goto('/checkout')
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible()
+})
+```
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:7abbb61d09c1a8f57748d7bf54218ee490f41f98fa4dc39ad4aef8304527a5f6 -->
+
+Set `use.baseURL` to your running app’s actual origin (the example app uses
+`http://127.0.0.1:4402`). Run it through the CLI so the capture environment exists:
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+```bash
+stacknext capture --name baseline -- \
+  pnpm exec playwright test --workers=1 --repeat-each=3
+```
+
+Running `playwright test` directly does not capture or compare anything.
+
+## Exports
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:b5db70b760e7288ddbd50c6826a786bb63e51a6bb4cfbf97d44192f11f505f50 -->
+
+| Export | Purpose |
+| --- | --- |
+| `test` | Playwright test with the auto `stacknextCapture` fixture. |
+| `expect` | Re-exported Playwright expect. |
+| `stackNextFixtures` | Exported function returning `{ test, expect }`. |
+| `resolveCaptureConfig` | Reads and validates capture environment variables. |
+| `CaptureTransportError` | Capture configuration/transport error. |
+| `createTraceparent` | Creates a W3C trace context pair. |
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Documentation map
+
+- [Fixture](fixture.md) — annotations, identity and capture lifecycle.
+- [Correlation](correlation.md) — injection, probing and verified samples.
+- [Troubleshooting](troubleshooting.md) — missing samples and incomplete runs.
+
+## Related packages
+
+- `@stacknext/regression` owns scenario identity and sample schemas.
+- `@stacknext/cli` starts the collector and writes run records.
+- `@stacknext/next` receives the injected trace on the server.

package/docs/troubleshooting.md

@@ -0,0 +1,62 @@
+---
+title: Troubleshooting
+description: Fix missing samples, failed correlation and inactive capture fixtures.
+---
+
+# Troubleshooting
+
+## The fixture does nothing
+
+`resolveCaptureConfig()` returns `null` when capture is inactive. That is normal
+for a direct `playwright test` run. Start the test through:
+
+```bash
+stacknext capture --name candidate -- pnpm exec playwright test --workers=1
+```
+
+## `CaptureTransportError`
+
+The run is marked active but the environment is invalid. Check that
+`STACKNEXT_TEST_RUN_ID` matches `run-<16 hex>`,
+`STACKNEXT_COLLECTOR_URL` is a loopback URL and `STACKNEXT_TOKEN` is present.
+Do not set these manually; let `stacknext capture` supply them.
+
+## Samples are incomplete
+
+1. Confirm the app was started with StackNext instrumentation. The server must
+   have an active OTel provider and the W3C propagator.
+2. Check that the browser request URL is loopback or matches `baseURL`.
+3. Look at the sample's correlation reason in `stacknext runs show <run-id>` or
+   the MCP `stacknext_get_test_run` response.
+4. Confirm the app received the request before the probe timeout. Increase
+   `STACKNEXT_CAPTURE_TIMEOUT_MS` only when the app is genuinely slow to start.
+5. Run with one worker. Parallel workers are not supported for capture.
+
+## A scenario has no baseline match
+
+The scenario identity changed. Prefer a stable `stacknext.scenario` annotation
+and keep it unchanged between the baseline and candidate. See
+[Fixture](fixture.md).
+
+## The test passes but the run exits 3
+
+Exit 3 means the child command succeeded but the captured telemetry is
+incomplete. It is not a pass. Inspect the run status and sample correlation
+before comparing.
+
+## Timeouts
+
+- `STACKNEXT_CAPTURE_SETTLE_MS` (default 500) delays the first probe.
+- `STACKNEXT_CAPTURE_TIMEOUT_MS` (default 5000) bounds probing.
+
+Very slow development servers may need a larger timeout, but a consistently
+missing document trace usually indicates broken instrumentation, not a short
+timeout.
+
+## Verify
+
+```bash
+stacknext runs list --json
+stacknext runs show <run-id> --json
+stacknext doctor
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@stacknext/playwright",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Playwright fixtures that correlate browser scenarios with StackNext server telemetry",
   "license": "MIT",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,7 +19,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/regression": "0.8.0"
+    "@stacknext/regression": "0.10.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40.0 <2"