@piwitests/instrumentation-nitro 0.68.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 +11 -11
- package/dist/environment.js +6 -4
- package/dist/index.js +7 -5
- package/dist/manifest.d.ts +3 -2
- package/dist/manifest.js +3 -2
- package/package.json +1 -1
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
152
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
package/dist/environment.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The runtime facts of the server process the plugin serves at `/__piwi/environment`
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
|
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
|
|
227
|
-
//
|
|
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
|
|
267
|
-
//
|
|
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);
|
package/dist/manifest.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The declared-surface route manifest the plugin serves at `/__piwi/manifest`
|
|
3
|
-
*
|
|
4
|
-
*
|
|
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
|
-
*
|
|
4
|
-
*
|
|
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.
|
|
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": {
|