@piwitests/instrumentation-nitro 0.72.0 → 0.73.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
@@ -57,13 +57,25 @@ Wherever capture is on, the plugin also serves `GET /__piwi/environment`: the ru
57
57
  | `utcOffsetMinutes` | The local zone's offset from UTC now, in minutes |
58
58
  | `globalization` | The ICU version and its locale data, `full` or `small`: `icu 76.1 full` |
59
59
  | `environmentName` | `NODE_ENV` |
60
- | `appVersion` | Always `null` |
60
+ | `appVersion` | The plugin's `appVersion` option, else `PIWI_APP_VERSION`, else `null` |
61
+ | `appCommit` | The commit the application was built from (below) |
61
62
  | `hostname` | `os.hostname()` |
62
63
  | `instance` | A random id of the process, the one the coverage endpoints name |
63
64
  | `startedAt`, `now` | When the process started (ISO date) and the server's clock (epoch ms) |
64
65
 
65
66
  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
67
 
68
+ `appVersion` and `appCommit` tell the dashboard which version of the application a run tested, for an environment deployed apart from the tests' checkout. `appCommit` is the first of these that holds 7 to 40 hexadecimal characters, lower-cased, else `null`: the plugin's `appCommit` option, `PIWI_APP_COMMIT`, then the commit variable of the hosting platform the server runs on (`VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`, `SOURCE_COMMIT`). To set the options, export the plugin from `piwiPlugin` in place of the default export:
69
+
70
+ ```typescript
71
+ // Nuxt: server/plugins/piwi-test-logs.ts
72
+ import { piwiPlugin } from '@piwitests/instrumentation-nitro'
73
+
74
+ export default piwiPlugin({ appVersion: '1.4.0', appCommit: process.env.GIT_COMMIT })
75
+ ```
76
+
77
+ Where capture is off (production, by default), nothing serves it: post a deploy marker with the commit from the deploy pipeline instead ([Timeline markers](https://piwitests.dev/features/timeline-markers)).
78
+
67
79
  ## Server coverage
68
80
 
69
81
  A **coverage build** records, per Playwright test, the server files, functions and lines the test ran, even when the
@@ -10,6 +10,8 @@ export interface ServerEnvironment {
10
10
  globalization: string | null;
11
11
  environmentName: string | null;
12
12
  appVersion: string | null;
13
+ /** The commit the application was built from: 7 to 40 hexadecimal characters, lower-cased. */
14
+ appCommit: string | null;
13
15
  hostname: string | null;
14
16
  /** An id of the server process: another one after a restart. */
15
17
  instance: string | null;
@@ -18,6 +20,17 @@ export interface ServerEnvironment {
18
20
  /** The server's clock, epoch ms. */
19
21
  now: number | null;
20
22
  }
23
+ /** What the plugin's options say of the application (`piwiPlugin`); each one left unset is read from the environment. */
24
+ export interface PiwiPluginOptions {
25
+ /** The application's version, served as `appVersion`. Unset: `PIWI_APP_VERSION`, else null. */
26
+ appVersion?: string | null;
27
+ /**
28
+ * The commit the application was built from, served as `appCommit`. Unset: `PIWI_APP_COMMIT`, then the commit
29
+ * variable of the hosting platform (`VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`,
30
+ * `SOURCE_COMMIT`). Kept only when it is 7 to 40 hexadecimal characters.
31
+ */
32
+ appCommit?: string | null;
33
+ }
21
34
  /** Where {@link buildServerEnvironment} reads each fact from. */
22
35
  export interface EnvironmentReaders {
23
36
  nodeVersion: () => string;
@@ -35,10 +48,12 @@ export interface EnvironmentReaders {
35
48
  /** True when the runtime carries locale data beyond English. */
36
49
  hasFullIcu: () => boolean;
37
50
  nodeEnv: () => string | undefined;
51
+ /** An environment variable of the process; `process.env` when left out. */
52
+ variable?: (name: string) => string | undefined;
38
53
  instanceId: () => string;
39
54
  /** Seconds since the process started. */
40
55
  uptime: () => number;
41
56
  now: () => number;
42
57
  }
43
- /** Builds the `/__piwi/environment` body from {@link readers}. */
44
- export declare function buildServerEnvironment(readers?: EnvironmentReaders): ServerEnvironment;
58
+ /** Builds the `/__piwi/environment` body from {@link readers} and the plugin's options. */
59
+ export declare function buildServerEnvironment(readers?: EnvironmentReaders, app?: PiwiPluginOptions): ServerEnvironment;
@@ -4,10 +4,21 @@
4
4
  * time zone, the locale and when the process started. The Piwi reporter reads it as a test first reaches the server and
5
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
6
  * one in the code. It carries only the fields below: never other environment variables, file paths or connection
7
- * strings.
7
+ * strings. `appVersion` and `appCommit` say which version of the application a run tested, for an environment deployed
8
+ * apart from the tests' checkout.
8
9
  */
9
10
  import { arch, hostname, platform, release } from 'node:os';
10
11
  import { instance } from './coverage-runtime.js';
12
+ const APP_VERSION_VARIABLE = 'PIWI_APP_VERSION';
13
+ /** Where the commit is read from after the option, in this order: Piwi's own variable, then the hosting platforms'. */
14
+ const APP_COMMIT_VARIABLES = [
15
+ 'PIWI_APP_COMMIT',
16
+ 'VERCEL_GIT_COMMIT_SHA',
17
+ 'RENDER_GIT_COMMIT',
18
+ 'RAILWAY_GIT_COMMIT_SHA',
19
+ 'SOURCE_COMMIT',
20
+ ];
21
+ const COMMIT = /^[0-9a-f]{7,40}$/i;
11
22
  const defaultReaders = {
12
23
  nodeVersion: () => process.version,
13
24
  platform: () => platform(),
@@ -19,10 +30,15 @@ const defaultReaders = {
19
30
  icuVersion: () => process.versions.icu,
20
31
  hasFullIcu: () => Intl.DateTimeFormat.supportedLocalesOf(['fr']).length > 0,
21
32
  nodeEnv: () => process.env.NODE_ENV,
33
+ variable: (name) => readProcessVariable(name),
22
34
  instanceId: () => instance().id,
23
35
  uptime: () => process.uptime(),
24
36
  now: () => Date.now(),
25
37
  };
38
+ /** An environment variable of the process. */
39
+ function readProcessVariable(name) {
40
+ return process.env[name];
41
+ }
26
42
  /** Reads one fact, null when the reader throws or gives nothing. */
27
43
  function read(reader) {
28
44
  try {
@@ -41,8 +57,17 @@ function globalization(readers) {
41
57
  const full = read(readers.hasFullIcu);
42
58
  return full === null ? `icu ${icu}` : `icu ${icu} ${full ? 'full' : 'small'}`;
43
59
  }
44
- /** Builds the `/__piwi/environment` body from {@link readers}. */
45
- export function buildServerEnvironment(readers = defaultReaders) {
60
+ /** The first of the option and the commit variables that holds 7 to 40 hexadecimal characters, lower-cased; else null. */
61
+ function appCommit(option, readers) {
62
+ for (const candidate of [option, ...APP_COMMIT_VARIABLES.map((name) => read(() => (readers.variable ?? readProcessVariable)(name)))]) {
63
+ const commit = candidate?.trim();
64
+ if (commit && COMMIT.test(commit))
65
+ return commit.toLowerCase();
66
+ }
67
+ return null;
68
+ }
69
+ /** Builds the `/__piwi/environment` body from {@link readers} and the plugin's options. */
70
+ export function buildServerEnvironment(readers = defaultReaders, app = {}) {
46
71
  const now = readers.now();
47
72
  const options = read(readers.resolvedOptions);
48
73
  const os = [read(readers.platform), read(readers.release)].filter(Boolean).join(' ');
@@ -59,7 +84,8 @@ export function buildServerEnvironment(readers = defaultReaders) {
59
84
  locale: options?.locale || null,
60
85
  globalization: globalization(readers),
61
86
  environmentName: read(readers.nodeEnv),
62
- appVersion: null,
87
+ appVersion: read(() => app.appVersion?.trim() || (readers.variable ?? readProcessVariable)(APP_VERSION_VARIABLE)?.trim()),
88
+ appCommit: appCommit(app.appCommit, readers),
63
89
  hostname: read(readers.hostname),
64
90
  instance: read(readers.instanceId),
65
91
  startedAt: uptime === null ? null : new Date(now - uptime * 1000).toISOString(),
package/dist/index.d.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import type { NitroAppPlugin } from 'nitropack';
2
+ import { type PiwiPluginOptions } from './environment.js';
2
3
  export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, type PiwiProbeSpec, type SignedProbe, } from './probe.js';
3
4
  export { buildRouteManifest, recordObservedRoute, collapsePathPattern, type RouteManifest } from './manifest.js';
4
5
  export * from './faults.js';
5
- export { buildServerEnvironment, type ServerEnvironment, type EnvironmentReaders } from './environment.js';
6
+ export { buildServerEnvironment, type ServerEnvironment, type EnvironmentReaders, type PiwiPluginOptions, } from './environment.js';
6
7
  export interface PiwiTestLogEntry {
7
8
  timestamp: number;
8
9
  level: string;
@@ -44,5 +45,11 @@ export interface PiwiServerSpan {
44
45
  * once the request's response has ended.
45
46
  */
46
47
  export declare function recordServerSpan(span: PiwiServerSpan): void;
48
+ /**
49
+ * The plugin with options, for a server plugin file that tells it about the application:
50
+ * `export default piwiPlugin({ appVersion: '1.4.0' })` in place of re-exporting the default export.
51
+ */
52
+ export declare function piwiPlugin(options?: PiwiPluginOptions): NitroAppPlugin;
53
+ /** The plugin, served as `export { default } from '@piwitests/instrumentation-nitro'` in a server plugin file. */
47
54
  declare const piwiTestLogs: NitroAppPlugin;
48
55
  export default piwiTestLogs;
package/dist/index.js CHANGED
@@ -12,7 +12,7 @@ import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtreme
12
12
  export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe.js';
13
13
  export { buildRouteManifest, recordObservedRoute, collapsePathPattern } from './manifest.js';
14
14
  export * from './faults.js';
15
- export { buildServerEnvironment } from './environment.js';
15
+ export { buildServerEnvironment, } from './environment.js';
16
16
  const MAX_ENTRIES = 50;
17
17
  const MAX_MSG_LENGTH = 500;
18
18
  const MAX_STACK_FRAMES = 5;
@@ -193,7 +193,14 @@ function resolveHandlerFile(event) {
193
193
  const file = matched?.file ?? matched?.filename;
194
194
  return typeof file === 'string' && file ? file : undefined;
195
195
  }
196
- const piwiTestLogs = (nitroApp) => {
196
+ /**
197
+ * The plugin with options, for a server plugin file that tells it about the application:
198
+ * `export default piwiPlugin({ appVersion: '1.4.0' })` in place of re-exporting the default export.
199
+ */
200
+ export function piwiPlugin(options = {}) {
201
+ return (nitroApp) => install(nitroApp, options);
202
+ }
203
+ function install(nitroApp, options) {
197
204
  if (TEST_LOGS_DISABLED)
198
205
  return;
199
206
  const globals = globalThis;
@@ -244,7 +251,7 @@ const piwiTestLogs = (nitroApp) => {
244
251
  res.statusCode = 200;
245
252
  res.setHeader('Content-Type', 'application/json');
246
253
  res.setHeader('Cache-Control', 'no-store');
247
- res.end(JSON.stringify(buildServerEnvironment()));
254
+ res.end(JSON.stringify(buildServerEnvironment(undefined, options)));
248
255
  return;
249
256
  }
250
257
  const enclosing = als.getStore();
@@ -454,7 +461,7 @@ const piwiTestLogs = (nitroApp) => {
454
461
  g.$fetch = Object.assign(patched, original);
455
462
  }
456
463
  }
457
- };
464
+ }
458
465
  /** The request target of an outbound `$fetch` call, for dependency-fault matching. */
459
466
  function outboundCallTarget(args) {
460
467
  const first = args[0];
@@ -469,4 +476,6 @@ function outboundCallTarget(args) {
469
476
  }
470
477
  return '';
471
478
  }
479
+ /** The plugin, served as `export { default } from '@piwitests/instrumentation-nitro'` in a server plugin file. */
480
+ const piwiTestLogs = piwiPlugin();
472
481
  export default piwiTestLogs;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@piwitests/instrumentation-nitro",
3
- "version": "0.72.0",
3
+ "version": "0.73.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": {