@quiesco/jest 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quiesco contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @quiesco/jest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Quiesco for Jest: a preset whose test environment runs one session for the run, resets the app before
+every test and gives tests the global `quiesco`.
+
+```sh
+npm i -D @quiesco/jest @quiesco/core jest
+```
+
+```js
+// jest.config.js
+module.exports = { preset: '@quiesco/jest', maxWorkers: 1, testTimeout: 120_000 };
+
+// e2e/todo.test.js
+test('a new todo appears at the top @ios', async () => {
+  await quiesco.app.tap('add-todo');
+});
+```
+
+Platform tags go in test or `describe` titles. Run with `npx quiesco test --platform ios --runner jest`.
+Details: [using Quiesco without Cucumber](https://shift-14cc7601.mintlify.site/api#using-quiesco-without-cucumber).
+
+Part of [Quiesco](https://github.com/h2nology/quiesco): gray-box end-to-end testing for Expo apps on iOS, Android and the web. Setup: `npx quiesco init` ([quick start](https://github.com/h2nology/quiesco#quick-start-web-about-10-minutes)).
+
+## License
+
+MIT

package/dist/environment.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Jest test environment (`testEnvironment: '@quiesco/jest/environment'`, set by the preset): Node's
+ * environment plus the run's Quiesco session, exposed to tests as the global `quiesco`
+ * (`quiesco.app`, `quiesco.session`).
+ */
+import type { EnvironmentContext, JestEnvironmentConfig } from '@jest/environment';
+import { TestEnvironment } from 'jest-environment-node';
+import type { EventLike } from './events.js';
+export default class QuiescoEnvironment extends TestEnvironment {
+    private readonly worker;
+    private lifecycle;
+    constructor(config: JestEnvironmentConfig, context: EnvironmentContext);
+    setup(): Promise<void>;
+    handleTestEvent(event: EventLike): Promise<void>;
+}
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAEnF,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAKxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,eAAe;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,SAAS,CAA0B;gBAE/B,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,kBAAkB;IAKvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe/B,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAMvD"}

package/dist/environment.js

@@ -0,0 +1,34 @@
+import { TestEnvironment } from 'jest-environment-node';
+import { handleEvent, jestWorker } from './events.js';
+import { inWorkerProcess, registerChildren, startShared } from './shared.js';
+export default class QuiescoEnvironment extends TestEnvironment {
+    worker;
+    lifecycle = null;
+    constructor(config, context) {
+        super(config, context);
+        this.worker = jestWorker(config.globalConfig.maxWorkers, process.env, inWorkerProcess());
+    }
+    async setup() {
+        await super.setup();
+        const lifecycle = await startShared(this.worker);
+        this.lifecycle = lifecycle;
+        this.global['quiesco'] = {
+            get app() {
+                return lifecycle.current.driver;
+            },
+            get session() {
+                return lifecycle.current;
+            },
+        };
+    }
+    // Structural event type: jest-circus passes its own Event; only `name` and `test` are read.
+    async handleTestEvent(event) {
+        if (this.lifecycle === null)
+            return;
+        await handleEvent(this.lifecycle, event);
+        // Children started during the test (the iOS system UI runner, a recorder) join the registry.
+        if (event.name === 'test_done' && inWorkerProcess())
+            registerChildren();
+    }
+}
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIxD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7E,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,eAAe;IAC5C,MAAM,CAAa;IAC5B,SAAS,GAAqB,IAAI,CAAC;IAE3C,YAAY,MAA6B,EAAE,OAA2B;QACpE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC,CAAC;IAC3F,CAAC;IAEQ,KAAK,CAAC,KAAK;QAClB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG;YACvB,IAAI,GAAG;gBACL,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;YAClC,CAAC;YACD,IAAI,OAAO;gBACT,OAAO,SAAS,CAAC,OAAO,CAAC;YAC3B,CAAC;SACF,CAAC;IACJ,CAAC;IAED,4FAA4F;IAC5F,KAAK,CAAC,eAAe,CAAC,KAAgB;QACpC,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO;QACpC,MAAM,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACzC,6FAA6F;QAC7F,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,eAAe,EAAE;YAAE,gBAAgB,EAAE,CAAC;IAC1E,CAAC;CACF"}

package/dist/events.d.ts

@@ -0,0 +1,29 @@
+import type { Lifecycle } from '@quiesco/core';
+export interface BlockLike {
+    name: string;
+    parent?: BlockLike | undefined;
+}
+export interface TestLike extends BlockLike {
+    mode?: string | undefined;
+    errors: unknown[];
+}
+export interface EventLike {
+    name: string;
+    test?: TestLike;
+}
+/** Title tags by level, outermost describe first. */
+export declare function tagLevelsOf(test: TestLike): string[][];
+/** "describe > test": the name of the test's artifacts directory. */
+export declare function fullName(test: TestLike): string;
+/** Adds where the evidence is to a failed test's first error (Jest prints the message from `stack`). */
+export declare function addEvidence(test: TestLike, files: readonly string[]): void;
+export declare function handleEvent(lifecycle: Lifecycle, event: EventLike): Promise<void>;
+/**
+ * The worker this process is (Phase 6.12): Jest numbers its worker processes JEST_WORKER_ID = 1…maxWorkers.
+ * In-band runs (also chosen by Jest itself for fast suites, findings 6.12) are worker 0.
+ */
+export declare function jestWorker(maxWorkers: number | undefined, env: NodeJS.ProcessEnv, inWorkerProcess: boolean): {
+    index: number;
+    count: number;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAUD,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,EAAE,CAEtD;AAED,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAI/C;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAO1E;AAED,wBAAsB,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAK7I"}

package/dist/events.js

@@ -0,0 +1,81 @@
+/**
+ * The Jest side of the lifecycle (Phase 6.10, findings 6.10 batch B), on jest-circus events — structural
+ * types only, so it can be unit-tested without Jest:
+ *
+ * - `test_start` (dispatched before Jest decides to skip): a test tagged for another platform gets
+ *   `mode = 'skip'`.
+ * - `test_started` (before the beforeEach hooks): reset the app.
+ * - `test_done` (after the afterEach hooks): end the test; on failure the evidence files are added to the
+ *   first error's message. An app error reported after a passed test fails it.
+ */
+import { titleTags } from '@quiesco/core';
+const ROOT = 'ROOT_DESCRIBE_BLOCK';
+function chain(test) {
+    const out = [];
+    for (let n = test; n !== undefined; n = n.parent)
+        if (n.name !== ROOT)
+            out.unshift(n);
+    return out;
+}
+/** Title tags by level, outermost describe first. */
+export function tagLevelsOf(test) {
+    return chain(test).map((n) => titleTags(n.name));
+}
+/** "describe > test": the name of the test's artifacts directory. */
+export function fullName(test) {
+    return chain(test)
+        .map((n) => n.name)
+        .join(' > ');
+}
+/** Adds where the evidence is to a failed test's first error (Jest prints the message from `stack`). */
+export function addEvidence(test, files) {
+    const first = test.errors[0];
+    const err = (Array.isArray(first) ? first[0] : first);
+    if (err === undefined || err === null || typeof err !== 'object' || files.length === 0)
+        return;
+    const note = `\n\nQuiesco evidence:\n${files.map((f) => `  ${f}`).join('\n')}`;
+    if (typeof err.message === 'string')
+        err.message += note;
+    if (typeof err.stack === 'string')
+        err.stack = err.stack.replace(/\n|$/, `${note}\n`);
+}
+export async function handleEvent(lifecycle, event) {
+    const test = event.test;
+    if (test === undefined || !lifecycle.running)
+        return;
+    if (event.name === 'test_start') {
+        if (!lifecycle.runsHere(tagLevelsOf(test)))
+            test.mode = 'skip';
+    }
+    else if (event.name === 'test_started') {
+        try {
+            await lifecycle.before(tagLevelsOf(test), fullName(test));
+        }
+        catch (e) {
+            test.errors.push(e);
+        }
+    }
+    else if (event.name === 'test_done') {
+        const failed = test.errors.length > 0;
+        try {
+            const { files } = await lifecycle.after({ tags: tagLevelsOf(test).flat(), failed });
+            if (failed)
+                addEvidence(test, files);
+        }
+        catch (e) {
+            test.errors.push(e);
+        }
+    }
+}
+/**
+ * The worker this process is (Phase 6.12): Jest numbers its worker processes JEST_WORKER_ID = 1…maxWorkers.
+ * In-band runs (also chosen by Jest itself for fast suites, findings 6.12) are worker 0.
+ */
+export function jestWorker(maxWorkers, env, inWorkerProcess) {
+    const count = maxWorkers !== undefined && maxWorkers > 1 ? maxWorkers : 1;
+    const id = Number.parseInt(env['JEST_WORKER_ID'] ?? '', 10);
+    if (!inWorkerProcess || count === 1 || !(id >= 1))
+        return { index: 0, count };
+    return { index: Math.min(id, count) - 1, count };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @quiesco/jest (Phase 6.10): Quiesco for Jest.
+ *
+ *   // jest.config.js
+ *   module.exports = { preset: '@quiesco/jest', maxWorkers: 2, testTimeout: 60_000 };
+ *
+ *   // e2e/todo.test.js — `quiesco` is a global, like Jest's own `test` / `expect`
+ *   test('a new todo appears at the top @ios', async () => {
+ *     await quiesco.app.tap('add-todo');
+ *   });
+ *
+ * One session (device + app) per worker process (one device each; `maxWorkers: 1` runs serially), a
+ * reset before every test, a test tagged for another
+ * platform (in its or a describe's title; the innermost wins) is skipped, and a failure's message names
+ * the evidence files. TypeScript: add `"types": ["@quiesco/jest"]` for the `quiesco` global.
+ */
+import type { Driver, Session } from '@quiesco/core';
+export interface QuiescoGlobal {
+    readonly app: Driver;
+    readonly session: Session;
+}
+declare global {
+    var quiesco: QuiescoGlobal;
+}
+export { addEvidence, fullName, handleEvent, jestWorker, tagLevelsOf } from './events.js';
+export { registryDir, sweepRegistry } from './shared.js';
+export type { BlockLike, EventLike, TestLike } from './events.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,OAAO,EAAE,aAAa,CAAC;CAC5B;AAED,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { addEvidence, fullName, handleEvent, jestWorker, tagLevelsOf } from './events.js';
+export { registryDir, sweepRegistry } from './shared.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,22 @@
+import { Lifecycle } from '@quiesco/core';
+import type { WorkerInfo } from '@quiesco/core';
+/** Where workers of the Jest run with main process `mainPid` register their child processes. */
+export declare function registryDir(mainPid: number, tmp?: string): string;
+/** Whether this is a Jest worker process (forked with IPC), not the main process running in band. */
+export declare function inWorkerProcess(): boolean;
+/**
+ * jest-worker's "end" message to a worker process (CHILD_MESSAGE_END, jest-worker 29 and 30). On it the
+ * worker only stops listening and waits for its event loop to drain, which an open session never lets
+ * happen: about 0.5 s later Jest sends SIGTERM and reports "A worker process has failed to exit
+ * gracefully" (findings 6.12).
+ */
+export declare const JEST_CHILD_MESSAGE_END = 2;
+/** Write this worker's live child pids where globalTeardown finds them. */
+export declare function registerChildren(dir?: string): void;
+/** Starts the session once; a start that failed fails every later test file at once (no new attempt). */
+export declare function startShared(worker: WorkerInfo): Promise<Lifecycle>;
+/** globalTeardown: close an in-band session, then kill what the workers' registries still list. */
+export declare function disposeShared(dir?: string): Promise<number>;
+/** Kill registered child pids that are still alive; returns how many were. Removes the registry. */
+export declare function sweepRegistry(dir: string, kill?: (pid: number, signal?: NodeJS.Signals | 0) => void): number;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAA4C,MAAM,eAAe,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKhD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAc,GAAG,MAAM,CAEtE;AAED,qGAAqG;AACrG,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAID;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AA4BxC,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,SAA4B,GAAG,IAAI,CAOtE;AAED,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAWlE;AAED,mGAAmG;AACnG,wBAAsB,aAAa,CAAC,GAAG,SAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnF;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,IAAiC,GAAG,MAAM,CA0BxI"}

package/dist/shared.js

@@ -0,0 +1,123 @@
+/**
+ * The process's one Lifecycle. The test environment module is loaded once per process (outside the test
+ * files' sandboxes), so this module state outlives each test file (findings 6.10 batch B).
+ *
+ * Parallel runs (Phase 6.12, findings 6.12 batch A): with maxWorkers > 1 every Jest worker process has its
+ * own session (its own device). Jest ends a worker with SIGTERM and kills it about 0.5 s later, so the
+ * session's async dispose never finishes there: the worker kills the session's child processes
+ * synchronously instead, and writes their pids to a registry file that globalTeardown (in the main
+ * process) sweeps as a backstop. In-band runs close the session from globalTeardown as before.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Lifecycle, killChildProcessesSync, trackedChildPids } from '@quiesco/core';
+let lifecycle = null;
+let starting = null;
+/** Where workers of the Jest run with main process `mainPid` register their child processes. */
+export function registryDir(mainPid, tmp = os.tmpdir()) {
+    return path.join(tmp, `quiesco-jest-${mainPid}`);
+}
+/** Whether this is a Jest worker process (forked with IPC), not the main process running in band. */
+export function inWorkerProcess() {
+    return typeof process.send === 'function' && process.env['JEST_WORKER_ID'] !== undefined;
+}
+let exitHooked = false;
+/**
+ * jest-worker's "end" message to a worker process (CHILD_MESSAGE_END, jest-worker 29 and 30). On it the
+ * worker only stops listening and waits for its event loop to drain, which an open session never lets
+ * happen: about 0.5 s later Jest sends SIGTERM and reports "A worker process has failed to exit
+ * gracefully" (findings 6.12).
+ */
+export const JEST_CHILD_MESSAGE_END = 2;
+/** How long a worker's session may take to close before the worker exits anyway (Jest kills at ~0.5 s). */
+const END_BUDGET_MS = 400;
+/** In a worker process: close the session when Jest ends the worker, and never leave its children behind. */
+function hookWorkerExit() {
+    if (exitHooked)
+        return;
+    exitHooked = true;
+    process.on('message', (m) => {
+        if (Array.isArray(m) && m[0] === JEST_CHILD_MESSAGE_END)
+            void endWorker();
+    });
+    process.once('SIGTERM', () => {
+        killChildProcessesSync();
+        process.exit(0);
+    });
+    process.once('exit', () => killChildProcessesSync());
+}
+/** Close the session within the budget, then end the children left and the process. */
+async function endWorker() {
+    const l = lifecycle;
+    lifecycle = null;
+    await Promise.race([l?.afterAll().catch(() => undefined), new Promise((r) => setTimeout(r, END_BUDGET_MS).unref())]);
+    killChildProcessesSync();
+    process.exit(0);
+}
+/** Write this worker's live child pids where globalTeardown finds them. */
+export function registerChildren(dir = registryDir(process.ppid)) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, `${process.pid}.json`), JSON.stringify(trackedChildPids()));
+    }
+    catch {
+        // best effort: the synchronous kill on SIGTERM is the main mechanism
+    }
+}
+/** Starts the session once; a start that failed fails every later test file at once (no new attempt). */
+export function startShared(worker) {
+    starting ??= (async () => {
+        const worked = inWorkerProcess();
+        if (worked)
+            hookWorkerExit();
+        const l = new Lifecycle({ worker });
+        await l.beforeAll();
+        lifecycle = l;
+        if (worked)
+            registerChildren();
+        return l;
+    })();
+    return starting;
+}
+/** globalTeardown: close an in-band session, then kill what the workers' registries still list. */
+export async function disposeShared(dir = registryDir(process.pid)) {
+    const l = lifecycle;
+    lifecycle = null;
+    starting = null;
+    await l?.afterAll();
+    return sweepRegistry(dir);
+}
+/** Kill registered child pids that are still alive; returns how many were. Removes the registry. */
+export function sweepRegistry(dir, kill = process.kill.bind(process)) {
+    const read = (f, fallback) => {
+        try {
+            return f();
+        }
+        catch {
+            return fallback;
+        }
+    };
+    const files = read(() => fs.readdirSync(dir).filter((f) => f.endsWith('.json')), null);
+    if (files === null)
+        return 0;
+    let n = 0;
+    for (const f of files) {
+        const pids = read(() => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')), []);
+        for (const pid of Array.isArray(pids) ? pids : []) {
+            if (typeof pid !== 'number')
+                continue;
+            try {
+                kill(pid, 0);
+                kill(pid, 'SIGKILL');
+                n++;
+            }
+            catch {
+                // already gone
+            }
+        }
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+    return n;
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"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"}

package/dist/teardown.d.ts

@@ -0,0 +1,2 @@
+export default function teardown(): Promise<void>;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.d.ts","sourceRoot":"","sources":["../src/teardown.ts"],"names":[],"mappings":"AAMA,wBAA8B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtD"}

package/dist/teardown.js

@@ -0,0 +1,9 @@
+/**
+ * Jest globalTeardown (set by the preset): closes an in-band run's session (device per config), and kills
+ * what parallel workers' sessions left running (Phase 6.12).
+ */
+import { disposeShared } from './shared.js';
+export default async function teardown() {
+    await disposeShared();
+}
+//# sourceMappingURL=teardown.js.map

package/dist/teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.js","sourceRoot":"","sources":["../src/teardown.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,QAAQ;IACpC,MAAM,aAAa,EAAE,CAAC;AACxB,CAAC"}

package/jest-preset.cjs

@@ -0,0 +1,7 @@
+// `preset: '@quiesco/jest'`: the Quiesco test environment and the teardown that closes the session.
+// Set `maxWorkers` (1 = serial; N = N devices in parallel) and a `testTimeout` in your own config (Jest
+// presets cannot set them).
+module.exports = {
+  testEnvironment: require.resolve('./dist/environment.js'),
+  globalTeardown: require.resolve('./dist/teardown.js'),
+};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@quiesco/jest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Quiesco for Jest: a preset whose test environment runs one session for the run and gives tests `quiesco.app`",
+  "license": "MIT",
+  "author": "h2nology",
+  "keywords": [
+    "quiesco",
+    "e2e",
+    "testing",
+    "expo",
+    "react-native",
+    "jest"
+  ],
+  "homepage": "https://github.com/h2nology/quiesco/tree/main/packages/jest#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h2nology/quiesco.git",
+    "directory": "packages/jest"
+  },
+  "bugs": {
+    "url": "https://github.com/h2nology/quiesco/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./environment": {
+      "types": "./dist/environment.d.ts",
+      "import": "./dist/environment.js"
+    },
+    "./teardown": {
+      "types": "./dist/teardown.d.ts",
+      "import": "./dist/teardown.js"
+    },
+    "./jest-preset": "./jest-preset.cjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "jest-preset.cjs"
+  ],
+  "dependencies": {
+    "@quiesco/core": "0.1.1",
+    "jest-environment-node": "30.5.2"
+  },
+  "devDependencies": {
+    "@jest/environment": "30.5.2",
+    "@jest/types": "30.5.1"
+  },
+  "peerDependencies": {
+    "jest": ">=30"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
 }

package/src/environment.ts

@@ -0,0 +1,46 @@
+/**
+ * Jest test environment (`testEnvironment: '@quiesco/jest/environment'`, set by the preset): Node's
+ * environment plus the run's Quiesco session, exposed to tests as the global `quiesco`
+ * (`quiesco.app`, `quiesco.session`).
+ */
+import type { EnvironmentContext, JestEnvironmentConfig } from '@jest/environment';
+import type { Lifecycle } from '@quiesco/core';
+import { TestEnvironment } from 'jest-environment-node';
+
+import type { WorkerInfo } from '@quiesco/core';
+
+import { handleEvent, jestWorker } from './events.js';
+import type { EventLike } from './events.js';
+import { inWorkerProcess, registerChildren, startShared } from './shared.js';
+
+export default class QuiescoEnvironment extends TestEnvironment {
+  private readonly worker: WorkerInfo;
+  private lifecycle: Lifecycle | null = null;
+
+  constructor(config: JestEnvironmentConfig, context: EnvironmentContext) {
+    super(config, context);
+    this.worker = jestWorker(config.globalConfig.maxWorkers, process.env, inWorkerProcess());
+  }
+
+  override async setup(): Promise<void> {
+    await super.setup();
+    const lifecycle = await startShared(this.worker);
+    this.lifecycle = lifecycle;
+    this.global['quiesco'] = {
+      get app() {
+        return lifecycle.current.driver;
+      },
+      get session() {
+        return lifecycle.current;
+      },
+    };
+  }
+
+  // Structural event type: jest-circus passes its own Event; only `name` and `test` are read.
+  async handleTestEvent(event: EventLike): Promise<void> {
+    if (this.lifecycle === null) return;
+    await handleEvent(this.lifecycle, event);
+    // Children started during the test (the iOS system UI runner, a recorder) join the registry.
+    if (event.name === 'test_done' && inWorkerProcess()) registerChildren();
+  }
+}

package/src/events.ts

@@ -0,0 +1,90 @@
+/**
+ * The Jest side of the lifecycle (Phase 6.10, findings 6.10 batch B), on jest-circus events — structural
+ * types only, so it can be unit-tested without Jest:
+ *
+ * - `test_start` (dispatched before Jest decides to skip): a test tagged for another platform gets
+ *   `mode = 'skip'`.
+ * - `test_started` (before the beforeEach hooks): reset the app.
+ * - `test_done` (after the afterEach hooks): end the test; on failure the evidence files are added to the
+ *   first error's message. An app error reported after a passed test fails it.
+ */
+import { titleTags } from '@quiesco/core';
+import type { Lifecycle } from '@quiesco/core';
+
+export interface BlockLike {
+  name: string;
+  parent?: BlockLike | undefined;
+}
+
+export interface TestLike extends BlockLike {
+  mode?: string | undefined;
+  errors: unknown[];
+}
+
+export interface EventLike {
+  name: string;
+  test?: TestLike;
+}
+
+const ROOT = 'ROOT_DESCRIBE_BLOCK';
+
+function chain(test: TestLike): BlockLike[] {
+  const out: BlockLike[] = [];
+  for (let n: BlockLike | undefined = test; n !== undefined; n = n.parent) if (n.name !== ROOT) out.unshift(n);
+  return out;
+}
+
+/** Title tags by level, outermost describe first. */
+export function tagLevelsOf(test: TestLike): string[][] {
+  return chain(test).map((n) => titleTags(n.name));
+}
+
+/** "describe > test": the name of the test's artifacts directory. */
+export function fullName(test: TestLike): string {
+  return chain(test)
+    .map((n) => n.name)
+    .join(' > ');
+}
+
+/** Adds where the evidence is to a failed test's first error (Jest prints the message from `stack`). */
+export function addEvidence(test: TestLike, files: readonly string[]): void {
+  const first = test.errors[0];
+  const err = (Array.isArray(first) ? first[0] : first) as { message?: unknown; stack?: unknown } | undefined;
+  if (err === undefined || err === null || typeof err !== 'object' || files.length === 0) return;
+  const note = `\n\nQuiesco evidence:\n${files.map((f) => `  ${f}`).join('\n')}`;
+  if (typeof err.message === 'string') err.message += note;
+  if (typeof err.stack === 'string') err.stack = err.stack.replace(/\n|$/, `${note}\n`);
+}
+
+export async function handleEvent(lifecycle: Lifecycle, event: EventLike): Promise<void> {
+  const test = event.test;
+  if (test === undefined || !lifecycle.running) return;
+  if (event.name === 'test_start') {
+    if (!lifecycle.runsHere(tagLevelsOf(test))) test.mode = 'skip';
+  } else if (event.name === 'test_started') {
+    try {
+      await lifecycle.before(tagLevelsOf(test), fullName(test));
+    } catch (e) {
+      test.errors.push(e);
+    }
+  } else if (event.name === 'test_done') {
+    const failed = test.errors.length > 0;
+    try {
+      const { files } = await lifecycle.after({ tags: tagLevelsOf(test).flat(), failed });
+      if (failed) addEvidence(test, files);
+    } catch (e) {
+      test.errors.push(e);
+    }
+  }
+}
+
+/**
+ * The worker this process is (Phase 6.12): Jest numbers its worker processes JEST_WORKER_ID = 1…maxWorkers.
+ * In-band runs (also chosen by Jest itself for fast suites, findings 6.12) are worker 0.
+ */
+export function jestWorker(maxWorkers: number | undefined, env: NodeJS.ProcessEnv, inWorkerProcess: boolean): { index: number; count: number } {
+  const count = maxWorkers !== undefined && maxWorkers > 1 ? maxWorkers : 1;
+  const id = Number.parseInt(env['JEST_WORKER_ID'] ?? '', 10);
+  if (!inWorkerProcess || count === 1 || !(id >= 1)) return { index: 0, count };
+  return { index: Math.min(id, count) - 1, count };
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @quiesco/jest (Phase 6.10): Quiesco for Jest.
+ *
+ *   // jest.config.js
+ *   module.exports = { preset: '@quiesco/jest', maxWorkers: 2, testTimeout: 60_000 };
+ *
+ *   // e2e/todo.test.js — `quiesco` is a global, like Jest's own `test` / `expect`
+ *   test('a new todo appears at the top @ios', async () => {
+ *     await quiesco.app.tap('add-todo');
+ *   });
+ *
+ * One session (device + app) per worker process (one device each; `maxWorkers: 1` runs serially), a
+ * reset before every test, a test tagged for another
+ * platform (in its or a describe's title; the innermost wins) is skipped, and a failure's message names
+ * the evidence files. TypeScript: add `"types": ["@quiesco/jest"]` for the `quiesco` global.
+ */
+import type { Driver, Session } from '@quiesco/core';
+
+export interface QuiescoGlobal {
+  readonly app: Driver;
+  readonly session: Session;
+}
+
+declare global {
+  var quiesco: QuiescoGlobal;
+}
+
+export { addEvidence, fullName, handleEvent, jestWorker, tagLevelsOf } from './events.js';
+export { registryDir, sweepRegistry } from './shared.js';
+export type { BlockLike, EventLike, TestLike } from './events.js';

package/src/shared.ts

@@ -0,0 +1,127 @@
+/**
+ * The process's one Lifecycle. The test environment module is loaded once per process (outside the test
+ * files' sandboxes), so this module state outlives each test file (findings 6.10 batch B).
+ *
+ * Parallel runs (Phase 6.12, findings 6.12 batch A): with maxWorkers > 1 every Jest worker process has its
+ * own session (its own device). Jest ends a worker with SIGTERM and kills it about 0.5 s later, so the
+ * session's async dispose never finishes there: the worker kills the session's child processes
+ * synchronously instead, and writes their pids to a registry file that globalTeardown (in the main
+ * process) sweeps as a backstop. In-band runs close the session from globalTeardown as before.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { Lifecycle, killChildProcessesSync, trackedChildPids } from '@quiesco/core';
+import type { WorkerInfo } from '@quiesco/core';
+
+let lifecycle: Lifecycle | null = null;
+let starting: Promise<Lifecycle> | null = null;
+
+/** Where workers of the Jest run with main process `mainPid` register their child processes. */
+export function registryDir(mainPid: number, tmp = os.tmpdir()): string {
+  return path.join(tmp, `quiesco-jest-${mainPid}`);
+}
+
+/** Whether this is a Jest worker process (forked with IPC), not the main process running in band. */
+export function inWorkerProcess(): boolean {
+  return typeof process.send === 'function' && process.env['JEST_WORKER_ID'] !== undefined;
+}
+
+let exitHooked = false;
+
+/**
+ * jest-worker's "end" message to a worker process (CHILD_MESSAGE_END, jest-worker 29 and 30). On it the
+ * worker only stops listening and waits for its event loop to drain, which an open session never lets
+ * happen: about 0.5 s later Jest sends SIGTERM and reports "A worker process has failed to exit
+ * gracefully" (findings 6.12).
+ */
+export const JEST_CHILD_MESSAGE_END = 2;
+
+/** How long a worker's session may take to close before the worker exits anyway (Jest kills at ~0.5 s). */
+const END_BUDGET_MS = 400;
+
+/** In a worker process: close the session when Jest ends the worker, and never leave its children behind. */
+function hookWorkerExit(): void {
+  if (exitHooked) return;
+  exitHooked = true;
+  process.on('message', (m: unknown) => {
+    if (Array.isArray(m) && m[0] === JEST_CHILD_MESSAGE_END) void endWorker();
+  });
+  process.once('SIGTERM', () => {
+    killChildProcessesSync();
+    process.exit(0);
+  });
+  process.once('exit', () => killChildProcessesSync());
+}
+
+/** Close the session within the budget, then end the children left and the process. */
+async function endWorker(): Promise<void> {
+  const l = lifecycle;
+  lifecycle = null;
+  await Promise.race([l?.afterAll().catch(() => undefined), new Promise((r) => setTimeout(r, END_BUDGET_MS).unref())]);
+  killChildProcessesSync();
+  process.exit(0);
+}
+
+/** Write this worker's live child pids where globalTeardown finds them. */
+export function registerChildren(dir = registryDir(process.ppid)): void {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, `${process.pid}.json`), JSON.stringify(trackedChildPids()));
+  } catch {
+    // best effort: the synchronous kill on SIGTERM is the main mechanism
+  }
+}
+
+/** Starts the session once; a start that failed fails every later test file at once (no new attempt). */
+export function startShared(worker: WorkerInfo): Promise<Lifecycle> {
+  starting ??= (async () => {
+    const worked = inWorkerProcess();
+    if (worked) hookWorkerExit();
+    const l = new Lifecycle({ worker });
+    await l.beforeAll();
+    lifecycle = l;
+    if (worked) registerChildren();
+    return l;
+  })();
+  return starting;
+}
+
+/** globalTeardown: close an in-band session, then kill what the workers' registries still list. */
+export async function disposeShared(dir = registryDir(process.pid)): Promise<number> {
+  const l = lifecycle;
+  lifecycle = null;
+  starting = null;
+  await l?.afterAll();
+  return sweepRegistry(dir);
+}
+
+/** Kill registered child pids that are still alive; returns how many were. Removes the registry. */
+export function sweepRegistry(dir: string, kill: (pid: number, signal?: NodeJS.Signals | 0) => void = process.kill.bind(process)): number {
+  const read = <T>(f: () => T, fallback: T): T => {
+    try {
+      return f();
+    } catch {
+      return fallback;
+    }
+  };
+  const files = read(() => fs.readdirSync(dir).filter((f) => f.endsWith('.json')), null);
+  if (files === null) return 0;
+  let n = 0;
+  for (const f of files) {
+    const pids: unknown = read(() => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')) as unknown, []);
+    for (const pid of Array.isArray(pids) ? pids : []) {
+      if (typeof pid !== 'number') continue;
+      try {
+        kill(pid, 0);
+        kill(pid, 'SIGKILL');
+        n++;
+      } catch {
+        // already gone
+      }
+    }
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+  return n;
+}

package/src/teardown.ts

@@ -0,0 +1,9 @@
+/**
+ * Jest globalTeardown (set by the preset): closes an in-band run's session (device per config), and kills
+ * what parallel workers' sessions left running (Phase 6.12).
+ */
+import { disposeShared } from './shared.js';
+
+export default async function teardown(): Promise<void> {
+  await disposeShared();
+}