@piwitests/reporter 0.5.0 → 0.6.0

package/README.md

@@ -12,7 +12,34 @@ npm install --save-dev @piwitests/reporter
 
 ## Quick start
 
-Add the reporter to your `playwright.config.ts`:
+`wrapConfig` is the recommended setup. It injects the reporter **and** a global
+setup step (so the run shows up as "initialising" while your `globalSetup` runs),
+and forwards your options to that setup:
+
+```typescript
+import { defineConfig } from '@playwright/test'
+import { wrapConfig } from '@piwitests/reporter'
+
+export default wrapConfig(
+  defineConfig({
+    use: {
+      trace: 'retain-on-failure',
+    },
+  }),
+  {
+    serverUrl: 'http://localhost:3000',
+    projectName: 'my-project',
+  },
+)
+```
+
+Run your tests — results are uploaded automatically:
+
+```bash
+npx playwright test
+```
+
+Prefer to wire it up by hand? Add the reporter to the `reporter` array instead:
 
 ```typescript
 import { defineConfig } from '@playwright/test'
@@ -31,12 +58,6 @@ export default defineConfig({
 })
 ```
 
-Run your tests — results are uploaded automatically:
-
-```bash
-npx playwright test
-```
-
 ## Configuration Options
 
 | Option                      | Type     | Default                   | Description                                                            |
@@ -109,16 +130,20 @@ To capture network request timing and browser Web Vitals, use the provided fixtu
 ```typescript
 // tests/fixtures.ts
 import { test as base, expect } from '@playwright/test'
-import { dashboardFixtures } from '@piwitests/reporter/fixtures'
+import { dashboardFixtures } from '@piwitests/reporter'
 
 export const test = base.extend(dashboardFixtures)
 export { expect }
 ```
 
-Or as a drop-in replacement:
+Or extend the base `test` in one line with `extendDashboardFixtures`:
 
 ```typescript
-import { test, expect } from '@piwitests/reporter/fixtures'
+import { test as base } from '@playwright/test'
+import { extendDashboardFixtures } from '@piwitests/reporter'
+
+export const test = extendDashboardFixtures(base)
+export { expect } from '@playwright/test'
 ```
 
 ### What gets captured
@@ -192,21 +217,7 @@ npm run reporter:dev     # watch mode — auto-recompile on changes
 
 ### Source layout
 
-| File                       | Responsibility                              |
-|----------------------------|---------------------------------------------|
-| `src/reporter.ts`          | Orchestrator — Playwright hooks + fallback  |
-| `src/config.ts`            | Options interface + defaults                |
-| `src/http-client.ts`       | HTTP transport layer                        |
-| `src/uploader.ts`          | Upload strategies (JSON, multipart)         |
-| `src/stream-buffer.ts`     | Persistent JSONL buffer                     |
-| `src/crash-recovery.ts`    | Recovery data management                    |
-| `src/file-handler.ts`      | Report/trace/attachment file operations     |
-| `src/metadata-collector.ts`| CI, SCM, Playwright config metadata         |
-| `src/step-analyzer.ts`     | Step categorization + performance analysis  |
-| `src/helpers.ts`           | Pure utility functions                      |
-| `src/compression.ts`       | Directory gzip archiver                     |
-| `src/fixtures.ts`          | Playwright fixtures                         |
-| `src/index.ts`             | Package entry point                         |
+The package keeps its **public API** (`src/index.ts`, `src/fixtures.ts`, `src/public/`) separate from internal plumbing (`src/internal/<domain>/`) and the type model (`src/types/`). See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full map — the public/internal split, the collect-and-submit data flow, the fallback ladder, and the conventions.
 
 The `package.json` `exports` field maps the main entry and `./fixtures` to their `dist/` counterparts.
 
@@ -220,7 +231,7 @@ The `package.json` `exports` field maps the main entry and `./fixtures` to their
 
 ### Network/Web Vitals not appearing
 
-- Import `test` from `@piwitests/reporter/fixtures` (or extend with `dashboardFixtures`)
+- Extend your `test` with `dashboardFixtures` / `extendDashboardFixtures` from `@piwitests/reporter`
 - Verify `collectPerformanceMetrics` is not set to `false`
 - Ensure tests navigate to at least one page (`await page.goto(...)`)
 

package/dist/global-setup-module.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const helpers_js_1 = require("./helpers.js");
-exports.default = (0, helpers_js_1.createGlobalSetup)();
+const global_setup_js_1 = require("./public/global-setup.js");
+exports.default = (0, global_setup_js_1.createGlobalSetup)();

package/dist/index.d.ts

@@ -1,6 +1,15 @@
-import { PiwiDashboardReporter } from './reporter.js';
+/**
+ * Public API of `@piwitests/reporter`.
+ *
+ * This barrel is the *entire* external surface of the package — the reporter
+ * class, the config helpers, the capture fixtures, and the public types.
+ * Everything under `internal/` is deliberately NOT re-exported here; if it isn't
+ * exported from this file, it isn't part of the supported API.
+ */
+import { PiwiDashboardReporter } from './public/reporter.js';
 export default PiwiDashboardReporter;
 export { PiwiDashboardReporter };
-export { wrapConfig } from './config-wrapper.js';
-export { createGlobalSetup } from './helpers.js';
-export type { PiwiDashboardOptions, PlaywrightTestConfig } from './config.js';
+export { wrapConfig } from './public/config-wrapper.js';
+export { createGlobalSetup } from './public/global-setup.js';
+export { dashboardFixtures, extendDashboardFixtures } from './internal/capture/capture-fixtures.js';
+export type { PiwiDashboardOptions, PlaywrightTestConfig } from './public/options.js';

package/dist/index.js

@@ -1,10 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGlobalSetup = exports.wrapConfig = exports.PiwiDashboardReporter = void 0;
-const reporter_js_1 = require("./reporter.js");
+exports.extendDashboardFixtures = exports.dashboardFixtures = exports.createGlobalSetup = exports.wrapConfig = exports.PiwiDashboardReporter = void 0;
+/**
+ * Public API of `@piwitests/reporter`.
+ *
+ * This barrel is the *entire* external surface of the package — the reporter
+ * class, the config helpers, the capture fixtures, and the public types.
+ * Everything under `internal/` is deliberately NOT re-exported here; if it isn't
+ * exported from this file, it isn't part of the supported API.
+ */
+const reporter_js_1 = require("./public/reporter.js");
 Object.defineProperty(exports, "PiwiDashboardReporter", { enumerable: true, get: function () { return reporter_js_1.PiwiDashboardReporter; } });
+// ── Reporter (default + named export) ────────────────────────────────────────
 exports.default = reporter_js_1.PiwiDashboardReporter;
-var config_wrapper_js_1 = require("./config-wrapper.js");
+// ── Config helpers ───────────────────────────────────────────────────────────
+var config_wrapper_js_1 = require("./public/config-wrapper.js");
 Object.defineProperty(exports, "wrapConfig", { enumerable: true, get: function () { return config_wrapper_js_1.wrapConfig; } });
-var helpers_js_1 = require("./helpers.js");
-Object.defineProperty(exports, "createGlobalSetup", { enumerable: true, get: function () { return helpers_js_1.createGlobalSetup; } });
+var global_setup_js_1 = require("./public/global-setup.js");
+Object.defineProperty(exports, "createGlobalSetup", { enumerable: true, get: function () { return global_setup_js_1.createGlobalSetup; } });
+// ── Capture fixtures ─────────────────────────────────────────────────────────
+var capture_fixtures_js_1 = require("./internal/capture/capture-fixtures.js");
+Object.defineProperty(exports, "dashboardFixtures", { enumerable: true, get: function () { return capture_fixtures_js_1.dashboardFixtures; } });
+Object.defineProperty(exports, "extendDashboardFixtures", { enumerable: true, get: function () { return capture_fixtures_js_1.extendDashboardFixtures; } });

package/dist/internal/capture/attachments.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Names of the `testInfo` attachments the dashboard fixtures produce and the
+ * reporter parses. Single source of truth — imported by the producer
+ * (`fixtures.ts`), the consumers (`reporter.ts` / `file-handler.ts`), and the
+ * dogfooding `application/tests/fixtures.ts`, so producer and consumer can
+ * never drift on a name.
+ */
+export declare const ATTACHMENT_NAMES: {
+    readonly locators: "piwi-locators";
+    readonly ariaSnapshot: "piwi-aria-snapshot";
+    readonly console: "piwi-console";
+    readonly network: "piwi-network";
+    readonly webVitals: "piwi-web-vitals";
+    readonly locatorSuggestion: "piwi-locator-suggestion";
+};
+/** Set of every internal attachment name — used to skip them when collecting user attachments. */
+export declare const INTERNAL_ATTACHMENT_NAMES: ReadonlySet<string>;
+/** Annotation type that surfaces a locator-healing suggestion in the report/trace. */
+export declare const LOCATOR_SUGGESTION_ANNOTATION: "piwi-locator-suggestion";

package/dist/internal/capture/attachments.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCATOR_SUGGESTION_ANNOTATION = exports.INTERNAL_ATTACHMENT_NAMES = exports.ATTACHMENT_NAMES = void 0;
+/**
+ * Names of the `testInfo` attachments the dashboard fixtures produce and the
+ * reporter parses. Single source of truth — imported by the producer
+ * (`fixtures.ts`), the consumers (`reporter.ts` / `file-handler.ts`), and the
+ * dogfooding `application/tests/fixtures.ts`, so producer and consumer can
+ * never drift on a name.
+ */
+exports.ATTACHMENT_NAMES = {
+    locators: 'piwi-locators',
+    ariaSnapshot: 'piwi-aria-snapshot',
+    console: 'piwi-console',
+    network: 'piwi-network',
+    webVitals: 'piwi-web-vitals',
+    locatorSuggestion: 'piwi-locator-suggestion',
+};
+/** Set of every internal attachment name — used to skip them when collecting user attachments. */
+exports.INTERNAL_ATTACHMENT_NAMES = new Set(Object.values(exports.ATTACHMENT_NAMES));
+/** Annotation type that surfaces a locator-healing suggestion in the report/trace. */
+exports.LOCATOR_SUGGESTION_ANNOTATION = exports.ATTACHMENT_NAMES.locatorSuggestion;

package/dist/{fixtures.d.ts → internal/capture/capture-fixtures.d.ts}

@@ -3,8 +3,10 @@ import type { Fixtures } from '@playwright/test';
  * Playwright fixtures that collect network requests, console entries,
  * web vitals, ARIA snapshots, and locator interaction data during a test.
  *
- * Attaches collected data as `piwi-dashboard-*` test-info attachments
- * which the Piwi Dashboard reporter parses on `onTestEnd`.
+ * Capture is wired at the `browser` level, so it works whether a test uses the
+ * standard `page` fixture or builds its own pages from `browser` /
+ * `browser.newContext()`. Collected data is attached as `piwi-*`
+ * test-info attachments which the Piwi Dashboard reporter parses on `onTestEnd`.
  */
 export declare const dashboardFixtures: Fixtures;
 /**
@@ -17,7 +19,7 @@ export declare const dashboardFixtures: Fixtures;
  * @example
  * ```ts
  * import { test as base } from '@playwright/test';
- * import { extendDashboardFixtures } from '@piwitests/reporter/fixtures';
+ * import { extendDashboardFixtures } from '@piwitests/reporter';
  *
  * export const test = extendDashboardFixtures(base);
  * ```