@c9up/helix-plugin-ream 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+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

@@ -0,0 +1,41 @@
+# @c9up/helix-plugin-ream
+
+The bridge between [Ream](https://github.com/C9up/ream) and [helix](https://github.com/C9up/helix), its test runner.
+
+Ream knows nothing about helix, helix knows nothing about Ream. The plugin that joins them lives here and declares both sides as peers — the same shape as `@japa/plugin-adonisjs`.
+
+## Install
+
+```sh
+pnpm add -D @c9up/helix-plugin-ream @c9up/helix
+```
+
+## Inject a test client
+
+```ts
+// tests/bootstrap.ts
+import { configure } from '@c9up/helix'
+import { apiClient } from '@c9up/helix-plugin-ream'
+
+await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+```
+
+```ts
+test('health', async ({ client }) => {
+  await client.get('/health').assertOk()
+})
+```
+
+The server boots once at `configure()` time, is shared across the run, and closes through `api.cleanup` when the run ends.
+
+## Run the suites declared in the rc file
+
+```ts
+import { runTestsFromRcFile } from '@c9up/helix-plugin-ream/runner'
+```
+
+This is what `ream test` calls.
+
+## What stays in Ream
+
+`TestClient`, `createTestClient`, `RequestBuilder` and `ApiResponse` live in `@c9up/ream/testing`. They drive a Ream server over HTTP and owe nothing to the runner, so they need no plugin.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `@c9up/helix-plugin-ream` — the bridge between Ream and its test runner.
+ *
+ * Ream knows nothing about helix, helix knows nothing about Ream: the plugin
+ * that joins them lives here, and declares both sides as peers. The HTTP test
+ * client itself (`TestClient`, `createTestClient`) stays in `@c9up/ream/testing`
+ * — it drives a Ream server and owes nothing to the runner.
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from '@c9up/helix'
+ *   import { apiClient } from '@c9up/helix-plugin-ream'
+ *   await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+ *
+ *   // a test
+ *   test('health', async ({ client }) => {
+ *     await client.get('/health').assertOk()
+ *   })
+ */
+import type { PluginApi } from "@c9up/helix";
+import type { AuthStrategy, RouteManifest } from "@c9up/ream/testing";
+import { TestClient } from "@c9up/ream/testing";
+/** The slice of helix's `PluginApi` this plugin actually uses. */
+export type ClientHost = Pick<PluginApi, "context" | "cleanup">;
+export interface ApiClientConfig {
+    /** Boot the app under test on the given port; return the port + a close fn. */
+    boot: (port: number) => Promise<{
+        port: number;
+        close: () => Promise<void> | void;
+    }>;
+    /** Warden auth strategy for `client.withAuth()`/`asUser()`. */
+    auth?: AuthStrategy;
+    /** Named-route manifest (`router.namedManifest()`) for `client.visit()`. */
+    routes?: RouteManifest;
+}
+/**
+ * Injects a booted {@link TestClient} on the test context as `ctx.client`.
+ *
+ * The server is booted once at `configure()` time, shared across the run, and
+ * closed via `api.cleanup` after the run finishes — a proper lifecycle, with no
+ * reliance on process exit.
+ */
+export declare function apiClient(config: ApiClientConfig): (api: ClientHost) => Promise<void>;
+declare module "@c9up/helix" {
+    interface TestContext {
+        client: TestClient;
+    }
+}
+//# 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;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,kEAAkE;AAClE,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC/B,+EAA+E;IAC/E,IAAI,EAAE,CACL,IAAI,EAAE,MAAM,KACR,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAClE,+DAA+D;IAC/D,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,SACrB,UAAU,KAAG,OAAO,CAAC,IAAI,CAAC,CAarD;AAGD,OAAO,QAAQ,aAAa,CAAC;IAC5B,UAAU,WAAW;QACpB,MAAM,EAAE,UAAU,CAAC;KACnB;CACD"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * `@c9up/helix-plugin-ream` — the bridge between Ream and its test runner.
+ *
+ * Ream knows nothing about helix, helix knows nothing about Ream: the plugin
+ * that joins them lives here, and declares both sides as peers. The HTTP test
+ * client itself (`TestClient`, `createTestClient`) stays in `@c9up/ream/testing`
+ * — it drives a Ream server and owes nothing to the runner.
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from '@c9up/helix'
+ *   import { apiClient } from '@c9up/helix-plugin-ream'
+ *   await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+ *
+ *   // a test
+ *   test('health', async ({ client }) => {
+ *     await client.get('/health').assertOk()
+ *   })
+ */
+import { TestClient } from "@c9up/ream/testing";
+/**
+ * Injects a booted {@link TestClient} on the test context as `ctx.client`.
+ *
+ * The server is booted once at `configure()` time, shared across the run, and
+ * closed via `api.cleanup` after the run finishes — a proper lifecycle, with no
+ * reliance on process exit.
+ */
+export function apiClient(config) {
+    const plugin = async (api) => {
+        const client = new TestClient(config.boot, {
+            auth: config.auth,
+            routes: config.routes,
+        });
+        await client.boot();
+        api.context.macro("client", client);
+        api.cleanup(() => client.close());
+    };
+    // A wider parameter than `PluginApi` stays assignable to `Plugin`, so the
+    // plugin declares exactly what it touches and a caller can drive it with
+    // nothing more than that.
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAgBhD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAuB;IAChD,MAAM,MAAM,GAAG,KAAK,EAAE,GAAe,EAAiB,EAAE;QACvD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE;YAC1C,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;SACrB,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACpC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,0BAA0B;IAC1B,OAAO,MAAuB,CAAC;AAChC,CAAC"}

package/dist/runTests.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `ream test` — run the suites declared in the rc file.
+ *
+ * The AdonisJS stratification, kept intact: the FRAMEWORK reads its rc file and
+ * hands the suites to the runner, exactly as `@adonisjs/core` reads
+ * `adonisrc.ts` and hands them to Japa. The runner itself (helix) knows nothing
+ * about ream, and ream owns no test execution — it only translates.
+ *
+ *     // bin/test.ts
+ *     import { runTestsFromRcFile } from '@c9up/helix-plugin-ream/runner'
+ *     process.exitCode = await runTestsFromRcFile('./reamrc.ts', {
+ *       suites: process.argv.slice(2),
+ *     })
+ *
+ * Prefer that over `runTests(rc.tests, …)`: a `suites[].configure` callback has
+ * to be re-imported in each worker, so the runner needs the module's PATH, not
+ * just the object it exported. `runTests` takes it as `configModule`, and
+ * REFUSES to run when a suite declares a callback it was given no way to
+ * deliver — in Japa a declared `configure` runs, so a run that skipped it would
+ * be green in a state its own config does not describe.
+ */
+import type { TestsConfig } from "@c9up/ream";
+/** What a caller may override on top of the rc file. */
+export interface RunTestsOptions {
+    /** Project root the suites resolve against. Defaults to `process.cwd()`. */
+    root?: string;
+    /**
+     * Suite names to run. Empty (the default) runs every declared suite, in
+     * order — the AdonisJS behaviour for `ream test` with no argument.
+     */
+    suites?: string[];
+    /** Concurrent worker processes. */
+    threads?: number;
+    /** Reporter name, or several (`["spec", "json"]`). */
+    reporters?: string[];
+    /** Stop at the first failure. */
+    bail?: boolean;
+    /**
+     * The module that declared the suites, so a `suites[].configure` callback can
+     * be re-imported in each worker — a function does not cross a process
+     * boundary. Set for you by {@link runTestsFromRcFile}.
+     */
+    configModule?: string;
+    /**
+     * Flags the worker processes are spawned with. Defaults to this process's own
+     * (`process.execArgv`), so the workers load TypeScript through whatever
+     * loader the parent was started with — `--import @swc-node/register/esm-register`
+     * for `ream test`, tsx for a project that prefers it. Nothing to detect: the
+     * workers simply run under the same loader as their parent.
+     */
+    nodeArgs?: string[];
+}
+/** A suite name that was asked for but is not declared. */
+export declare class UnknownSuiteError extends Error {
+    constructor(name: string, declared: string[]);
+}
+/**
+ * A suite declares `configure`, but this entry point cannot deliver it.
+ *
+ * Not a warning: Japa runs a declared `configure`, so carrying on would run the
+ * suite in a state its own config does not describe — and a warning is exactly
+ * what gets scrolled past in CI.
+ */
+export declare class SuiteConfigureUnreachableError extends Error {
+    constructor(names: string[]);
+}
+/**
+ * The flags the worker processes are spawned with.
+ *
+ * Split out because it is a decision, not plumbing: the Japa alias loader
+ * redirects a package specifier, so it goes in only when a project asks. It
+ * rides ALONGSIDE whatever loader is already there — the test files still need
+ * theirs to read TypeScript.
+ */
+export declare function workerNodeArgs(tests: TestsConfig | undefined, options: RunTestsOptions): string[];
+/**
+ * Run the rc file's test suites. Returns the process exit code; the caller
+ * decides what to do with it, so this stays usable from a `bin/test.ts`, from a
+ * console command, or from a test of its own.
+ *
+ * `NODE_ENV=test` is set first, then the `.env` files are loaded — so `.env.test`
+ * wins over `.env` and `.env.local` is skipped, the AdonisJS test-env rules. It
+ * happens HERE, in the process that spawns the workers, so every worker
+ * inherits the result: an app gets its test environment without writing a
+ * single hook, which is what "loaded automatically" has to mean.
+ */
+export declare function runTests(tests: TestsConfig | undefined, options?: RunTestsOptions): Promise<number>;
+/**
+ * Load an rc file and run its suites — the one-liner a `bin/test.ts` needs.
+ * `rcPath` is resolved against `root`.
+ */
+export declare function runTestsFromRcFile(rcPath: string, options?: RunTestsOptions): Promise<number>;
+//# sourceMappingURL=runTests.d.ts.map

package/dist/runTests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTests.d.ts","sourceRoot":"","sources":["../src/runTests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAmB,WAAW,EAAE,MAAM,YAAY,CAAC;AAG/D,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC/B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,2DAA2D;AAC3D,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE;CAQ5C;AAED;;;;;;GAMG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;gBAC5C,KAAK,EAAE,MAAM,EAAE;CAU3B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,eAAe,GACtB,MAAM,EAAE,CAMV;AAkBD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC7B,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CA2GjB;AAgBD;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/runTests.js

@@ -0,0 +1,222 @@
+/**
+ * `ream test` — run the suites declared in the rc file.
+ *
+ * The AdonisJS stratification, kept intact: the FRAMEWORK reads its rc file and
+ * hands the suites to the runner, exactly as `@adonisjs/core` reads
+ * `adonisrc.ts` and hands them to Japa. The runner itself (helix) knows nothing
+ * about ream, and ream owns no test execution — it only translates.
+ *
+ *     // bin/test.ts
+ *     import { runTestsFromRcFile } from '@c9up/helix-plugin-ream/runner'
+ *     process.exitCode = await runTestsFromRcFile('./reamrc.ts', {
+ *       suites: process.argv.slice(2),
+ *     })
+ *
+ * Prefer that over `runTests(rc.tests, …)`: a `suites[].configure` callback has
+ * to be re-imported in each worker, so the runner needs the module's PATH, not
+ * just the object it exported. `runTests` takes it as `configModule`, and
+ * REFUSES to run when a suite declares a callback it was given no way to
+ * deliver — in Japa a declared `configure` runs, so a run that skipped it would
+ * be green in a state its own config does not describe.
+ */
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadEnvFiles } from "@c9up/ream/env";
+/** A suite name that was asked for but is not declared. */
+export class UnknownSuiteError extends Error {
+    constructor(name, declared) {
+        super(declared.length === 0
+            ? `Unknown test suite "${name}": the rc file declares none.`
+            : `Unknown test suite "${name}". Declared: ${declared.join(", ")}.`);
+        this.name = "UnknownSuiteError";
+    }
+}
+/**
+ * A suite declares `configure`, but this entry point cannot deliver it.
+ *
+ * Not a warning: Japa runs a declared `configure`, so carrying on would run the
+ * suite in a state its own config does not describe — and a warning is exactly
+ * what gets scrolled past in CI.
+ */
+export class SuiteConfigureUnreachableError extends Error {
+    constructor(names) {
+        const plural = names.length > 1;
+        super(`Suite${plural ? "s" : ""} ${names.map((name) => `"${name}"`).join(", ")} ` +
+            `declare${plural ? "" : "s"} \`configure\`, which has to be re-imported in each ` +
+            "worker and therefore needs the rc file PATH, not the object it exported. " +
+            "Call runTestsFromRcFile(), or pass `configModule`.");
+        this.name = "SuiteConfigureUnreachableError";
+    }
+}
+/**
+ * The flags the worker processes are spawned with.
+ *
+ * Split out because it is a decision, not plumbing: the Japa alias loader
+ * redirects a package specifier, so it goes in only when a project asks. It
+ * rides ALONGSIDE whatever loader is already there — the test files still need
+ * theirs to read TypeScript.
+ */
+export function workerNodeArgs(tests, options) {
+    const args = [...(options.nodeArgs ?? process.execArgv)];
+    if (tests?.japaPlugins === true) {
+        args.push("--import", import.meta.resolve("@c9up/helix/japa-alias"));
+    }
+    return args;
+}
+/** The suites to run, in declaration order, for the given selection. */
+function select(declared, asked) {
+    if (asked.length === 0)
+        return declared;
+    const byName = new Map(declared.map((suite) => [suite.name, suite]));
+    return asked.map((name) => {
+        const suite = byName.get(name);
+        if (suite === undefined) {
+            throw new UnknownSuiteError(name, [...byName.keys()]);
+        }
+        return suite;
+    });
+}
+/**
+ * Run the rc file's test suites. Returns the process exit code; the caller
+ * decides what to do with it, so this stays usable from a `bin/test.ts`, from a
+ * console command, or from a test of its own.
+ *
+ * `NODE_ENV=test` is set first, then the `.env` files are loaded — so `.env.test`
+ * wins over `.env` and `.env.local` is skipped, the AdonisJS test-env rules. It
+ * happens HERE, in the process that spawns the workers, so every worker
+ * inherits the result: an app gets its test environment without writing a
+ * single hook, which is what "loaded automatically" has to mean.
+ */
+export async function runTests(tests, options = {}) {
+    process.env.NODE_ENV = "test";
+    const root = options.root ?? process.cwd();
+    // Skipping `.env.local` is deliberate (and what the Ignitor does for the test
+    // environment): a developer's local overrides must not decide what CI runs.
+    loadEnvFiles(pathToFileURL(`${root}${path.sep}`), { skipEnvLocal: true });
+    const declared = tests?.suites ?? [];
+    const selected = select(declared, options.suites ?? []);
+    const helix = await import("@c9up/helix/runner");
+    // The bootstrap module is the app's, not the runner's — helix imports it in
+    // every worker, so a plugin's context extensions exist before the first test
+    // declares itself.
+    const bootstrap = helix.resolveBootstrap(root, tests?.bootstrap);
+    process.env.HELIX_BOOTSTRAP = bootstrap ?? "";
+    // Assigned either way: a second call in the same process must not inherit
+    // the first one's flag. A plugin reads it back off `api.cliArgs.forceExit`.
+    const forceExit = tests?.forceExit === true;
+    process.env.HELIX_FORCE_EXIT = forceExit ? "1" : "";
+    // Only named when a suite actually declares `configure`: pointing at it makes
+    // every worker import the rc file, which a project not using the callback
+    // should not pay for.
+    const configuring = selected.filter((suite) => typeof suite.configure === "function");
+    if (configuring.length > 0 && options.configModule === undefined) {
+        // In Japa a declared `configure` RUNS. It cannot here — the callback needs
+        // the module's path to be re-imported in each worker, and this entry was
+        // handed the exported object. Running anyway would produce a green suite
+        // configured differently from what the rc file says, so the run stops.
+        throw new SuiteConfigureUnreachableError(configuring.map((suite) => suite.name));
+    }
+    process.env.HELIX_SUITE_CONFIG =
+        configuring.length > 0 && options.configModule !== undefined
+            ? options.configModule
+            : "";
+    process.env.HELIX_SUITE_CONFIG_KEY = "tests.suites";
+    const base = {
+        root,
+        nodeArgs: workerNodeArgs(tests, options),
+        threads: options.threads,
+        timeoutMs: tests?.timeout,
+        reporters: options.reporters,
+        bail: options.bail,
+    };
+    // `runnerHooks` run ONCE around the whole run, here, and the workers skip
+    // them — Japa's semantics, and the difference between migrating once and
+    // migrating once per test file.
+    const dropGlobalHooks = await helix.runGlobalHooks(bootstrap, {
+        japaPlugins: tests?.japaPlugins === true,
+    });
+    // No suites declared: run whatever the project's discovery finds, so an app
+    // with a plain `tests/` directory works without declaring anything.
+    if (selected.length === 0) {
+        try {
+            const outcome = await helix.run(base);
+            return finish(outcome.exitCode, forceExit);
+        }
+        finally {
+            await dropGlobalHooks();
+        }
+    }
+    const steps = [];
+    for (const suite of selected) {
+        const files = await helix.resolveSuiteFiles({
+            name: suite.name,
+            files: suite.files,
+            timeout: suite.timeout,
+            retries: suite.retries,
+        }, root, undefined);
+        if (files.length === 0) {
+            process.stderr.write(`ream: suite "${suite.name}": no test files\n`);
+            continue;
+        }
+        steps.push({
+            env: {
+                HELIX_SUITE: suite.name,
+                // Empty means unset, so a suite that declares no retries does not
+                // inherit the previous suite's.
+                HELIX_RETRIES: suite.retries === undefined ? "" : String(suite.retries),
+            },
+            config: { ...base, files, timeoutMs: suite.timeout ?? tests?.timeout },
+        });
+    }
+    if (steps.length === 0) {
+        await dropGlobalHooks();
+        return finish(0, forceExit);
+    }
+    try {
+        const outcome = await helix.runSuites(steps, base);
+        return finish(outcome.exitCode, forceExit);
+    }
+    finally {
+        await dropGlobalHooks();
+    }
+}
+/**
+ * Apply `tests.forceExit`. Japa does this inside its own run — sets the exit
+ * code, then `process.exit()` — rather than leaving it to the caller, because
+ * the whole point is to not wait for the event loop to drain. A run that
+ * force-exits never returns here; the value is for every other run.
+ */
+function finish(code, forceExit) {
+    if (forceExit) {
+        process.exitCode = code;
+        process.exit();
+    }
+    return code;
+}
+/**
+ * Load an rc file and run its suites — the one-liner a `bin/test.ts` needs.
+ * `rcPath` is resolved against `root`.
+ */
+export async function runTestsFromRcFile(rcPath, options = {}) {
+    const root = options.root ?? process.cwd();
+    const absolute = path.isAbsolute(rcPath)
+        ? rcPath
+        : path.resolve(root, rcPath);
+    const imported = await import(pathToFileURL(absolute).href);
+    const rc = imported !== null && typeof imported === "object"
+        ? (Reflect.get(imported, "default") ?? imported)
+        : undefined;
+    const tests = rc !== null && typeof rc === "object"
+        ? Reflect.get(rc, "tests")
+        : undefined;
+    return runTests(isTestsConfig(tests) ? tests : undefined, {
+        ...options,
+        root,
+        configModule: absolute,
+    });
+}
+/** Narrow an rc file's `tests` value without trusting it. */
+function isTestsConfig(value) {
+    return value !== null && typeof value === "object";
+}
+//# sourceMappingURL=runTests.js.map

package/dist/runTests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTests.js","sourceRoot":"","sources":["../src/runTests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAiC9C,2DAA2D;AAC3D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3C,YAAY,IAAY,EAAE,QAAkB;QAC3C,KAAK,CACJ,QAAQ,CAAC,MAAM,KAAK,CAAC;YACpB,CAAC,CAAC,uBAAuB,IAAI,+BAA+B;YAC5D,CAAC,CAAC,uBAAuB,IAAI,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACpE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACjC,CAAC;CACD;AAED;;;;;;GAMG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACxD,YAAY,KAAe;QAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAChC,KAAK,CACJ,QAAQ,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC1E,UAAU,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,sDAAsD;YACjF,2EAA2E;YAC3E,oDAAoD,CACrD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC9C,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC7B,KAA8B,EAC9B,OAAwB;IAExB,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzD,IAAI,KAAK,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,SAAS,MAAM,CACd,QAA2B,EAC3B,KAAe;IAEf,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC7B,KAA8B,EAC9B,UAA2B,EAAE;IAE7B,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC;IAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC3C,8EAA8E;IAC9E,4EAA4E;IAC5E,YAAY,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAExD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAEjD,4EAA4E;IAC5E,6EAA6E;IAC7E,mBAAmB;IACnB,MAAM,SAAS,GAAG,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,CAAC,eAAe,GAAG,SAAS,IAAI,EAAE,CAAC;IAC9C,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,SAAS,GAAG,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpD,8EAA8E;IAC9E,0EAA0E;IAC1E,sBAAsB;IACtB,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAClC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,SAAS,KAAK,UAAU,CAChD,CAAC;IACF,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAClE,2EAA2E;QAC3E,yEAAyE;QACzE,yEAAyE;QACzE,uEAAuE;QACvE,MAAM,IAAI,8BAA8B,CACvC,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CACtC,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAC7B,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;YAC3D,CAAC,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,CAAC,GAAG,CAAC,sBAAsB,GAAG,cAAc,CAAC;IAEpD,MAAM,IAAI,GAAG;QACZ,IAAI;QACJ,QAAQ,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC;QACxC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,KAAK,EAAE,OAAO;QACzB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;KAClB,CAAC;IAEF,0EAA0E;IAC1E,yEAAyE;IACzE,gCAAgC;IAChC,MAAM,eAAe,GAAG,MAAM,KAAK,CAAC,cAAc,CAAC,SAAS,EAAE;QAC7D,WAAW,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI;KACxC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,oEAAoE;IACpE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC5C,CAAC;gBAAS,CAAC;YACV,MAAM,eAAe,EAAE,CAAC;QACzB,CAAC;IACF,CAAC;IAED,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,iBAAiB,CAC1C;YACC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;SACtB,EACD,IAAI,EACJ,SAAS,CACT,CAAC;QACF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,KAAK,CAAC,IAAI,oBAAoB,CAAC,CAAC;YACrE,SAAS;QACV,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACV,GAAG,EAAE;gBACJ,WAAW,EAAE,KAAK,CAAC,IAAI;gBACvB,kEAAkE;gBAClE,gCAAgC;gBAChC,aAAa,EAAE,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;aACvE;YACD,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,IAAI,KAAK,EAAE,OAAO,EAAE;SACtE,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,eAAe,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC5C,CAAC;YAAS,CAAC;QACV,MAAM,eAAe,EAAE,CAAC;IACzB,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,SAAkB;IAC/C,IAAI,SAAS,EAAE,CAAC;QACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QACxB,OAAO,CAAC,IAAI,EAAE,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,MAAc,EACd,UAA2B,EAAE;IAE7B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QACvC,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAY,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,EAAE,GACP,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAChD,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,QAAQ,CAAC;QAChD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,KAAK,GACV,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,KAAK,QAAQ;QACpC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC;QAC1B,CAAC,CAAC,SAAS,CAAC;IACd,OAAO,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE;QACzD,GAAG,OAAO;QACV,IAAI;QACJ,YAAY,EAAE,QAAQ;KACtB,CAAC,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,SAAS,aAAa,CAAC,KAAc;IACpC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AACpD,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@c9up/helix-plugin-ream",
+  "version": "0.1.0",
+  "description": "Helix plugin for Ream — boots a Ream app under test and injects a TestClient on the test context",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runTests.d.ts",
+      "import": "./dist/runTests.js"
+    }
+  },
+  "peerDependencies": {
+    "@c9up/helix": "^0.1.9",
+    "@c9up/ream": "^0.1.27"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@c9up/helix": "^0.1.9",
+    "@c9up/ream": "^0.1.27",
+    "@types/node": "^22.19.15",
+    "tsx": "^4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/helix-plugin-ream.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * `@c9up/helix-plugin-ream` — the bridge between Ream and its test runner.
+ *
+ * Ream knows nothing about helix, helix knows nothing about Ream: the plugin
+ * that joins them lives here, and declares both sides as peers. The HTTP test
+ * client itself (`TestClient`, `createTestClient`) stays in `@c9up/ream/testing`
+ * — it drives a Ream server and owes nothing to the runner.
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from '@c9up/helix'
+ *   import { apiClient } from '@c9up/helix-plugin-ream'
+ *   await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+ *
+ *   // a test
+ *   test('health', async ({ client }) => {
+ *     await client.get('/health').assertOk()
+ *   })
+ */
+
+import type { Plugin, PluginApi } from "@c9up/helix";
+import type { AuthStrategy, RouteManifest } from "@c9up/ream/testing";
+import { TestClient } from "@c9up/ream/testing";
+
+/** The slice of helix's `PluginApi` this plugin actually uses. */
+export type ClientHost = Pick<PluginApi, "context" | "cleanup">;
+
+export interface ApiClientConfig {
+	/** Boot the app under test on the given port; return the port + a close fn. */
+	boot: (
+		port: number,
+	) => Promise<{ port: number; close: () => Promise<void> | void }>;
+	/** Warden auth strategy for `client.withAuth()`/`asUser()`. */
+	auth?: AuthStrategy;
+	/** Named-route manifest (`router.namedManifest()`) for `client.visit()`. */
+	routes?: RouteManifest;
+}
+
+/**
+ * Injects a booted {@link TestClient} on the test context as `ctx.client`.
+ *
+ * The server is booted once at `configure()` time, shared across the run, and
+ * closed via `api.cleanup` after the run finishes — a proper lifecycle, with no
+ * reliance on process exit.
+ */
+export function apiClient(config: ApiClientConfig) {
+	const plugin = async (api: ClientHost): Promise<void> => {
+		const client = new TestClient(config.boot, {
+			auth: config.auth,
+			routes: config.routes,
+		});
+		await client.boot();
+		api.context.macro("client", client);
+		api.cleanup(() => client.close());
+	};
+	// A wider parameter than `PluginApi` stays assignable to `Plugin`, so the
+	// plugin declares exactly what it touches and a caller can drive it with
+	// nothing more than that.
+	return plugin satisfies Plugin;
+}
+
+// Typing side of the plugin — importing it augments the helix test context.
+declare module "@c9up/helix" {
+	interface TestContext {
+		client: TestClient;
+	}
+}

package/src/runTests.ts

@@ -0,0 +1,294 @@
+/**
+ * `ream test` — run the suites declared in the rc file.
+ *
+ * The AdonisJS stratification, kept intact: the FRAMEWORK reads its rc file and
+ * hands the suites to the runner, exactly as `@adonisjs/core` reads
+ * `adonisrc.ts` and hands them to Japa. The runner itself (helix) knows nothing
+ * about ream, and ream owns no test execution — it only translates.
+ *
+ *     // bin/test.ts
+ *     import { runTestsFromRcFile } from '@c9up/helix-plugin-ream/runner'
+ *     process.exitCode = await runTestsFromRcFile('./reamrc.ts', {
+ *       suites: process.argv.slice(2),
+ *     })
+ *
+ * Prefer that over `runTests(rc.tests, …)`: a `suites[].configure` callback has
+ * to be re-imported in each worker, so the runner needs the module's PATH, not
+ * just the object it exported. `runTests` takes it as `configModule`, and
+ * REFUSES to run when a suite declares a callback it was given no way to
+ * deliver — in Japa a declared `configure` runs, so a run that skipped it would
+ * be green in a state its own config does not describe.
+ */
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { TestSuiteConfig, TestsConfig } from "@c9up/ream";
+import { loadEnvFiles } from "@c9up/ream/env";
+
+/** What a caller may override on top of the rc file. */
+export interface RunTestsOptions {
+	/** Project root the suites resolve against. Defaults to `process.cwd()`. */
+	root?: string;
+	/**
+	 * Suite names to run. Empty (the default) runs every declared suite, in
+	 * order — the AdonisJS behaviour for `ream test` with no argument.
+	 */
+	suites?: string[];
+	/** Concurrent worker processes. */
+	threads?: number;
+	/** Reporter name, or several (`["spec", "json"]`). */
+	reporters?: string[];
+	/** Stop at the first failure. */
+	bail?: boolean;
+	/**
+	 * The module that declared the suites, so a `suites[].configure` callback can
+	 * be re-imported in each worker — a function does not cross a process
+	 * boundary. Set for you by {@link runTestsFromRcFile}.
+	 */
+	configModule?: string;
+	/**
+	 * Flags the worker processes are spawned with. Defaults to this process's own
+	 * (`process.execArgv`), so the workers load TypeScript through whatever
+	 * loader the parent was started with — `--import @swc-node/register/esm-register`
+	 * for `ream test`, tsx for a project that prefers it. Nothing to detect: the
+	 * workers simply run under the same loader as their parent.
+	 */
+	nodeArgs?: string[];
+}
+
+/** A suite name that was asked for but is not declared. */
+export class UnknownSuiteError extends Error {
+	constructor(name: string, declared: string[]) {
+		super(
+			declared.length === 0
+				? `Unknown test suite "${name}": the rc file declares none.`
+				: `Unknown test suite "${name}". Declared: ${declared.join(", ")}.`,
+		);
+		this.name = "UnknownSuiteError";
+	}
+}
+
+/**
+ * A suite declares `configure`, but this entry point cannot deliver it.
+ *
+ * Not a warning: Japa runs a declared `configure`, so carrying on would run the
+ * suite in a state its own config does not describe — and a warning is exactly
+ * what gets scrolled past in CI.
+ */
+export class SuiteConfigureUnreachableError extends Error {
+	constructor(names: string[]) {
+		const plural = names.length > 1;
+		super(
+			`Suite${plural ? "s" : ""} ${names.map((name) => `"${name}"`).join(", ")} ` +
+				`declare${plural ? "" : "s"} \`configure\`, which has to be re-imported in each ` +
+				"worker and therefore needs the rc file PATH, not the object it exported. " +
+				"Call runTestsFromRcFile(), or pass `configModule`.",
+		);
+		this.name = "SuiteConfigureUnreachableError";
+	}
+}
+
+/**
+ * The flags the worker processes are spawned with.
+ *
+ * Split out because it is a decision, not plumbing: the Japa alias loader
+ * redirects a package specifier, so it goes in only when a project asks. It
+ * rides ALONGSIDE whatever loader is already there — the test files still need
+ * theirs to read TypeScript.
+ */
+export function workerNodeArgs(
+	tests: TestsConfig | undefined,
+	options: RunTestsOptions,
+): string[] {
+	const args = [...(options.nodeArgs ?? process.execArgv)];
+	if (tests?.japaPlugins === true) {
+		args.push("--import", import.meta.resolve("@c9up/helix/japa-alias"));
+	}
+	return args;
+}
+
+/** The suites to run, in declaration order, for the given selection. */
+function select(
+	declared: TestSuiteConfig[],
+	asked: string[],
+): TestSuiteConfig[] {
+	if (asked.length === 0) return declared;
+	const byName = new Map(declared.map((suite) => [suite.name, suite]));
+	return asked.map((name) => {
+		const suite = byName.get(name);
+		if (suite === undefined) {
+			throw new UnknownSuiteError(name, [...byName.keys()]);
+		}
+		return suite;
+	});
+}
+
+/**
+ * Run the rc file's test suites. Returns the process exit code; the caller
+ * decides what to do with it, so this stays usable from a `bin/test.ts`, from a
+ * console command, or from a test of its own.
+ *
+ * `NODE_ENV=test` is set first, then the `.env` files are loaded — so `.env.test`
+ * wins over `.env` and `.env.local` is skipped, the AdonisJS test-env rules. It
+ * happens HERE, in the process that spawns the workers, so every worker
+ * inherits the result: an app gets its test environment without writing a
+ * single hook, which is what "loaded automatically" has to mean.
+ */
+export async function runTests(
+	tests: TestsConfig | undefined,
+	options: RunTestsOptions = {},
+): Promise<number> {
+	process.env.NODE_ENV = "test";
+
+	const root = options.root ?? process.cwd();
+	// Skipping `.env.local` is deliberate (and what the Ignitor does for the test
+	// environment): a developer's local overrides must not decide what CI runs.
+	loadEnvFiles(pathToFileURL(`${root}${path.sep}`), { skipEnvLocal: true });
+	const declared = tests?.suites ?? [];
+	const selected = select(declared, options.suites ?? []);
+
+	const helix = await import("@c9up/helix/runner");
+
+	// The bootstrap module is the app's, not the runner's — helix imports it in
+	// every worker, so a plugin's context extensions exist before the first test
+	// declares itself.
+	const bootstrap = helix.resolveBootstrap(root, tests?.bootstrap);
+	process.env.HELIX_BOOTSTRAP = bootstrap ?? "";
+	// Assigned either way: a second call in the same process must not inherit
+	// the first one's flag. A plugin reads it back off `api.cliArgs.forceExit`.
+	const forceExit = tests?.forceExit === true;
+	process.env.HELIX_FORCE_EXIT = forceExit ? "1" : "";
+
+	// Only named when a suite actually declares `configure`: pointing at it makes
+	// every worker import the rc file, which a project not using the callback
+	// should not pay for.
+	const configuring = selected.filter(
+		(suite) => typeof suite.configure === "function",
+	);
+	if (configuring.length > 0 && options.configModule === undefined) {
+		// In Japa a declared `configure` RUNS. It cannot here — the callback needs
+		// the module's path to be re-imported in each worker, and this entry was
+		// handed the exported object. Running anyway would produce a green suite
+		// configured differently from what the rc file says, so the run stops.
+		throw new SuiteConfigureUnreachableError(
+			configuring.map((suite) => suite.name),
+		);
+	}
+	process.env.HELIX_SUITE_CONFIG =
+		configuring.length > 0 && options.configModule !== undefined
+			? options.configModule
+			: "";
+	process.env.HELIX_SUITE_CONFIG_KEY = "tests.suites";
+
+	const base = {
+		root,
+		nodeArgs: workerNodeArgs(tests, options),
+		threads: options.threads,
+		timeoutMs: tests?.timeout,
+		reporters: options.reporters,
+		bail: options.bail,
+	};
+
+	// `runnerHooks` run ONCE around the whole run, here, and the workers skip
+	// them — Japa's semantics, and the difference between migrating once and
+	// migrating once per test file.
+	const dropGlobalHooks = await helix.runGlobalHooks(bootstrap, {
+		japaPlugins: tests?.japaPlugins === true,
+	});
+
+	// No suites declared: run whatever the project's discovery finds, so an app
+	// with a plain `tests/` directory works without declaring anything.
+	if (selected.length === 0) {
+		try {
+			const outcome = await helix.run(base);
+			return finish(outcome.exitCode, forceExit);
+		} finally {
+			await dropGlobalHooks();
+		}
+	}
+
+	const steps = [];
+	for (const suite of selected) {
+		const files = await helix.resolveSuiteFiles(
+			{
+				name: suite.name,
+				files: suite.files,
+				timeout: suite.timeout,
+				retries: suite.retries,
+			},
+			root,
+			undefined,
+		);
+		if (files.length === 0) {
+			process.stderr.write(`ream: suite "${suite.name}": no test files\n`);
+			continue;
+		}
+		steps.push({
+			env: {
+				HELIX_SUITE: suite.name,
+				// Empty means unset, so a suite that declares no retries does not
+				// inherit the previous suite's.
+				HELIX_RETRIES: suite.retries === undefined ? "" : String(suite.retries),
+			},
+			config: { ...base, files, timeoutMs: suite.timeout ?? tests?.timeout },
+		});
+	}
+	if (steps.length === 0) {
+		await dropGlobalHooks();
+		return finish(0, forceExit);
+	}
+
+	try {
+		const outcome = await helix.runSuites(steps, base);
+		return finish(outcome.exitCode, forceExit);
+	} finally {
+		await dropGlobalHooks();
+	}
+}
+
+/**
+ * Apply `tests.forceExit`. Japa does this inside its own run — sets the exit
+ * code, then `process.exit()` — rather than leaving it to the caller, because
+ * the whole point is to not wait for the event loop to drain. A run that
+ * force-exits never returns here; the value is for every other run.
+ */
+function finish(code: number, forceExit: boolean): number {
+	if (forceExit) {
+		process.exitCode = code;
+		process.exit();
+	}
+	return code;
+}
+
+/**
+ * Load an rc file and run its suites — the one-liner a `bin/test.ts` needs.
+ * `rcPath` is resolved against `root`.
+ */
+export async function runTestsFromRcFile(
+	rcPath: string,
+	options: RunTestsOptions = {},
+): Promise<number> {
+	const root = options.root ?? process.cwd();
+	const absolute = path.isAbsolute(rcPath)
+		? rcPath
+		: path.resolve(root, rcPath);
+	const imported: unknown = await import(pathToFileURL(absolute).href);
+	const rc =
+		imported !== null && typeof imported === "object"
+			? (Reflect.get(imported, "default") ?? imported)
+			: undefined;
+	const tests =
+		rc !== null && typeof rc === "object"
+			? Reflect.get(rc, "tests")
+			: undefined;
+	return runTests(isTestsConfig(tests) ? tests : undefined, {
+		...options,
+		root,
+		configModule: absolute,
+	});
+}
+
+/** Narrow an rc file's `tests` value without trusting it. */
+function isTestsConfig(value: unknown): value is TestsConfig {
+	return value !== null && typeof value === "object";
+}