@piwitests/instrumentation-nitro 0.69.0 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  Nitro / Nuxt server plugin for [Piwi Dashboard](https://piwitests.dev) — captures Warning and Error log entries per HTTP request and delivers them to the Piwi Dashboard reporter via the `X-Piwi-Logs` response header, and, in a coverage build, the server code each test ran.
4
4
 
5
- During a Playwright test run, the reporter reads this header from every response and stores the entries alongside the network request. The entries are then available in the Piwi Dashboard test-case view and are included in the AI diagnosis context.
5
+ During a Playwright test run, the reporter reads this header from every response and stores the entries alongside the network request. The entries are then shown with that request on the test's execution page in the Piwi Dashboard, and are included in the AI diagnosis context.
6
6
 
7
- **Active in development and test only, by default.** Capture and probe verification run only outside production, using the same Development/Test allow-list as the ASP.NET package. Controlled by the `PIWI_TEST_LOGS_DISABLED` environment variable:
7
+ **Active in development and test only, by default.** Capture and probe verification run only when `NODE_ENV` is `development` or `test`, the same Development/Test allow-list as the ASP.NET package. Controlled by the `PIWI_TEST_LOGS_DISABLED` environment variable:
8
8
 
9
9
  - unset — capture is on when `NODE_ENV` is `development` or `test`; off for any other value (`production`, `staging`, `prod`, …) and when `NODE_ENV` is not set at all, as when a built server is started with `node .output/server/index.mjs`
10
10
  - `PIWI_TEST_LOGS_DISABLED=true` — capture is off everywhere
@@ -32,7 +32,7 @@ That's all. Nitro auto-loads every file in that directory on startup (`server/pl
32
32
 
33
33
  ## Route manifest
34
34
 
35
- Outside production, the plugin serves `GET /__piwi/manifest`: the routes the app declares. The Piwi reporter fetches it when a run starts and uploads it, so a declared route no test reaches becomes a **declared, never hit** gap in the Test Map. Nitro has no route table to read while it runs, so add the package's module, which reads it when the server is bundled (again on each rebuild in development):
35
+ While capture is on, the plugin serves `GET /__piwi/manifest`: the routes the app declares. The Piwi reporter fetches it when a run starts and uploads it, so a declared route no test reaches becomes a **declared, never hit** gap in the Test Map. Nitro has no route table to read while it runs, so add the package's module, which reads it when the server is bundled (again on each rebuild in development):
36
36
 
37
37
  ```typescript
38
38
  // Standalone Nitro: nitro.config.ts
@@ -134,7 +134,7 @@ Playwright test
134
134
  └─ X-Piwi-Logs: <gzip+base64 JSON>
135
135
  └─ Piwi reporter reads header
136
136
  └─ stored as serverLogs on the network request
137
- └─ visible in test-case detail + AI diagnosis
137
+ └─ visible on the execution page + AI diagnosis
138
138
  ```
139
139
 
140
140
  The plugin wraps Nitro's root H3 handler and uses three mechanisms:
@@ -148,11 +148,11 @@ The plugin wraps Nitro's root H3 handler and uses three mechanisms:
148
148
  The plugin accepts a signed fault instruction from a Piwi probe run (Test Map,
149
149
  level two), so a passing test can be checked against the server's real error
150
150
  path. A verified header is always recorded on the request scope
151
- (`event.context._piwiProbe`); a fault is **applied** only once a project turns
152
- server probes on (`PIWI_SERVER_PROBES=true`), which stays off by default.
151
+ (`event.context._piwiProbe`); a fault is **applied** only when the server runs with
152
+ `PIWI_SERVER_PROBES=true`, off by default, and the project has server probes on in the dashboard.
153
153
 
154
- The header is honored only outside production, under the **same guard as log
155
- capture** (`PIWI_TEST_LOGS_DISABLED`), and only when a shared secret is set:
154
+ The header is honored only while capture is on, under the **same guard as log
155
+ capture** (`NODE_ENV` and `PIWI_TEST_LOGS_DISABLED`), and only when a shared secret is set:
156
156
 
157
157
  | Variable | Effect |
158
158
  |----------------------|-------------------------------------------------------------------|
@@ -171,9 +171,9 @@ dependency; when no call matches, nothing is applied). The plugin reports
171
171
  the fault it actually applied in `X-Piwi-Trace` (root-span `piwi.probe.applied`),
172
172
  so a probe the server did not honor is recorded as **inconclusive**, never a pass.
173
173
 
174
- **Entry condition.** Turn this on when the client probes (level one) report
175
- "not-noticed" on at least one in ten probed pairs across your pilot projects —
176
- that is the signal the suite has false comfort the network boundary cannot reveal.
174
+ **Entry condition (experimental, unmeasured).** Turn this on when the client probes (level one) report
175
+ "not-noticed" on at least one in ten probed pairs across your pilot projects — the signal that the suite has false
176
+ comfort the network boundary cannot reveal.
177
177
 
178
178
  **Header format.** `X-Piwi-Probe` carries a base64-encoded JSON envelope:
179
179
 
@@ -1,8 +1,10 @@
1
1
  /**
2
- * The runtime facts of the server process the plugin serves at `/__piwi/environment` outside production: the
3
- * runtime, the operating system, the time zone, the locale and when the process started. The Piwi reporter reads it as
4
- * a test first reaches the server and again as the run's last test ends, so a failure that depends on the server's clock, zone or locale can be told from one in the code. It
5
- * carries only the fields below: never other environment variables, file paths or connection strings.
2
+ * The runtime facts of the server process the plugin serves at `/__piwi/environment` while capture is on (`NODE_ENV`
3
+ * `development` or `test`, unless `PIWI_TEST_LOGS_DISABLED` says otherwise): the runtime, the operating system, the
4
+ * time zone, the locale and when the process started. The Piwi reporter reads it as a test first reaches the server and
5
+ * again as the run's last test ends, so a failure that depends on the server's clock, zone or locale can be told from
6
+ * one in the code. It carries only the fields below: never other environment variables, file paths or connection
7
+ * strings.
6
8
  */
7
9
  import { arch, hostname, platform, release } from 'node:os';
8
10
  import { instance } from './coverage-runtime.js';
package/dist/index.js CHANGED
@@ -103,7 +103,7 @@ const TEST_LOGS_DISABLED = process.env.PIWI_TEST_LOGS_DISABLED === 'true' ||
103
103
  (!IS_DEV_OR_TEST && process.env.PIWI_TEST_LOGS_DISABLED !== 'false');
104
104
  /** The shared secret a probe run signs the `X-Piwi-Probe` header with. */
105
105
  const PROBE_SECRET = process.env.PIWI_PROBE_SECRET || undefined;
106
- /** The declared-surface route path the plugin serves outside production. */
106
+ /** The declared-surface route path the plugin serves while capture is on (`NODE_ENV` `development` or `test`). */
107
107
  const MANIFEST_PATH = '/__piwi/manifest';
108
108
  /** The runtime facts of the server process, served beside the manifest. */
109
109
  const ENVIRONMENT_PATH = '/__piwi/environment';
@@ -223,8 +223,8 @@ const piwiTestLogs = (nitroApp) => {
223
223
  // als.run() scope covers every hook, middleware, and route handler.
224
224
  const originalHandler = nitroApp.h3App.handler;
225
225
  nitroApp.h3App.handler = ((event) => {
226
- // Serve the declared-surface manifest and the process's runtime facts outside
227
- // production (the plugin already returned early when log capture is disabled):
226
+ // Serve the declared-surface manifest and the process's runtime facts while log
227
+ // capture is on (the plugin already returned early when it is off):
228
228
  // the manifest lists the routes the module declared, then the ones observed.
229
229
  const requestPath = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
230
230
  if (serveCoverage(event, requestPath))
@@ -263,8 +263,10 @@ const piwiTestLogs = (nitroApp) => {
263
263
  // driven by the layer above h3App.handler), so als.getStore() is unreliable
264
264
  // there — reach the request store through the event context instead.
265
265
  event.context._piwiStore = store;
266
- // Verify a signed probe header, honored only outside production (under the
267
- // same guard as log capture) and only when a shared secret is configured.
266
+ // Verify a signed probe header, honored only while capture is on (the same
267
+ // guard as log capture: NODE_ENV `development` or `test`, unless
268
+ // PIWI_TEST_LOGS_DISABLED says otherwise) and only when a shared secret is
269
+ // configured.
268
270
  // The spec is recorded on the request scope, and a fault is applied only when
269
271
  // server probes are turned on for the project and this is the Nth match.
270
272
  const probe = verifyProbeHeader(event.node.req.headers['x-piwi-probe'], PROBE_SECRET, Date.now(), undefined, probeNonces);
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * The declared-surface route manifest the plugin serves at `/__piwi/manifest`
3
- * outside production. Nitro has no stable public API to enumerate its route table
4
- * at runtime: the module (`./module`) reads it at build time (`route-table.ts`),
3
+ * while capture is on (`NODE_ENV` `development` or `test`, unless
4
+ * `PIWI_TEST_LOGS_DISABLED` says otherwise). Nitro has no stable public API to
5
+ * enumerate its route table at runtime: the module (`./module`) reads it at build time (`route-table.ts`),
5
6
  * and the routes the server matches are added as they come, each request with its
6
7
  * method, matched pattern and handler file. The Piwi reporter fetches it once at
7
8
  * run start and uploads it, and a declared route no test reaches becomes a
package/dist/manifest.js CHANGED
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * The declared-surface route manifest the plugin serves at `/__piwi/manifest`
3
- * outside production. Nitro has no stable public API to enumerate its route table
4
- * at runtime: the module (`./module`) reads it at build time (`route-table.ts`),
3
+ * while capture is on (`NODE_ENV` `development` or `test`, unless
4
+ * `PIWI_TEST_LOGS_DISABLED` says otherwise). Nitro has no stable public API to
5
+ * enumerate its route table at runtime: the module (`./module`) reads it at build time (`route-table.ts`),
5
6
  * and the routes the server matches are added as they come, each request with its
6
7
  * method, matched pattern and handler file. The Piwi reporter fetches it once at
7
8
  * run start and uploads it, and a declared route no test reaches becomes a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@piwitests/instrumentation-nitro",
3
- "version": "0.69.0",
3
+ "version": "0.70.0",
4
4
  "description": "Nitro/Nuxt server plugin for Piwi Dashboard: backend logs (X-Piwi-Logs), server spans, probes, the route manifest and per-test server coverage",
5
5
  "homepage": "https://piwitests.dev",
6
6
  "repository": {