@testrelic/playwright-analytics 2.4.10-next.6 → 2.4.10-next.8

package/README.md

@@ -22,10 +22,27 @@ When you run your Playwright tests with the TestRelic reporter and fixture, you
 
 ### 1. Install
 
+Install `@testrelic/playwright-analytics` alongside `@playwright/test` (a required peer dependency):
+
 ```bash
-npm install @testrelic/playwright-analytics
+# npm
+npm install -D @playwright/test @testrelic/playwright-analytics
+
+# pnpm
+pnpm add -D @playwright/test @testrelic/playwright-analytics
+
+# yarn
+yarn add -D @playwright/test @testrelic/playwright-analytics
 ```
 
+If your project already has `@playwright/test` installed, just add `@testrelic/playwright-analytics`. Any version `>=1.35.0` of Playwright is compatible.
+
+#### Installation notes
+
+- **Peer dependency:** `@playwright/test` must be a direct dependency in the same project. If you see a peer dependency warning from pnpm or npm after installing only `@testrelic/playwright-analytics`, install `@playwright/test` explicitly as shown above — this is a tooling hint, not a TestRelic bug.
+
+- **Postinstall:** On a fresh install (outside CI), the package prints a line like `[testrelic] Created .testrelic/testrelic-config.json`. This is intentional — it scaffolds a config file at your project root for cloud upload. Update `testrelic-repo.name` to match your project and set `TESTRELIC_API_KEY` in your environment before using cloud features. In CI environments where `CI=true` or `CI=1`, the script is skipped automatically; create the config file manually if needed. See [Cloud Integration](#cloud-integration) for full details.
+
 ### 2. Add the reporter to your Playwright config
 
 **Option A: Use `defineConfig` (recommended)** — automatically enables video, screenshots, trace capture, and the TestRelic reporter:
@@ -125,6 +142,57 @@ npx playwright test
 
 The JSON report will be written to `./test-results/analytics-timeline.json` and the HTML report to `./test-results/analytics-timeline.html`.
 
+## Troubleshooting
+
+### `require() of ES Module … fixture.js`
+
+**Symptom:** Running `npx playwright test` throws an error like:
+
+```
+Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/@testrelic/playwright-analytics/dist/fixture.js not supported.
+```
+
+**Cause:** Your project's TypeScript or Playwright configuration compiles test files as **CommonJS**. When a CJS module calls `require('@testrelic/playwright-analytics/fixture')`, some toolchains mis-resolve the subpath export to the ESM build (`fixture.js`) instead of the CJS build (`fixture.cjs`).
+
+**Fix — Option A (recommended): Run tests as ESM**
+
+Add `"type": "module"` to your project's `package.json`, or configure TypeScript to emit ESM:
+
+```json
+// package.json
+{ "type": "module" }
+```
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "NodeNext",   // or "ESNext"
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+**Fix — Option B: Use the explicit CJS subpath**
+
+Import the CJS build via the dedicated subpath export (no deep `node_modules` path needed):
+
+```typescript
+// base-test.ts or your fixture wrapper
+import { test, expect } from '@testrelic/playwright-analytics/fixture/cjs';
+```
+
+```typescript
+// api tests
+import { testRelicApiFixture } from '@testrelic/playwright-analytics/api-fixture/cjs';
+```
+
+This is stable across version upgrades and pnpm/npm layouts.
+
+### `[testrelic] No API key configured`
+
+This message is printed when `TESTRELIC_API_KEY` is not set in the environment the test process sees. **Local HTML/JSON reports are still written** — this only affects cloud upload. Set the key in your shell or CI secrets; see [Cloud Integration](#cloud-integration).
+
 ## Cloud Integration
 
 TestRelic can upload test results, action steps, artifacts (screenshots, videos), and network logs directly to the [TestRelic cloud platform](https://platform.testrelic.ai) for team-wide visibility, historical tracking, and the interactive Steps dashboard.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testrelic/playwright-analytics",
-  "version": "2.4.10-next.6",
+  "version": "2.4.10-next.8",
   "description": "Playwright test analytics reporter with E2E navigation tracking, API call capture, network stats, failure diagnostics, and interactive HTML reports",
   "keywords": [
     "playwright",
@@ -47,6 +47,10 @@
         "default": "./dist/fixture.cjs"
       }
     },
+    "./fixture/cjs": {
+      "types": "./dist/fixture.d.cts",
+      "default": "./dist/fixture.cjs"
+    },
     "./api-fixture": {
       "import": {
         "types": "./dist/api-fixture.d.ts",
@@ -57,6 +61,10 @@
         "default": "./dist/api-fixture.cjs"
       }
     },
+    "./api-fixture/cjs": {
+      "types": "./dist/api-fixture.d.cts",
+      "default": "./dist/api-fixture.cjs"
+    },
     "./merge": {
       "import": {
         "types": "./dist/merge.d.ts",
@@ -82,7 +90,7 @@
     "@playwright/test": ">=1.35.0"
   },
   "dependencies": {
-    "@testrelic/core": "2.4.10-next.6"
+    "@testrelic/core": "2.4.10-next.8"
   },
   "devDependencies": {
     "@playwright/test": "^1.35.0",