@c9up/helix-plugin-ream 0.1.2 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 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`.
+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 AdonisJS uses to join its own runner to the framework.
 
 ## Install
 

package/dist/index.d.ts

@@ -6,10 +6,25 @@
  * client itself (`TestClient`, `createTestClient`) stays in `@c9up/ream/testing`
  * — it drives a Ream server and owes nothing to the runner.
  *
+ * The split follows AdonisJS: the plugin puts a CLIENT on the test context, and
+ * the SERVER is started by a suite hook, so a suite that does not declare the
+ * hook never starts one.
+ *
  *   // tests/bootstrap.ts
  *   import { configure } from '@c9up/helix'
  *   import { apiClient } from '@c9up/helix-plugin-ream'
- *   await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+ *   import { createTestUtils } from '@c9up/ream/testing/utils'
+ *
+ *   export const testUtils = createTestUtils((port) => bootApp(port))
+ *
+ *   await configure({
+ *     plugins: [apiClient({ testUtils })],
+ *     configureSuite(suite) {
+ *       if (['functional', 'e2e'].includes(suite.name)) {
+ *         return suite.setup(() => testUtils.httpServer().start())
+ *       }
+ *     },
+ *   })
  *
  *   // a test
  *   test('health', async ({ client }) => {
@@ -19,27 +34,55 @@
 import type { PluginApi } from "@c9up/helix";
 import type { AuthStrategy, RouteManifest } from "@c9up/ream/testing";
 import { TestClient } from "@c9up/ream/testing";
+import type { BootServer, TestUtils } from "@c9up/ream/testing/utils";
 /** 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;
-    }>;
+    /**
+     * The utilities whose `httpServer()` a suite hook starts. The plugin reads
+     * the client of the server that hook started, so both point at one server.
+     */
+    testUtils?: TestUtils;
+    /**
+     * Boot the app directly, for a project that does not split its suites.
+     *
+     * A deviation from AdonisJS, where starting the server is always the suite
+     * hook's job. It exists because the server then starts on the client's FIRST
+     * REQUEST rather than at plugin time, so a file that issues none pays
+     * nothing — the same saving `testUtils` obtains by scoping, without having
+     * to split the suites first. Prefer `testUtils`; reach for this when the
+     * files are not separated.
+     */
+    boot?: BootServer;
     /** 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`.
+ * Injects a {@link TestClient} on the test context as `ctx.client`.
+ *
+ * With `testUtils`, the client is the one belonging to the server the suite
+ * hook started — so nothing is booted here, and a suite without the hook has no
+ * server at all. With `boot`, the client owns its server and starts it on the
+ * first request.
  *
- * 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.
+ * Either way `api.cleanup` closes what this plugin started, which is nothing in
+ * the `testUtils` case — the hook's own teardown owns that server.
  */
 export declare function apiClient(config: ApiClientConfig): (api: ClientHost) => Promise<void>;
+/**
+ * The client this run is using, reachable without a test context.
+ *
+ * `ctx.client` covers a test body. A helper module, a fixture, or a
+ * `runnerHooks` setup has no context to read it from and had to be handed one
+ * through a parameter every call site then had to thread. Same instance as
+ * `ctx.client` — the AdonisJS `services/test_utils` idiom.
+ *
+ * Throws when no client is in play, which is a wiring mistake rather than a
+ * state to handle.
+ */
+export declare function testClient(): TestClient;
 declare module "@c9up/helix" {
     interface TestContext {
         client: TestClient;

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEtE,kEAAkE;AAClE,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,SACrB,UAAU,KAAG,OAAO,CAAC,IAAI,CAAC,CAkDrD;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAUvC;AAGD,OAAO,QAAQ,aAAa,CAAC;IAC5B,UAAU,WAAW;QACpB,MAAM,EAAE,UAAU,CAAC;KACnB;CACD"}

package/dist/index.js

@@ -6,10 +6,25 @@
  * client itself (`TestClient`, `createTestClient`) stays in `@c9up/ream/testing`
  * — it drives a Ream server and owes nothing to the runner.
  *
+ * The split follows AdonisJS: the plugin puts a CLIENT on the test context, and
+ * the SERVER is started by a suite hook, so a suite that does not declare the
+ * hook never starts one.
+ *
  *   // tests/bootstrap.ts
  *   import { configure } from '@c9up/helix'
  *   import { apiClient } from '@c9up/helix-plugin-ream'
- *   await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+ *   import { createTestUtils } from '@c9up/ream/testing/utils'
+ *
+ *   export const testUtils = createTestUtils((port) => bootApp(port))
+ *
+ *   await configure({
+ *     plugins: [apiClient({ testUtils })],
+ *     configureSuite(suite) {
+ *       if (['functional', 'e2e'].includes(suite.name)) {
+ *         return suite.setup(() => testUtils.httpServer().start())
+ *       }
+ *     },
+ *   })
  *
  *   // a test
  *   test('health', async ({ client }) => {
@@ -18,25 +33,93 @@
  */
 import { TestClient } from "@c9up/ream/testing";
 /**
- * Injects a booted {@link TestClient} on the test context as `ctx.client`.
+ * Injects a {@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.
+ * With `testUtils`, the client is the one belonging to the server the suite
+ * hook started — so nothing is booted here, and a suite without the hook has no
+ * server at all. With `boot`, the client owns its server and starts it on the
+ * first request.
+ *
+ * Either way `api.cleanup` closes what this plugin started, which is nothing in
+ * the `testUtils` case — the hook's own teardown owns that server.
  */
 export function apiClient(config) {
     const plugin = async (api) => {
-        const client = new TestClient(config.boot, {
-            auth: config.auth,
-            routes: config.routes,
+        if (!config.testUtils && !config.boot) {
+            throw new Error("[E_NO_SERVER] apiClient() needs either `testUtils` (the AdonisJS shape: " +
+                "a suite hook starts the server) or `boot` (the client starts one on its " +
+                "first request). It was given neither, so `ctx.client` would have had " +
+                "nothing to talk to.");
+        }
+        // Resolved per access, not once: with `testUtils` the server does not
+        // exist yet when the plugin runs — the suite's setup hook starts it.
+        const owned = config.boot
+            ? new TestClient(config.boot, {
+                auth: config.auth,
+                routes: config.routes,
+            })
+            : undefined;
+        const read = () => {
+            const client = owned ?? config.testUtils?.client();
+            if (!client) {
+                throw new Error("[E_SERVER_NOT_STARTED] No server is running for this suite. Add the " +
+                    "hook that starts it:\n" +
+                    "  configureSuite(suite) {\n" +
+                    "    if (suite.name === 'functional') {\n" +
+                    "      return suite.setup(() => testUtils.httpServer().start())\n" +
+                    "    }\n" +
+                    "  }");
+            }
+            return client;
+        };
+        // The resolver, not a client: with `testUtils` there is nothing to record
+        // yet, and `testClient()` must not depend on someone having read
+        // `ctx.client` first — a fixture or a runner hook has no context to read
+        // it from, which is the reason the accessor exists.
+        setResolver(read);
+        api.context.getter("client", read);
+        api.cleanup(async () => {
+            if (owned)
+                await owned.close();
+            clearResolver(read);
         });
-        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;
 }
+let resolve;
+/** @internal Record how to reach the client in play. */
+function setResolver(read) {
+    resolve = read;
+}
+/**
+ * @internal Forget it IF it is still the one recorded — a second `configure()`
+ * in the same process must not have the first one's teardown clear its client.
+ */
+function clearResolver(read) {
+    if (resolve === read)
+        resolve = undefined;
+}
+/**
+ * The client this run is using, reachable without a test context.
+ *
+ * `ctx.client` covers a test body. A helper module, a fixture, or a
+ * `runnerHooks` setup has no context to read it from and had to be handed one
+ * through a parameter every call site then had to thread. Same instance as
+ * `ctx.client` — the AdonisJS `services/test_utils` idiom.
+ *
+ * Throws when no client is in play, which is a wiring mistake rather than a
+ * state to handle.
+ */
+export function testClient() {
+    if (!resolve) {
+        throw new Error("[E_NO_TEST_CLIENT] No client is in play. Add `apiClient()` to the plugins " +
+            "in tests/bootstrap.ts, and — with the `testUtils` shape — make sure the " +
+            "suite's setup hook has started the server. This reads the client of the " +
+            "CURRENT process.");
+    }
+    return resolve();
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AA6BhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,MAAuB;IAChD,MAAM,MAAM,GAAG,KAAK,EAAE,GAAe,EAAiB,EAAE;QACvD,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACd,0EAA0E;gBACzE,0EAA0E;gBAC1E,uEAAuE;gBACvE,qBAAqB,CACtB,CAAC;QACH,CAAC;QAED,sEAAsE;QACtE,qEAAqE;QACrE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI;YACxB,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE;gBAC5B,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,MAAM,EAAE,MAAM,CAAC,MAAM;aACrB,CAAC;YACH,CAAC,CAAC,SAAS,CAAC;QAEb,MAAM,IAAI,GAAG,GAAe,EAAE;YAC7B,MAAM,MAAM,GAAG,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACnD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACd,sEAAsE;oBACrE,wBAAwB;oBACxB,6BAA6B;oBAC7B,0CAA0C;oBAC1C,kEAAkE;oBAClE,SAAS;oBACT,KAAK,CACN,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC;QACf,CAAC,CAAC;QAEF,0EAA0E;QAC1E,iEAAiE;QACjE,yEAAyE;QACzE,oDAAoD;QACpD,WAAW,CAAC,IAAI,CAAC,CAAC;QAClB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACnC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE;YACtB,IAAI,KAAK;gBAAE,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/B,aAAa,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,0BAA0B;IAC1B,OAAO,MAAuB,CAAC;AAChC,CAAC;AAED,IAAI,OAAuC,CAAC;AAE5C,wDAAwD;AACxD,SAAS,WAAW,CAAC,IAAsB;IAC1C,OAAO,GAAG,IAAI,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,IAAsB;IAC5C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,GAAG,SAAS,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACd,4EAA4E;YAC3E,0EAA0E;YAC1E,0EAA0E;YAC1E,kBAAkB,CACnB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AAClB,CAAC"}

package/dist/runTests.d.ts

@@ -3,7 +3,7 @@
  *
  * 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
+ * `adonisrc.ts` and hands them to helix. The runner itself (helix) knows nothing
  * about ream, and ream owns no test execution — it only translates.
  *
  *     // bin/test.ts
@@ -16,7 +16,7 @@
  * 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
+ * deliver — in helix 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";
@@ -57,7 +57,7 @@ export declare class UnknownSuiteError extends Error {
 /**
  * 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
+ * Not a warning: helix 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.
  */
@@ -67,7 +67,7 @@ export declare class SuiteConfigureUnreachableError extends Error {
 /**
  * The flags the worker processes are spawned with.
  *
- * Split out because it is a decision, not plumbing: the Japa alias loader
+ * Split out because it is a decision, not plumbing: the helix 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.

package/dist/runTests.d.ts.map

@@ -1 +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,CAEV;AAkBD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC7B,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAyGjB;AAgBD;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB"}
+{"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,CAEV;AAkBD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC7B,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAyGjB;AA2BD;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/runTests.js

@@ -3,7 +3,7 @@
  *
  * 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
+ * `adonisrc.ts` and hands them to helix. The runner itself (helix) knows nothing
  * about ream, and ream owns no test execution — it only translates.
  *
  *     // bin/test.ts
@@ -16,7 +16,7 @@
  * 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
+ * deliver — in helix 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";
@@ -34,7 +34,7 @@ export class UnknownSuiteError extends Error {
 /**
  * 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
+ * Not a warning: helix 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.
  */
@@ -51,7 +51,7 @@ export class SuiteConfigureUnreachableError extends Error {
 /**
  * The flags the worker processes are spawned with.
  *
- * Split out because it is a decision, not plumbing: the Japa alias loader
+ * Split out because it is a decision, not plumbing: the helix 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.
@@ -106,7 +106,7 @@ export async function runTests(tests, options = {}) {
     // 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
+        // In helix 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.
@@ -126,7 +126,7 @@ export async function runTests(tests, options = {}) {
         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
+    // them — helix's semantics, and the difference between migrating once and
     // migrating once per test file.
     const dropGlobalHooks = await helix.runGlobalHooks(bootstrap);
     // No suites declared: run whatever the project's discovery finds, so an app
@@ -134,7 +134,7 @@ export async function runTests(tests, options = {}) {
     if (selected.length === 0) {
         try {
             const outcome = await helix.run(base);
-            return finish(outcome.exitCode, forceExit);
+            return finish(outcome.exitCode, forceExit, helix.armDrainGuard);
         }
         finally {
             await dropGlobalHooks();
@@ -164,27 +164,34 @@ export async function runTests(tests, options = {}) {
     }
     if (steps.length === 0) {
         await dropGlobalHooks();
-        return finish(0, forceExit);
+        return finish(0, forceExit, helix.armDrainGuard);
     }
     try {
         const outcome = await helix.runSuites(steps, base);
-        return finish(outcome.exitCode, forceExit);
+        return finish(outcome.exitCode, forceExit, helix.armDrainGuard);
     }
     finally {
         await dropGlobalHooks();
     }
 }
 /**
- * Apply `tests.forceExit`. Japa does this inside its own run — sets the exit
+ * Apply `tests.forceExit`. helix 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) {
+function finish(code, forceExit, armDrainGuard) {
     if (forceExit) {
         process.exitCode = code;
         process.exit();
     }
+    // Without forceExit the loop is left to drain on its own, which is the right
+    // default — a leaked handle should be visible, not swallowed. But visible has
+    // to mean SAID: `ream test` used to print its summary and then hang with no
+    // further output, and under a CI timeout that is a non-zero exit for a run in
+    // which every test passed. helix's own CLI already said so; this entry point
+    // did not, and it is the one `ream test` goes through.
+    armDrainGuard(code);
     return code;
 }
 /**

package/dist/runTests.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/helix-plugin-ream",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Helix plugin for Ream — boots a Ream app under test and injects a TestClient on the test context",
   "license": "MIT",
   "type": "module",
@@ -17,13 +17,13 @@
     }
   },
   "peerDependencies": {
-    "@c9up/helix": "^0.2.0",
-    "@c9up/ream": "^0.2.0"
+    "@c9up/helix": "^0.2.3",
+    "@c9up/ream": "^0.2.7"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@c9up/helix": "^0.2.0",
-    "@c9up/ream": "^0.2.0",
+    "@c9up/helix": "^0.2.3",
+    "@c9up/ream": "^0.2.7",
     "@types/node": "^22.19.15",
     "tsx": "^4",
     "typescript": "^6.0.2",

package/src/index.ts

@@ -6,10 +6,25 @@
  * client itself (`TestClient`, `createTestClient`) stays in `@c9up/ream/testing`
  * — it drives a Ream server and owes nothing to the runner.
  *
+ * The split follows AdonisJS: the plugin puts a CLIENT on the test context, and
+ * the SERVER is started by a suite hook, so a suite that does not declare the
+ * hook never starts one.
+ *
  *   // tests/bootstrap.ts
  *   import { configure } from '@c9up/helix'
  *   import { apiClient } from '@c9up/helix-plugin-ream'
- *   await configure({ plugins: [apiClient({ boot: () => bootApp() })] })
+ *   import { createTestUtils } from '@c9up/ream/testing/utils'
+ *
+ *   export const testUtils = createTestUtils((port) => bootApp(port))
+ *
+ *   await configure({
+ *     plugins: [apiClient({ testUtils })],
+ *     configureSuite(suite) {
+ *       if (['functional', 'e2e'].includes(suite.name)) {
+ *         return suite.setup(() => testUtils.httpServer().start())
+ *       }
+ *     },
+ *   })
  *
  *   // a test
  *   test('health', async ({ client }) => {
@@ -20,15 +35,28 @@
 import type { Plugin, PluginApi } from "@c9up/helix";
 import type { AuthStrategy, RouteManifest } from "@c9up/ream/testing";
 import { TestClient } from "@c9up/ream/testing";
+import type { BootServer, TestUtils } from "@c9up/ream/testing/utils";
 
 /** 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 }>;
+	/**
+	 * The utilities whose `httpServer()` a suite hook starts. The plugin reads
+	 * the client of the server that hook started, so both point at one server.
+	 */
+	testUtils?: TestUtils;
+	/**
+	 * Boot the app directly, for a project that does not split its suites.
+	 *
+	 * A deviation from AdonisJS, where starting the server is always the suite
+	 * hook's job. It exists because the server then starts on the client's FIRST
+	 * REQUEST rather than at plugin time, so a file that issues none pays
+	 * nothing — the same saving `testUtils` obtains by scoping, without having
+	 * to split the suites first. Prefer `testUtils`; reach for this when the
+	 * files are not separated.
+	 */
+	boot?: BootServer;
 	/** Warden auth strategy for `client.withAuth()`/`asUser()`. */
 	auth?: AuthStrategy;
 	/** Named-route manifest (`router.namedManifest()`) for `client.visit()`. */
@@ -36,21 +64,62 @@ export interface ApiClientConfig {
 }
 
 /**
- * Injects a booted {@link TestClient} on the test context as `ctx.client`.
+ * Injects a {@link TestClient} on the test context as `ctx.client`.
+ *
+ * With `testUtils`, the client is the one belonging to the server the suite
+ * hook started — so nothing is booted here, and a suite without the hook has no
+ * server at all. With `boot`, the client owns its server and starts it on the
+ * first request.
  *
- * 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.
+ * Either way `api.cleanup` closes what this plugin started, which is nothing in
+ * the `testUtils` case — the hook's own teardown owns that server.
  */
 export function apiClient(config: ApiClientConfig) {
 	const plugin = async (api: ClientHost): Promise<void> => {
-		const client = new TestClient(config.boot, {
-			auth: config.auth,
-			routes: config.routes,
+		if (!config.testUtils && !config.boot) {
+			throw new Error(
+				"[E_NO_SERVER] apiClient() needs either `testUtils` (the AdonisJS shape: " +
+					"a suite hook starts the server) or `boot` (the client starts one on its " +
+					"first request). It was given neither, so `ctx.client` would have had " +
+					"nothing to talk to.",
+			);
+		}
+
+		// Resolved per access, not once: with `testUtils` the server does not
+		// exist yet when the plugin runs — the suite's setup hook starts it.
+		const owned = config.boot
+			? new TestClient(config.boot, {
+					auth: config.auth,
+					routes: config.routes,
+				})
+			: undefined;
+
+		const read = (): TestClient => {
+			const client = owned ?? config.testUtils?.client();
+			if (!client) {
+				throw new Error(
+					"[E_SERVER_NOT_STARTED] No server is running for this suite. Add the " +
+						"hook that starts it:\n" +
+						"  configureSuite(suite) {\n" +
+						"    if (suite.name === 'functional') {\n" +
+						"      return suite.setup(() => testUtils.httpServer().start())\n" +
+						"    }\n" +
+						"  }",
+				);
+			}
+			return client;
+		};
+
+		// The resolver, not a client: with `testUtils` there is nothing to record
+		// yet, and `testClient()` must not depend on someone having read
+		// `ctx.client` first — a fixture or a runner hook has no context to read
+		// it from, which is the reason the accessor exists.
+		setResolver(read);
+		api.context.getter("client", read);
+		api.cleanup(async () => {
+			if (owned) await owned.close();
+			clearResolver(read);
 		});
-		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
@@ -58,6 +127,44 @@ export function apiClient(config: ApiClientConfig) {
 	return plugin satisfies Plugin;
 }
 
+let resolve: (() => TestClient) | undefined;
+
+/** @internal Record how to reach the client in play. */
+function setResolver(read: () => TestClient): void {
+	resolve = read;
+}
+
+/**
+ * @internal Forget it IF it is still the one recorded — a second `configure()`
+ * in the same process must not have the first one's teardown clear its client.
+ */
+function clearResolver(read: () => TestClient): void {
+	if (resolve === read) resolve = undefined;
+}
+
+/**
+ * The client this run is using, reachable without a test context.
+ *
+ * `ctx.client` covers a test body. A helper module, a fixture, or a
+ * `runnerHooks` setup has no context to read it from and had to be handed one
+ * through a parameter every call site then had to thread. Same instance as
+ * `ctx.client` — the AdonisJS `services/test_utils` idiom.
+ *
+ * Throws when no client is in play, which is a wiring mistake rather than a
+ * state to handle.
+ */
+export function testClient(): TestClient {
+	if (!resolve) {
+		throw new Error(
+			"[E_NO_TEST_CLIENT] No client is in play. Add `apiClient()` to the plugins " +
+				"in tests/bootstrap.ts, and — with the `testUtils` shape — make sure the " +
+				"suite's setup hook has started the server. This reads the client of the " +
+				"CURRENT process.",
+		);
+	}
+	return resolve();
+}
+
 // Typing side of the plugin — importing it augments the helix test context.
 declare module "@c9up/helix" {
 	interface TestContext {

package/src/runTests.ts

@@ -3,7 +3,7 @@
  *
  * 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
+ * `adonisrc.ts` and hands them to helix. The runner itself (helix) knows nothing
  * about ream, and ream owns no test execution — it only translates.
  *
  *     // bin/test.ts
@@ -16,7 +16,7 @@
  * 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
+ * deliver — in helix a declared `configure` runs, so a run that skipped it would
  * be green in a state its own config does not describe.
  */
 
@@ -71,7 +71,7 @@ export class UnknownSuiteError extends Error {
 /**
  * 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
+ * Not a warning: helix 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.
  */
@@ -91,7 +91,7 @@ export class SuiteConfigureUnreachableError extends Error {
 /**
  * The flags the worker processes are spawned with.
  *
- * Split out because it is a decision, not plumbing: the Japa alias loader
+ * Split out because it is a decision, not plumbing: the helix 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.
@@ -162,7 +162,7 @@ export async function runTests(
 		(suite) => typeof suite.configure === "function",
 	);
 	if (configuring.length > 0 && options.configModule === undefined) {
-		// In Japa a declared `configure` RUNS. It cannot here — the callback needs
+		// In helix 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.
@@ -186,7 +186,7 @@ export async function runTests(
 	};
 
 	// `runnerHooks` run ONCE around the whole run, here, and the workers skip
-	// them — Japa's semantics, and the difference between migrating once and
+	// them — helix's semantics, and the difference between migrating once and
 	// migrating once per test file.
 	const dropGlobalHooks = await helix.runGlobalHooks(bootstrap);
 
@@ -195,7 +195,7 @@ export async function runTests(
 	if (selected.length === 0) {
 		try {
 			const outcome = await helix.run(base);
-			return finish(outcome.exitCode, forceExit);
+			return finish(outcome.exitCode, forceExit, helix.armDrainGuard);
 		} finally {
 			await dropGlobalHooks();
 		}
@@ -229,28 +229,39 @@ export async function runTests(
 	}
 	if (steps.length === 0) {
 		await dropGlobalHooks();
-		return finish(0, forceExit);
+		return finish(0, forceExit, helix.armDrainGuard);
 	}
 
 	try {
 		const outcome = await helix.runSuites(steps, base);
-		return finish(outcome.exitCode, forceExit);
+		return finish(outcome.exitCode, forceExit, helix.armDrainGuard);
 	} finally {
 		await dropGlobalHooks();
 	}
 }
 
 /**
- * Apply `tests.forceExit`. Japa does this inside its own run — sets the exit
+ * Apply `tests.forceExit`. helix 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 {
+function finish(
+	code: number,
+	forceExit: boolean,
+	armDrainGuard: (code: number) => void,
+): number {
 	if (forceExit) {
 		process.exitCode = code;
 		process.exit();
 	}
+	// Without forceExit the loop is left to drain on its own, which is the right
+	// default — a leaked handle should be visible, not swallowed. But visible has
+	// to mean SAID: `ream test` used to print its summary and then hang with no
+	// further output, and under a CI timeout that is a non-zero exit for a run in
+	// which every test passed. helix's own CLI already said so; this entry point
+	// did not, and it is the one `ream test` goes through.
+	armDrainGuard(code);
 	return code;
 }