@hydranium/core 1.0.0-next.30 → 1.0.0-next.301

package/src/testing/playwright/flaky-network-proxy.ts

@@ -0,0 +1,240 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { connect, createServer as createTcpServer, type Server as TcpServer, type Socket } from 'node:net';
+
+/**
+ * A TCP proxy that can half-close a connection, so an e2e suite can reproduce a
+ * flaky network against a real browser session.
+ *
+ * Toggling the browser offline is not enough. On localhost the server sees the
+ * close immediately and reaps the socket before the browser reconnects, so the
+ * window where both sides disagree about the session — the one where reconnect
+ * defects live — never opens. Reaching it needs the browser's socket to die
+ * while the server still believes it is alive, and nothing inside the app or in
+ * Playwright's offline emulation can produce that asymmetry: both close cleanly
+ * at both ends.
+ *
+ * The proxy holds both halves of every connection and lets a test kill them
+ * independently:
+ *
+ *   `break`    destroy the BROWSER-side sockets, keep the server-side ones open.
+ *              The browser reconnects through a fresh pair while the server
+ *              still holds the old one.
+ *   `release`  destroy the orphaned server-side sockets `break` left. The
+ *              server's disconnect handler fires at once, rather than whenever
+ *              its next heartbeat write would have failed.
+ */
+
+/** Where the proxy listens, and the application it fronts. */
+export interface FlakyNetworkProxyOptions {
+   /** Port the browser connects to. */
+   readonly listenPort: number;
+   /** Port of the application being proxied. */
+   readonly targetPort: number;
+   /** Host of the application being proxied. Defaults to loopback. */
+   readonly targetHost?: string;
+   /** Port the HTTP control channel listens on. Defaults to `listenPort + 1000`. */
+   readonly controlPort?: number;
+}
+
+/** The commands the control channel accepts, and the proxy's own vocabulary. */
+export type FlakyNetworkCommand = 'break' | 'release' | 'status';
+
+/** Drives a running proxy. Implemented both in-process and over HTTP. */
+export interface FlakyNetworkControl {
+   /** Kill the browser side of every live connection; leave the server side up. */
+   break(): Promise<string>;
+   /** Kill the server side of every connection `break` orphaned. */
+   release(): Promise<string>;
+   /** How many connections are live and how many are orphaned. */
+   status(): Promise<string>;
+}
+
+export interface FlakyNetworkProxy extends FlakyNetworkControl {
+   /** Base URL a browser should be pointed at, i.e. Playwright's `baseURL`. */
+   readonly url: string;
+   /** Control channel, for workers that cannot reach this object directly. */
+   readonly controlUrl: string;
+   close(): Promise<void>;
+}
+
+interface ConnectionPair {
+   readonly id: number;
+   readonly browserSocket: Socket;
+   readonly targetSocket: Socket;
+   orphaned: boolean;
+}
+
+/**
+ * Starts the proxy in the calling process.
+ *
+ * Call it from a Playwright config, which runs in the main process before any
+ * worker forks. Workers are separate processes and cannot reach the returned
+ * object, which is what {@link controlUrl} and {@link flakyNetworkControlClient}
+ * are for.
+ */
+export async function startFlakyNetworkProxy(options: FlakyNetworkProxyOptions): Promise<FlakyNetworkProxy> {
+   const targetHost = options.targetHost ?? '127.0.0.1';
+   const controlPort = options.controlPort ?? options.listenPort + 1000;
+   const pairs = new Set<ConnectionPair>();
+   let sequence = 0;
+   let transcript: string[] = [];
+
+   const log = (message: string): void => {
+      transcript.push(message);
+      console.log(`[flaky-network] ${message}`);
+   };
+
+   const proxyServer: TcpServer = createTcpServer(browserSocket => {
+      const id = ++sequence;
+      const targetSocket = connect(options.targetPort, targetHost);
+      const pair: ConnectionPair = { id, browserSocket, targetSocket, orphaned: false };
+      pairs.add(pair);
+
+      // Forwarded by hand rather than with `pipe()`, so killing one side does not
+      // tear the other down — which is the entire point of the proxy.
+      browserSocket.on('data', chunk => {
+         if (!targetSocket.destroyed) {
+            targetSocket.write(chunk);
+         }
+      });
+      targetSocket.on('data', chunk => {
+         if (!pair.orphaned && !browserSocket.destroyed) {
+            browserSocket.write(chunk);
+         }
+      });
+
+      const teardown = (origin: 'browser' | 'target'): void => {
+         if (pair.orphaned && origin === 'browser') {
+            // Expected: `break` killed this side deliberately. The server side
+            // stays up until `release`.
+            return;
+         }
+         pairs.delete(pair);
+         browserSocket.destroy();
+         targetSocket.destroy();
+      };
+
+      browserSocket.on('close', () => teardown('browser'));
+      targetSocket.on('close', () => teardown('target'));
+      // A half-killed pair reliably raises ECONNRESET on the surviving side; an
+      // unhandled 'error' would take the whole runner down with it.
+      browserSocket.on('error', () => undefined);
+      targetSocket.on('error', () => undefined);
+   });
+
+   const commands: Record<FlakyNetworkCommand, () => void> = {
+      break: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned);
+         if (live.length === 0) {
+            log('nothing to break');
+            return;
+         }
+         for (const pair of live) {
+            pair.orphaned = true;
+            pair.browserSocket.destroy();
+         }
+         log(`${live.length} connection(s) broken; the browser should reconnect shortly`);
+      },
+      release: () => {
+         const orphans = [...pairs].filter(pair => pair.orphaned);
+         if (orphans.length === 0) {
+            log('no orphaned connections; run `break` first');
+            return;
+         }
+         for (const pair of orphans) {
+            pairs.delete(pair);
+            pair.targetSocket.destroy();
+         }
+         log(`${orphans.length} orphaned connection(s) destroyed; their late disconnect fires now`);
+      },
+      status: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned).length;
+         const orphaned = pairs.size - live;
+         log(`${live} live, ${orphaned} orphaned`);
+      }
+   };
+
+   const run = (name: string): string => {
+      transcript = [];
+      const command = commands[name as FlakyNetworkCommand];
+      if (command) {
+         command();
+      } else {
+         log(`unknown command '${name}'; use: ${Object.keys(commands).join(' | ')}`);
+      }
+      return transcript.join('\n');
+   };
+
+   const controlServer: HttpServer = createHttpServer((request, response) => {
+      const output = run((request.url ?? '').replace(/^\//, '').split('?')[0]);
+      response.writeHead(200, { 'content-type': 'text/plain' });
+      response.end(`${output}\n`);
+   });
+
+   await Promise.all([listen(proxyServer, options.listenPort), listen(controlServer, controlPort)]);
+   // Neither server keeps the process alive, so a runner that starts one from a
+   // config does not need a teardown hook to exit — and a caller that wants a
+   // deterministic shutdown still has `close()`.
+   proxyServer.unref();
+   controlServer.unref();
+
+   return {
+      url: `http://localhost:${options.listenPort}`,
+      controlUrl: `http://localhost:${controlPort}`,
+      break: async () => run('break'),
+      release: async () => run('release'),
+      status: async () => run('status'),
+      close: async () => {
+         for (const pair of pairs) {
+            pair.browserSocket.destroy();
+            pair.targetSocket.destroy();
+         }
+         pairs.clear();
+         await Promise.all([close(proxyServer), close(controlServer)]);
+      }
+   };
+}
+
+/**
+ * Drives a proxy running in another process, over its control channel.
+ *
+ * This is what a spec uses: Playwright workers are separate processes from the
+ * config that started the proxy.
+ */
+export function flakyNetworkControlClient(controlUrl: string): FlakyNetworkControl {
+   const send = async (command: FlakyNetworkCommand): Promise<string> => {
+      const response = await fetch(`${controlUrl}/${command}`);
+      if (!response.ok) {
+         throw new Error(`flaky-network proxy rejected '${command}': ${response.status}`);
+      }
+      return (await response.text()).trim();
+   };
+   return {
+      break: () => send('break'),
+      release: () => send('release'),
+      status: () => send('status')
+   };
+}
+
+function listen(server: TcpServer | HttpServer, port: number): Promise<void> {
+   return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, () => {
+         server.off('error', reject);
+         resolve();
+      });
+   });
+}
+
+function close(server: TcpServer | HttpServer): Promise<void> {
+   return new Promise(resolve => server.close(() => resolve()));
+}

package/src/testing/playwright/index.ts

@@ -11,6 +11,7 @@
 // `@hydranium/core/testing` barrel) so importing the framework's unit-test
 // helpers never pulls in `@playwright/test` — which is an OPTIONAL peer here.
 export * from './e2e-profiling.js';
+export * from './flaky-network-proxy.js';
 export * from './browser-capture-bridge.js';
 export * from './server-log-capture.js';
 export * from './server-log-fixture.js';

package/src/testing/playwright/server-log-capture.ts

@@ -10,7 +10,14 @@
 import { appendFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { DEFAULT_LOG_FILE_ENV, DEFAULT_LOG_LEVEL_ENV } from '@hydranium/protocol';
+import {
+   DEFAULT_CPU_PROFILE_FILE_ENV,
+   DEFAULT_LOG_FILE_ENV,
+   DEFAULT_LOG_FILE_LEVEL_ENV,
+   DEFAULT_LOG_LEVEL_ENV,
+   type LogThreshold,
+   parseLogLevel
+} from '@hydranium/protocol';
 import { toLogFileWorkspaceToken } from '../../langium/diagnostics/log-file-token.js';
 
 /**
@@ -20,6 +27,13 @@ import { toLogFileWorkspaceToken } from '../../langium/diagnostics/log-file-toke
  * {@link attachServerLog}.
  */
 export const DEFAULT_SERVER_LOG_DIR_ENV = 'HYDRANIUM_SERVER_LOG_DIR';
+/**
+ * Default env var opting a capture into the servers' CPU profiles: any
+ * non-empty value makes {@link captureServerLog} name a
+ * `<token>.<pid>.cpuprofile` beside each log, which each server of that
+ * workspace writes when it ends.
+ */
+export const DEFAULT_SERVER_CPU_PROFILE_ENV = 'HYDRANIUM_SERVER_CPU_PROFILE';
 /**
  * Default env var providing a central {@link AttachServerLogOptions.attachOn}
  * policy (`'failure' | 'always' | 'never'`) for a whole run, so a debugging
@@ -59,6 +73,26 @@ function parseBrowserLogLevels(value: string | undefined): readonly string[] | u
 
 /** The `{workspace}` placeholder the file-tee expands once the workspace is known. */
 const WORKSPACE_PLACEHOLDER = '{workspace}';
+/**
+ * Name of each server's CPU profile beside `<token>.log`. Per process, since
+ * every server of a workspace writes one and a write replaces the file.
+ */
+const CPU_PROFILE_NAME = `${WORKSPACE_PLACEHOLDER}.{pid}.cpuprofile`;
+
+/** Matches the `.<pid>.cpuprofile` ending of a profile named by {@link CPU_PROFILE_NAME}. */
+const CPU_PROFILE_SUFFIX_PATTERN = /\.\d+\.cpuprofile$/;
+
+/** The `.<pid>.cpuprofile` suffixes of the profiles among `entries` written for `token`. */
+function cpuProfileSuffixes(entries: readonly string[], token: string): string[] {
+   const suffixes: string[] = [];
+   for (const entry of entries) {
+      const suffix = CPU_PROFILE_SUFFIX_PATTERN.exec(entry)?.[0];
+      if (suffix !== undefined && entry.slice(0, -suffix.length) === token) {
+         suffixes.push(suffix);
+      }
+   }
+   return suffixes.sort();
+}
 
 export interface CaptureServerLogOptions {
    /**
@@ -69,11 +103,20 @@ export interface CaptureServerLogOptions {
     */
    dir?: string;
    /**
-    * Server log level set on `HYDRANIUM_LOG_LEVEL`. When omitted, respects a
-    * pre-set `HYDRANIUM_LOG_LEVEL` env (so a run can pick the level without editing
-    * the config), then falls back to `'debug'` (a capture at `'info'` is too thin).
+    * Threshold the log file is written at, set on `HYDRANIUM_LOG_FILE_LEVEL`;
+    * the client's log-level setting does not change it. When omitted, respects a
+    * pre-set `HYDRANIUM_LOG_FILE_LEVEL`, then `HYDRANIUM_LOG_LEVEL` env (so a run
+    * can pick the level without editing the config), then falls back to `'debug'`
+    * (a capture at `'info'` is too thin).
+    *
+    * The server's own threshold is left alone: it governs what the client sees,
+    * not the file, and the setting replaces it within moments of startup.
+    *
+    * The server runs every path guarded on a level this admits, its debug
+    * profiling included, so a timing run captured at a level that admits debug
+    * measures that work too.
     */
-   level?: string;
+   level?: LogThreshold;
 }
 
 /** A Playwright `reporter` config entry: `[modulePath, options]`. */
@@ -97,7 +140,8 @@ export interface ServerLogRenameReporterOptions {
  * plus the reporter entry that renames those files to spec names once the run
  * ends. Returns an **empty env, and no reporter, when no dir is configured**, so a
  * normal run is untouched. The `{workspace}` token is expanded server-side once
- * the workspace is known.
+ * the workspace is known. With {@link DEFAULT_SERVER_CPU_PROFILE_ENV} set, the
+ * env also names a `<token>.<pid>.cpuprofile` per server beside each log.
  *
  * **Publishes a resolved `options.dir` onto {@link DEFAULT_SERVER_LOG_DIR_ENV} in
  * the CALLING process, and that mutation is load-bearing rather than a
@@ -119,7 +163,14 @@ export function captureServerLog(options: CaptureServerLogOptions = {}): Capture
    const env: Record<string, string> = {
       [DEFAULT_LOG_FILE_ENV]: join(dir, `${WORKSPACE_PLACEHOLDER}.log`)
    };
-   env[DEFAULT_LOG_LEVEL_ENV] = options.level ?? process.env[DEFAULT_LOG_LEVEL_ENV] ?? 'debug';
+   env[DEFAULT_LOG_FILE_LEVEL_ENV] =
+      options.level ??
+      parseLogLevel(process.env[DEFAULT_LOG_FILE_LEVEL_ENV]) ??
+      parseLogLevel(process.env[DEFAULT_LOG_LEVEL_ENV]) ??
+      'debug';
+   if (process.env[DEFAULT_SERVER_CPU_PROFILE_ENV]) {
+      env[DEFAULT_CPU_PROFILE_FILE_ENV] = join(dir, CPU_PROFILE_NAME);
+   }
    const reporterModule = fileURLToPath(new URL('./server-log-rename-reporter.js', import.meta.url));
    return { env, reporter: [reporterModule, { dir }] };
 }
@@ -157,16 +208,18 @@ export function serverLogSpecName(file: string): string {
 }
 
 /**
- * Rename each `<token>.log` (backend) and `<token>.browser.log` (forwarded
- * browser console) to the spec name recorded in its `<token>.spec` sidecar
- * (written by {@link markServerLog}), then delete the sidecar. Colliding names —
- * a spec that opened more than one workspace — get a `-2`, `-3`, … suffix. Run
- * once, after all server processes have exited (e.g. a reporter's `onEnd`).
- * Best-effort.
+ * Rename each `<token>.log` (backend), `<token>.browser.log` (forwarded
+ * browser console) and `<token>.<pid>.cpuprofile` (each server's CPU profile,
+ * when {@link DEFAULT_SERVER_CPU_PROFILE_ENV} is set) to the spec name recorded
+ * in its `<token>.spec` sidecar (written by {@link markServerLog}), then delete
+ * the sidecar. Colliding names — a spec that opened more than one workspace —
+ * get a `-2`, `-3`, … suffix. Run once, after all server processes have exited
+ * (e.g. a reporter's `onEnd`). Best-effort.
  *
- * Returns the workspace tokens left UNATTRIBUTED — a log the capture wrote that
- * no test claimed, because that spec never reached
- * {@link markServerLog} (no `serverLog` fixture, no `beforeEach` call).
+ * Returns the workspace tokens left UNATTRIBUTED — a log or CPU profile the
+ * capture wrote that no test claimed, because that spec never reached
+ * {@link markServerLog} (no `serverLog` fixture, no `beforeEach` call), or
+ * because its server never learned its workspace and named it `_startup-<pid>`.
  *
  * **Returned rather than ignored, because the unattributed state is the
  * misleading one.** Such a log still exists, still has content, and is named by
@@ -183,30 +236,38 @@ export function renameServerLogs(dir: string): string[] {
       // unattributed, since no log was observed at all.
       return [];
    }
-   // Per suffix (`.log`, `.browser.log`) a `taken` set guards collisions, so the
-   // backend and browser logs for one spec share the same friendly base name.
-   const taken: Record<string, Set<string>> = { '.log': new Set(), '.browser.log': new Set() };
-   const rename = (token: string, name: string, suffix: string): void => {
-      const source = join(dir, `${token}${suffix}`);
-      if (!existsSync(source)) {
-         return;
+   // One base name per token, free for every file the token has, so a spec's
+   // second workspace keeps its log, browser log and profiles paired under one
+   // `-N`. A base chosen per file pairs nothing: a profile's suffix carries its
+   // pid and never collides, so it would stay at the plain name beside a `-2` log.
+   const renameAll = (token: string, name: string): void => {
+      const suffixes = ['.log', '.browser.log', ...cpuProfileSuffixes(entries, token)].filter(suffix =>
+         existsSync(join(dir, `${token}${suffix}`))
+      );
+      let base = name;
+      for (let n = 2; suffixes.some(suffix => existsSync(join(dir, `${base}${suffix}`))); n++) {
+         base = `${name}-${n}`;
       }
-      let target = `${name}${suffix}`;
-      for (let n = 2; taken[suffix].has(target) || existsSync(join(dir, target)); n++) {
-         target = `${name}-${n}${suffix}`;
-      }
-      taken[suffix].add(target);
-      try {
-         renameSync(source, join(dir, target));
-      } catch {
-         // ignore
+      for (const suffix of suffixes) {
+         try {
+            renameSync(join(dir, `${token}${suffix}`), join(dir, `${base}${suffix}`));
+         } catch {
+            // ignore
+         }
       }
    };
-   // Every token the capture produced a backend log for, so the ones no sidecar
-   // claims can be reported rather than silently left behind.
-   const unattributed = new Set(
-      entries.filter(entry => entry.endsWith('.log') && !entry.endsWith('.browser.log')).map(entry => entry.slice(0, -'.log'.length))
-   );
+   // Every token the capture produced a backend log or a CPU profile for, so
+   // the ones no sidecar claims can be reported rather than silently left behind.
+   const unattributed = new Set<string>();
+   for (const entry of entries) {
+      if (entry.endsWith('.log') && !entry.endsWith('.browser.log')) {
+         unattributed.add(entry.slice(0, -'.log'.length));
+      }
+      const profileSuffix = CPU_PROFILE_SUFFIX_PATTERN.exec(entry)?.[0];
+      if (profileSuffix !== undefined) {
+         unattributed.add(entry.slice(0, -profileSuffix.length));
+      }
+   }
    for (const entry of entries) {
       if (!entry.endsWith('.spec')) {
          continue;
@@ -228,8 +289,7 @@ export function renameServerLogs(dir: string): string[] {
          continue;
       }
       unattributed.delete(token);
-      rename(token, name, '.log');
-      rename(token, name, '.browser.log');
+      renameAll(token, name);
    }
    return [...unattributed];
 }
@@ -396,6 +456,20 @@ export function forwardBrowserConsole(
    });
 }
 
+/** The label a `Warn` or `Error` entry starts with; continuation lines of a stack never do. */
+const WARN_OR_ERROR_LINE = /^\[(Warn|Error)\s*-/;
+
+/**
+ * The `Warn` and `Error` lines of `text` that no pattern of `allowlist`
+ * matches; its keys are the reasons the lines are expected. A clean run logs
+ * neither: `warn` is an anomaly that was handled and `error` is work that
+ * failed, so either one in a passing spec is a defect or a missing allowance.
+ */
+export function findUnexpectedServerLogLines(text: string, allowlist: Readonly<Record<string, RegExp>> = {}): string[] {
+   const patterns = Object.values(allowlist);
+   return text.split('\n').filter(line => WARN_OR_ERROR_LINE.test(line) && !patterns.some(pattern => pattern.test(line)));
+}
+
 /**
  * Per-test server-log capture, called from a spec's `afterEach` with the test's
  * workspace path:
@@ -404,8 +478,11 @@ export function forwardBrowserConsole(
  *   server log, so each test's region is delimited within the shared stream;
  * - attaches that log — and the separate browser-console log, when one exists —
  *   to the test, so it shows in the HTML report alongside the trace + screenshot.
- *   Which outcomes attach is {@link AttachServerLogOptions.attachOn}, failure-only
- *   by default.
+ *   Every CPU profile of the workspace's servers written by then is attached
+ *   too, so one of a server that ended in an earlier test of the same
+ *   workspace comes along, and one written after the test is only named after
+ *   the spec by {@link renameServerLogs}. Which outcomes attach is
+ *   {@link AttachServerLogOptions.attachOn}, failure-only by default.
  *
  * **No-op when no capture dir is configured** (`options.dir` and the default env
  * var both unset), so a normal run is untouched — no per-spec guard needed.
@@ -433,18 +510,31 @@ export async function attachServerLog(
    if (!shouldAttach) {
       return;
    }
-   // Attach both streams: the backend server log and (when present) the separate
-   // browser-console log, so a failing test carries the frontend side too.
-   const attachments: { name: string; path: string }[] = [
-      { name: 'server-log', path: file },
-      { name: 'browser-console-log', path: join(dir, `${toLogFileWorkspaceToken(workspacePath)}.browser.log`) }
+   // Attach every stream present: the backend server log, the separate
+   // browser-console log, so a failing test carries the frontend side too, and
+   // the CPU profile of each server of the workspace that has already ended.
+   const token = toLogFileWorkspaceToken(workspacePath);
+   let entries: string[] = [];
+   try {
+      entries = readdirSync(dir);
+   } catch {
+      // No profiles to attach; the logs below are checked one by one.
+   }
+   const attachments: { name: string; path: string; contentType: string }[] = [
+      { name: 'server-log', path: file, contentType: 'text/plain' },
+      { name: 'browser-console-log', path: join(dir, `${token}.browser.log`), contentType: 'text/plain' },
+      ...cpuProfileSuffixes(entries, token).map(suffix => ({
+         name: 'server-cpu-profile',
+         path: join(dir, `${token}${suffix}`),
+         contentType: 'application/json'
+      }))
    ];
    for (const attachment of attachments) {
       if (!existsSync(attachment.path)) {
          continue;
       }
       try {
-         await testInfo.attach(attachment.name, { path: attachment.path, contentType: 'text/plain' });
+         await testInfo.attach(attachment.name, { path: attachment.path, contentType: attachment.contentType });
       } catch {
          // Attaching must not break the test run.
       }

package/src/testing/playwright/server-log-fixture.ts

@@ -11,7 +11,14 @@
 // The plain functions in `server-log-capture.ts` stay playwright-free; only
 // adopters that use this fixture need `@playwright/test` installed.
 import { test as base, type Fixtures, type PlaywrightTestArgs, type PlaywrightTestOptions } from '@playwright/test';
-import { attachServerLog, markServerLog } from './server-log-capture.js';
+import {
+   attachServerLog,
+   DEFAULT_SERVER_LOG_ATTACH_ENV,
+   findUnexpectedServerLogLines,
+   markServerLog,
+   resolveServerLogPath
+} from './server-log-capture.js';
+import { readServerLogRegion } from './server-log-region.js';
 
 export interface ServerLogFixtures {
    /**
@@ -22,6 +29,21 @@ export interface ServerLogFixtures {
     * `attachServerLog` in `beforeEach` / `afterEach` instead.
     */
    serverLogWorkspace: string;
+   /**
+    * Fail a test whose part of the server log holds a `Warn` or `Error` line
+    * that {@link serverLogAllowlist} does not match. Off by default; reads
+    * nothing when capture is off.
+    */
+   serverLogClean: boolean;
+   /**
+    * The `Warn` and `Error` lines {@link serverLogClean} lets through: each key
+    * is why the line is expected, and its pattern is matched against the whole
+    * line, label and timestamp included. A pattern takes neither the `g` nor
+    * the `y` flag, which make `test` resume from its last match. An object
+    * rather than a list, because Playwright reads an array whose second entry
+    * is an object as a fixture's `[value, options]`.
+    */
+   serverLogAllowlist: Readonly<Record<string, RegExp>>;
 }
 
 /** Full fixture set including the internal side-effect-only auto fixture. */
@@ -36,17 +58,35 @@ interface ServerLogTestFixtures extends ServerLogFixtures {
  * (teardown) — i.e. the `beforeEach` + `afterEach` pair fused into one auto
  * fixture. Compose onto any test base, or use the pre-extended {@link test}.
  * Override `serverLogWorkspace` to wire the workspace; otherwise it's inert.
+ * Set `serverLogClean` to also fail a test on an unexpected `Warn` or `Error`.
  */
 export const serverLogFixtures: Fixtures<ServerLogTestFixtures, object, PlaywrightTestArgs & PlaywrightTestOptions> = {
    serverLogWorkspace: ['', { option: true }],
+   serverLogClean: [false, { option: true }],
+   serverLogAllowlist: [{}, { option: true }],
    serverLogCapture: [
-      async ({ serverLogWorkspace }, use): Promise<void> => {
-         if (serverLogWorkspace) {
-            markServerLog(base.info(), serverLogWorkspace);
+      async ({ serverLogWorkspace, serverLogClean, serverLogAllowlist }, use): Promise<void> => {
+         if (!serverLogWorkspace) {
+            await use(undefined);
+            return;
          }
+         markServerLog(base.info(), serverLogWorkspace);
          await use(undefined);
-         if (serverLogWorkspace) {
-            await attachServerLog(base.info(), serverLogWorkspace);
+         const file = resolveServerLogPath(serverLogWorkspace);
+         const region = file ? readServerLogRegion(file) : '';
+         let problem: string | undefined;
+         if (serverLogClean) {
+            const unexpected = findUnexpectedServerLogLines(region, serverLogAllowlist);
+            if (unexpected.length > 0) {
+               problem = `The server logged ${unexpected.length} unexpected Warn or Error line(s):\n${unexpected.join('\n')}`;
+            }
+         }
+         // The failure-only policy reads the test's status, which failing here
+         // does not change; a run set to attach nothing still attaches nothing.
+         const attachOn = process.env[DEFAULT_SERVER_LOG_ATTACH_ENV] === 'never' ? 'never' : 'always';
+         await attachServerLog(base.info(), serverLogWorkspace, problem ? { attachOn } : {});
+         if (problem) {
+            throw new Error(problem);
          }
       },
       { auto: true }

package/src/testing/playwright/server-log-region.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * How far each log has been read. A suite starts its app before its first
+ * test's marker, so reading from the marker would leave startup unread.
+ */
+const readUpTo = new Map<string, number>();
+
+/**
+ * The part of `file` written since the last read of it, up to its last complete
+ * line, since the server may be mid-write. Every test reads, checked or not, so
+ * a test that is not checked leaves no lines to the next one.
+ */
+export function readServerLogRegion(file: string): string {
+   if (!existsSync(file)) {
+      return '';
+   }
+   const log = readFileSync(file);
+   const end = log.lastIndexOf('\n') + 1;
+   const text = log.subarray(readUpTo.get(file) ?? 0, end).toString('utf-8');
+   readUpTo.set(file, end);
+   return text;
+}

package/src/testing/playwright/server-log-rename-reporter.ts

@@ -31,9 +31,10 @@ export default class ServerLogRenameReporter {
          // opaque workspace token and carry no test boundaries, so nothing
          // about them says which spec they belong to.
          console.warn(
-            `[server-log] ${unattributed.length} captured log(s) belong to no test: ${unattributed.join(', ')}.\n` +
-               '[server-log] Those specs never marked a boundary — apply the `serverLog` fixture, ' +
-               'or call `markServerLog`/`attachServerLog` from the suite, or their logs cannot be read per test.'
+            `[server-log] ${unattributed.length} workspace(s) left captured logs or profiles that belong to no test: ${unattributed.join(', ')}.\n` +
+               '[server-log] A workspace token means its spec never marked a boundary — apply the `serverLog` fixture, ' +
+               'or call `markServerLog`/`attachServerLog` from the suite, or its logs cannot be read per test. ' +
+               'A `_startup-<pid>` name is a server that never learned its workspace, so no spec can claim its files.'
          );
       }
    }