@testrelic/playwright-analytics 2.3.18 → 2.4.0

package/README.md

@@ -125,6 +125,189 @@ 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`.
 
+## 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.
+
+### Setup
+
+**Step 1: Get your API key**
+
+Sign in to [platform.testrelic.ai](https://platform.testrelic.ai) and generate an API key from **Settings → API Keys**.
+
+**Step 2: Create the config file**
+
+Installing the package automatically creates `.testrelic/testrelic-config.json` in your project root via a `postinstall` script. If it wasn't created (e.g. in CI with `CI=true`), create it manually:
+
+```json
+{
+  "cloud": {
+    "apiKey": "$TESTRELIC_API_KEY",
+    "endpoint": "https://platform.testrelic.ai/api/v1",
+    "upload": "both"
+  },
+  "testrelic-repo": {
+    "name": "my-project"
+  }
+}
+```
+
+Replace `my-project` with the name of your repository as it should appear in the cloud dashboard. The `apiKey` value of `"$TESTRELIC_API_KEY"` is automatically resolved from the environment variable of the same name at runtime — no secrets in your config file.
+
+**Step 3: Set your API key in the environment**
+
+```bash
+export TESTRELIC_API_KEY=your_api_key_here
+```
+
+In CI, add `TESTRELIC_API_KEY` as a repository secret and pass it to the test job.
+
+**Step 4: Enable cloud upload in your Playwright config**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  reporter: [
+    ['list'],
+    [
+      '@testrelic/playwright-analytics',
+      {
+        cloud: {
+          apiKey: process.env.TESTRELIC_API_KEY,
+          endpoint: 'https://platform.testrelic.ai/api/v1',
+          upload: 'both',
+          uploadArtifacts: true,
+          artifactMaxSizeMb: 50,
+        },
+        includeActionSteps: true,
+        includeCodeSnippets: true,
+        includeNetworkStats: true,
+        includeArtifacts: true,
+        captureResponseBody: true,
+        captureRequestBody: true,
+      },
+    ],
+  ],
+  use: {
+    video: 'on',
+    screenshot: 'on',
+    trace: 'on',
+  },
+});
+```
+
+### Config File Reference
+
+The `.testrelic/testrelic-config.json` file is the project-level configuration for cloud integration. It should be committed to version control.
+
+**Full schema:**
+
+```json
+{
+  "cloud": {
+    "apiKey": "$TESTRELIC_API_KEY",
+    "endpoint": "https://platform.testrelic.ai/api/v1",
+    "upload": "both",
+    "timeout": 30000
+  },
+  "testrelic-repo": {
+    "name": "my-project"
+  },
+  "queue": {
+    "maxAge": "7d",
+    "directory": ".testrelic/queue"
+  }
+}
+```
+
+| Key | Description |
+|---|---|
+| `cloud.apiKey` | API key for authentication. Use `"$TESTRELIC_API_KEY"` to read from the environment variable. |
+| `cloud.endpoint` | Cloud API endpoint. Defaults to `https://platform.testrelic.ai/api/v1`. |
+| `cloud.upload` | Upload strategy — see [Upload Strategy](#upload-strategy) below. |
+| `cloud.timeout` | Request timeout in milliseconds (default: `30000`). |
+| `testrelic-repo.name` | Repository/project name shown in the cloud dashboard. |
+| `queue.maxAge` | How long to retain queued failed uploads before discarding (default: `"7d"`). |
+| `queue.directory` | Directory for queued uploads (default: `.testrelic/queue`). |
+
+### Upload Strategy
+
+The `upload` field controls how test data is sent to the cloud:
+
+| Value | Behaviour |
+|---|---|
+| `"realtime"` | Streams test events to the cloud as they happen. Fast feedback but skips the batch payload. |
+| `"batch"` | Sends a single complete JSON payload after all tests finish. Includes full step data. |
+| `"both"` | **Recommended.** Streams realtime events AND sends the complete batch payload at the end. Required for the Steps tab in the cloud dashboard to be populated. |
+
+> **Important:** Using `upload: "realtime"` alone skips the batch payload that the cloud platform uses to populate the Steps, navigation timeline, and network stats views. Use `"both"` to ensure all data appears in the dashboard.
+
+### Environment Variables
+
+Environment variables take the highest priority and override both reporter options and the config file:
+
+| Variable | Description |
+|---|---|
+| `TESTRELIC_API_KEY` | API key — always set this in CI secrets rather than hardcoding it. |
+| `TESTRELIC_CLOUD_ENDPOINT` | Override the API endpoint (e.g. for a self-hosted or stage deployment). |
+| `TESTRELIC_UPLOAD_STRATEGY` | Override the upload strategy (`realtime`, `batch`, or `both`). |
+| `TESTRELIC_CLOUD_TIMEOUT` | Override the request timeout in milliseconds. |
+
+**Priority order (highest wins):**
+1. Environment variables
+2. Reporter `cloud:` options in `playwright.config.ts`
+3. `.testrelic/testrelic-config.json`
+4. Built-in defaults
+
+### .gitignore Guidance
+
+The `.testrelic/` directory serves multiple purposes. Only the config file should be committed:
+
+```gitignore
+# Commit: .testrelic/testrelic-config.json
+# Ignore runtime directories:
+.testrelic/queue/
+.testrelic/cache/
+```
+
+### Migrating from Previous Versions
+
+**Config file location (v2.3.x → v2.4.0)**
+
+The config file has moved from a flat `.testrelic` file to `.testrelic/testrelic-config.json`. This prevents a filesystem conflict where the SDK needed to create a `.testrelic/` directory (for queue and cache) while the config file occupied the same path.
+
+If you have an existing `.testrelic` flat file, it still works — the SDK reads it with a deprecation warning:
+
+```
+[testrelic] Deprecation: config file ".testrelic" has moved to ".testrelic/testrelic-config.json".
+Please migrate your config file to the new location.
+```
+
+To migrate, rename the file and move it into the directory:
+
+```bash
+mkdir -p .testrelic
+mv .testrelic .testrelic/testrelic-config.json   # on Unix/macOS
+```
+
+**`project` key renamed to `testrelic-repo` (v2.3.x → v2.4.0)**
+
+The `project` config key has been renamed to `testrelic-repo` for clarity. The old key still works with a deprecation warning:
+
+```
+[testrelic] Deprecation: "project" key in config is deprecated. Rename it to "testrelic-repo".
+```
+
+Update your config file:
+
+```json
+// Before
+{ "project": { "name": "my-project" } }
+
+// After
+{ "testrelic-repo": { "name": "my-project" } }
+```
+
 ## Output Example
 
 ```jsonc
@@ -220,6 +403,21 @@ All options are passed as the second element of the reporter tuple:
 | `apiIncludeUrls` | `(string \| RegExp)[]` | `[]` (all URLs) | Only track API calls matching these patterns |
 | `apiExcludeUrls` | `(string \| RegExp)[]` | `[]` (none excluded) | Exclude API calls matching these patterns |
 
+### Cloud Upload Options
+
+Passed inside the `cloud:` key of the reporter options. These are merged with (and take priority over) the `.testrelic/testrelic-config.json` values.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cloud.apiKey` | `string` | — | API key for cloud authentication. Prefer `process.env.TESTRELIC_API_KEY`. |
+| `cloud.endpoint` | `string` | `https://platform.testrelic.ai/api/v1` | Cloud API endpoint. |
+| `cloud.upload` | `'realtime' \| 'batch' \| 'both'` | `'batch'` | Upload strategy. Use `'both'` to populate all cloud dashboard views including Steps. |
+| `cloud.timeout` | `number` | `30000` | Request timeout in milliseconds. |
+| `cloud.uploadArtifacts` | `boolean` | `true` | Upload screenshots and videos to cloud storage. |
+| `cloud.artifactMaxSizeMb` | `number` | `50` | Maximum size per artifact file in MB. Files exceeding this are skipped. |
+| `cloud.queueDirectory` | `string` | `.testrelic/queue` | Directory for queued uploads that failed and will be retried. |
+| `cloud.queueMaxAge` | `string` | `'7d'` | Maximum age for queued items before they are discarded (e.g. `'7d'`, `'24h'`). |
+
 ### Configuration Examples
 
 **Default (zero config)** — captures everything with built-in redaction: