@piwitests/instrumentation-nitro 0.67.0 → 0.69.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 +20 -0
- package/dist/environment.d.ts +44 -0
- package/dist/environment.js +66 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +15 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -44,6 +44,26 @@ export default defineNuxtConfig({ nitro: { modules: ['@piwitests/instrumentation
|
|
|
44
44
|
|
|
45
45
|
The manifest then lists every route Nitro scanned (`routes/`, `api/`) and every handler the config declares, middleware and a fallback catch-all (`/**`) left out, each with its method (`GET` for a route that answers any method), its pattern (`/api/orders/:id`) and its file relative to the git repository. Without the module, it lists only the routes the server has answered since it started (a route handler matched, so neither a 404 nor a public asset), which the reporter, reading it before any test runs, rarely sees. Nuxt pages are rendered by one catch-all route, so they are not listed: name them in a `piwi.manifest.json`.
|
|
46
46
|
|
|
47
|
+
## Server environment
|
|
48
|
+
|
|
49
|
+
Wherever capture is on, the plugin also serves `GET /__piwi/environment`: the runtime facts of the server process, so a failure that depends on the server's clock, time zone or locale can be told from one in the code. It answers JSON with these fields and no others (never another environment variable, a file path or a connection string):
|
|
50
|
+
|
|
51
|
+
| Field | Source |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `v` | `1` |
|
|
54
|
+
| `runtime` | `process.version`, as `Node.js v24.3.0` |
|
|
55
|
+
| `os`, `arch` | `os.platform()` and `os.release()`, `os.arch()` |
|
|
56
|
+
| `timeZone`, `locale` | `Intl.DateTimeFormat().resolvedOptions()` |
|
|
57
|
+
| `utcOffsetMinutes` | The local zone's offset from UTC now, in minutes |
|
|
58
|
+
| `globalization` | The ICU version and its locale data, `full` or `small`: `icu 76.1 full` |
|
|
59
|
+
| `environmentName` | `NODE_ENV` |
|
|
60
|
+
| `appVersion` | Always `null` |
|
|
61
|
+
| `hostname` | `os.hostname()` |
|
|
62
|
+
| `instance` | A random id of the process, the one the coverage endpoints name |
|
|
63
|
+
| `startedAt`, `now` | When the process started (ISO date) and the server's clock (epoch ms) |
|
|
64
|
+
|
|
65
|
+
It is served under the same rule as the route manifest: never turn capture on for a public production server, where this endpoint would describe the host to anyone who asks.
|
|
66
|
+
|
|
47
67
|
## Server coverage
|
|
48
68
|
|
|
49
69
|
A **coverage build** records, per Playwright test, the server files, functions and lines the test ran, even when the
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/** The body served at `/__piwi/environment`. */
|
|
2
|
+
export interface ServerEnvironment {
|
|
3
|
+
v: 1;
|
|
4
|
+
runtime: string | null;
|
|
5
|
+
os: string | null;
|
|
6
|
+
arch: string | null;
|
|
7
|
+
timeZone: string | null;
|
|
8
|
+
utcOffsetMinutes: number | null;
|
|
9
|
+
locale: string | null;
|
|
10
|
+
globalization: string | null;
|
|
11
|
+
environmentName: string | null;
|
|
12
|
+
appVersion: string | null;
|
|
13
|
+
hostname: string | null;
|
|
14
|
+
/** An id of the server process: another one after a restart. */
|
|
15
|
+
instance: string | null;
|
|
16
|
+
/** When the process started, as an ISO date. */
|
|
17
|
+
startedAt: string | null;
|
|
18
|
+
/** The server's clock, epoch ms. */
|
|
19
|
+
now: number | null;
|
|
20
|
+
}
|
|
21
|
+
/** Where {@link buildServerEnvironment} reads each fact from. */
|
|
22
|
+
export interface EnvironmentReaders {
|
|
23
|
+
nodeVersion: () => string;
|
|
24
|
+
platform: () => string;
|
|
25
|
+
release: () => string;
|
|
26
|
+
arch: () => string;
|
|
27
|
+
hostname: () => string;
|
|
28
|
+
resolvedOptions: () => {
|
|
29
|
+
timeZone?: string;
|
|
30
|
+
locale?: string;
|
|
31
|
+
};
|
|
32
|
+
/** `Date#getTimezoneOffset()`: minutes west of UTC. */
|
|
33
|
+
timezoneOffset: () => number;
|
|
34
|
+
icuVersion: () => string | undefined;
|
|
35
|
+
/** True when the runtime carries locale data beyond English. */
|
|
36
|
+
hasFullIcu: () => boolean;
|
|
37
|
+
nodeEnv: () => string | undefined;
|
|
38
|
+
instanceId: () => string;
|
|
39
|
+
/** Seconds since the process started. */
|
|
40
|
+
uptime: () => number;
|
|
41
|
+
now: () => number;
|
|
42
|
+
}
|
|
43
|
+
/** Builds the `/__piwi/environment` body from {@link readers}. */
|
|
44
|
+
export declare function buildServerEnvironment(readers?: EnvironmentReaders): ServerEnvironment;
|
|
@@ -0,0 +1,66 @@
|
|
|
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.
|
|
6
|
+
*/
|
|
7
|
+
import { arch, hostname, platform, release } from 'node:os';
|
|
8
|
+
import { instance } from './coverage-runtime.js';
|
|
9
|
+
const defaultReaders = {
|
|
10
|
+
nodeVersion: () => process.version,
|
|
11
|
+
platform: () => platform(),
|
|
12
|
+
release: () => release(),
|
|
13
|
+
arch: () => arch(),
|
|
14
|
+
hostname: () => hostname(),
|
|
15
|
+
resolvedOptions: () => Intl.DateTimeFormat().resolvedOptions(),
|
|
16
|
+
timezoneOffset: () => new Date().getTimezoneOffset(),
|
|
17
|
+
icuVersion: () => process.versions.icu,
|
|
18
|
+
hasFullIcu: () => Intl.DateTimeFormat.supportedLocalesOf(['fr']).length > 0,
|
|
19
|
+
nodeEnv: () => process.env.NODE_ENV,
|
|
20
|
+
instanceId: () => instance().id,
|
|
21
|
+
uptime: () => process.uptime(),
|
|
22
|
+
now: () => Date.now(),
|
|
23
|
+
};
|
|
24
|
+
/** Reads one fact, null when the reader throws or gives nothing. */
|
|
25
|
+
function read(reader) {
|
|
26
|
+
try {
|
|
27
|
+
const value = reader();
|
|
28
|
+
return value === undefined || value === '' ? null : value;
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** The ICU version and whether its locale data is `full` or `small`, e.g. `icu 76.1 full`; null without ICU. */
|
|
35
|
+
function globalization(readers) {
|
|
36
|
+
const icu = read(readers.icuVersion);
|
|
37
|
+
if (!icu)
|
|
38
|
+
return null;
|
|
39
|
+
const full = read(readers.hasFullIcu);
|
|
40
|
+
return full === null ? `icu ${icu}` : `icu ${icu} ${full ? 'full' : 'small'}`;
|
|
41
|
+
}
|
|
42
|
+
/** Builds the `/__piwi/environment` body from {@link readers}. */
|
|
43
|
+
export function buildServerEnvironment(readers = defaultReaders) {
|
|
44
|
+
const now = readers.now();
|
|
45
|
+
const options = read(readers.resolvedOptions);
|
|
46
|
+
const os = [read(readers.platform), read(readers.release)].filter(Boolean).join(' ');
|
|
47
|
+
const version = read(readers.nodeVersion);
|
|
48
|
+
const offset = read(readers.timezoneOffset);
|
|
49
|
+
const uptime = read(readers.uptime);
|
|
50
|
+
return {
|
|
51
|
+
v: 1,
|
|
52
|
+
runtime: version ? `Node.js ${version}` : null,
|
|
53
|
+
os: os || null,
|
|
54
|
+
arch: read(readers.arch),
|
|
55
|
+
timeZone: options?.timeZone || null,
|
|
56
|
+
utcOffsetMinutes: offset === null ? null : offset === 0 ? 0 : -offset,
|
|
57
|
+
locale: options?.locale || null,
|
|
58
|
+
globalization: globalization(readers),
|
|
59
|
+
environmentName: read(readers.nodeEnv),
|
|
60
|
+
appVersion: null,
|
|
61
|
+
hostname: read(readers.hostname),
|
|
62
|
+
instance: read(readers.instanceId),
|
|
63
|
+
startedAt: uptime === null ? null : new Date(now - uptime * 1000).toISOString(),
|
|
64
|
+
now,
|
|
65
|
+
};
|
|
66
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import type { NitroAppPlugin } from 'nitropack';
|
|
|
2
2
|
export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, type PiwiProbeSpec, type SignedProbe, } from './probe.js';
|
|
3
3
|
export { buildRouteManifest, recordObservedRoute, collapsePathPattern, type RouteManifest } from './manifest.js';
|
|
4
4
|
export * from './faults.js';
|
|
5
|
+
export { buildServerEnvironment, type ServerEnvironment, type EnvironmentReaders } from './environment.js';
|
|
5
6
|
export interface PiwiTestLogEntry {
|
|
6
7
|
timestamp: number;
|
|
7
8
|
level: string;
|
package/dist/index.js
CHANGED
|
@@ -5,12 +5,14 @@ import { createError } from 'h3';
|
|
|
5
5
|
import { verifyProbeHeader, ProbeNonceCache } from './probe.js';
|
|
6
6
|
import { buildRouteManifest, recordObservedRoute, matchedRoutePattern, } from './manifest.js';
|
|
7
7
|
import { declaredRoutes } from './route-table.js';
|
|
8
|
+
import { buildServerEnvironment } from './environment.js';
|
|
8
9
|
import { requestScope } from './request-scope.js';
|
|
9
10
|
import { beginRequestCoverage, collectCoverage, coverageActive, CoverageRequestError, nameRequest, parseGranularity, runCoverage, settleRequest, } from './coverage-runtime.js';
|
|
10
11
|
import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtremeFault, isDataFault, isDependencyFault, dependencyCallMatches, mutateResponseBody, appliedFaultLabel, } from './faults.js';
|
|
11
12
|
export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe.js';
|
|
12
13
|
export { buildRouteManifest, recordObservedRoute, collapsePathPattern } from './manifest.js';
|
|
13
14
|
export * from './faults.js';
|
|
15
|
+
export { buildServerEnvironment } from './environment.js';
|
|
14
16
|
const MAX_ENTRIES = 50;
|
|
15
17
|
const MAX_MSG_LENGTH = 500;
|
|
16
18
|
const MAX_STACK_FRAMES = 5;
|
|
@@ -103,6 +105,8 @@ const TEST_LOGS_DISABLED = process.env.PIWI_TEST_LOGS_DISABLED === 'true' ||
|
|
|
103
105
|
const PROBE_SECRET = process.env.PIWI_PROBE_SECRET || undefined;
|
|
104
106
|
/** The declared-surface route path the plugin serves outside production. */
|
|
105
107
|
const MANIFEST_PATH = '/__piwi/manifest';
|
|
108
|
+
/** The runtime facts of the server process, served beside the manifest. */
|
|
109
|
+
const ENVIRONMENT_PATH = '/__piwi/environment';
|
|
106
110
|
/** The coverage endpoints a coverage build serves beside the manifest. */
|
|
107
111
|
const COVERAGE_COLLECT_PATH = '/__piwi/coverage/collect';
|
|
108
112
|
const COVERAGE_RUN_PATH = '/__piwi/coverage/run';
|
|
@@ -219,9 +223,9 @@ const piwiTestLogs = (nitroApp) => {
|
|
|
219
223
|
// als.run() scope covers every hook, middleware, and route handler.
|
|
220
224
|
const originalHandler = nitroApp.h3App.handler;
|
|
221
225
|
nitroApp.h3App.handler = ((event) => {
|
|
222
|
-
// Serve the declared-surface manifest
|
|
223
|
-
// returned early when log capture is disabled):
|
|
224
|
-
// then the ones observed.
|
|
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):
|
|
228
|
+
// the manifest lists the routes the module declared, then the ones observed.
|
|
225
229
|
const requestPath = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
|
|
226
230
|
if (serveCoverage(event, requestPath))
|
|
227
231
|
return;
|
|
@@ -235,6 +239,14 @@ const piwiTestLogs = (nitroApp) => {
|
|
|
235
239
|
res.end(JSON.stringify(buildRouteManifest(routes)));
|
|
236
240
|
return;
|
|
237
241
|
}
|
|
242
|
+
if (requestPath === ENVIRONMENT_PATH) {
|
|
243
|
+
const res = event.node.res;
|
|
244
|
+
res.statusCode = 200;
|
|
245
|
+
res.setHeader('Content-Type', 'application/json');
|
|
246
|
+
res.setHeader('Cache-Control', 'no-store');
|
|
247
|
+
res.end(JSON.stringify(buildServerEnvironment()));
|
|
248
|
+
return;
|
|
249
|
+
}
|
|
238
250
|
const enclosing = als.getStore();
|
|
239
251
|
const nested = enclosing !== undefined && !enclosing.ended;
|
|
240
252
|
const coverage = nested ? enclosing.coverage : beginRequestCoverage();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@piwitests/instrumentation-nitro",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.69.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": {
|