Files
reverse-engineering-anything/tests/support/lifecycleHarness.ts
T
morluto b4a2a79c55 test(lifecycle): move local gate copies, tests/process-global and tests/boundary phase gates onto the shared harness (#11412)
* test(lifecycle): replace eight local gate helper copies with the shared harness

* test(lifecycle): count an arrival announced in the turn its operation settles

* test(lifecycle): move tests/process-global phase gates onto the shared harness (#11414)

* test(lifecycle): move tests/process-global phase gates onto the shared harness

* test(lifecycle): move tests/boundary filesystem and process phase gates onto the shared harness (#11418)

* test(lifecycle): move tests/boundary provider phase gates onto the shared harness

* test(lifecycle): move tests/boundary/mcp phase gates onto the shared harness (#11433)

* test(lifecycle): give each phaseGate hold its own promise so unhandled held rejections stay visible

* test(lifecycle): move tests/boundary browser, pcap and CLI worker phase gates onto the shared harness (#11437)

* test(lifecycle): move tests/boundary browser, pcap and CLI worker phase gates onto the shared harness

* test(lifecycle): move fixture-owned and arrival-only provider gates onto the shared harness (#11441)

* test(lifecycle): move src/server and provider phase gates onto the shared harness (#11447)

* test(lifecycle): move the remaining src server, Kuna copy, Frida and Ghidra phase gates onto the shared harness (#11471)
2026-11-16 04:49:19 +08:00

151 lines
5.0 KiB
TypeScript

import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js";
/**
* Controls for the scenarios in
* docs/development/testing.md#lifecycle-regressions that a fixed delay cannot
* establish: a late handshake or work still in flight at close (`phaseGate`,
* or `phaseArrival` when the work waits on something other than a release),
* cancellation during final cleanup (`cancelDuringCleanup`), and mixed child
* cleanup outcomes with retry (`controlledCleanup`).
*/
/**
* A phase boundary the code under test only announces: it calls `arrive` and
* keeps going (or waits on something the test triggers, such as an abort),
* and the test waits until the boundary is `reached`.
*/
export interface PhaseArrival<T = void> {
/** Called by the code under test: records arrival with `value`. */
arrive(value: T): void;
/**
* Resolve with the arrival value once the boundary is reached. Fails if
* `operation` settles first or the test wait deadline passes.
*/
reached(operation: Promise<unknown>, boundary: string): Promise<T>;
}
export const phaseArrival = <T = void>(): PhaseArrival<T> => {
let arrive!: (value: T) => void;
const arrived = new Promise<T>((resolve) => {
arrive = resolve;
});
return {
arrive,
reached: async (operation, boundary) => {
// Pass `arrived` itself: a derived promise would settle a turn later
// and lose the race to an operation that settles right after arriving.
await awaitAcknowledgement(arrived, operation, boundary);
return arrived;
},
};
};
/**
* A phase boundary the test holds open. The code under test calls `hold` at
* the boundary and waits there; the test waits until the boundary is
* `reached`, acts (closes, cancels, lets a deadline pass), then `release`s it
* with the value `hold` returns, or `reject`s it with the failure `hold`
* throws (a late module load, a read that fails after cancellation).
*/
export interface PhaseGate<T = void, R = void> {
/** Called by the code under test: records arrival with `value`, then waits for release. */
hold(value: T): Promise<R>;
/**
* Resolve with the held value once the boundary is reached. Fails if
* `operation` settles first or the test wait deadline passes.
*/
reached(operation: Promise<unknown>, boundary: string): Promise<T>;
/**
* Let every current and later `hold` continue with `value`. Only the first
* `release` or `reject` decides the outcome; later calls are ignored.
*/
release(value: R): void;
/** Make every current and later `hold` throw `error`. */
reject(error: unknown): void;
}
export const phaseGate = <T = void, R = void>(): PhaseGate<T, R> => {
const arrival = phaseArrival<T>();
let release!: (value: R) => void;
let reject!: (error: unknown) => void;
const released = new Promise<R>((resolve, refuse) => {
release = resolve;
reject = refuse;
});
// A rejection before any `hold` is observed by that later `hold`, not here.
released.catch(() => {});
return {
// Each hold gets its own promise, so code under test that leaves a held
// rejection unhandled is still reported; the guard above covers only the
// gate's shared outcome.
hold: (value) => {
arrival.arrive(value);
return released.then((outcome) => outcome);
},
reached: arrival.reached,
release,
reject,
};
};
/**
* One child cleanup whose outcome the test controls. Each `close` counts an
* attempt, refuses with `failure` while refused, and otherwise runs its
* `release` (the real close, or a gate's `hold`). Two of them with different
* outcomes cover mixed child outcomes; `allow` then a retried close covers
* cleanup retry, and `attempts` shows a confirmed peer is not closed again.
*/
export interface ControlledCleanup {
readonly attempts: number;
/** Stop refusing: the next attempt runs its release. */
allow(): void;
close(release?: () => unknown): Promise<void>;
}
export const controlledCleanup = ({
refused = false,
failure = new Error("controlled cleanup refusal"),
}: {
readonly refused?: boolean;
readonly failure?: unknown;
} = {}): ControlledCleanup => {
let attempts = 0;
let refusing = refused;
return {
get attempts() {
return attempts;
},
allow: () => {
refusing = false;
},
close: async (release) => {
attempts++;
if (refusing) throw failure;
await release?.();
},
};
};
/**
* A final cleanup step that observes cancellation: it aborts `controller`
* with `reason` (whose identity the test asserts afterwards), then runs
* `cleanup`. A cancellation during active work does not cover this phase.
*/
export const cancelDuringCleanup =
<T>(
controller: AbortController,
reason: unknown,
cleanup?: () => T | Promise<T>,
): (() => Promise<T | undefined>) =>
async () => {
controller.abort(reason);
return cleanup?.();
};
/** The rejection of `operation`, or `undefined` once it fulfils. */
export const settledCause = (operation: Promise<unknown>): Promise<unknown> =>
operation.then(
() => undefined,
(cause: unknown) => cause,
);