@classytic/arc-testkit 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @classytic/arc-testkit
+
+> Boot a real [`@classytic/arc`](https://www.npmjs.com/package/@classytic/arc) app around the module(s) under test, on a real (in-memory) database.
+
+The ecosystem's contributor contract for the `@classytic/arc-*` module fleet: **if your module boots green here, it composes into any arc host.**
+
+## Install
+
+```bash
+npm i -D @classytic/arc-testkit @classytic/mongokit mongodb-memory-server
+```
+
+`@classytic/mongokit` + `mongodb-memory-server` are **optional peers** — needed only for the default backend, and dynamically imported so they never enter a production bundle. Pass your own `backend` to skip them entirely.
+
+## Usage
+
+```ts
+import { bootModuleApp } from '@classytic/arc-testkit';
+import { createAccountingModule } from '@classytic/arc-accounting';
+
+const t = await bootModuleApp(({ connection }) => [
+  createAccountingModule({ connection, permissions }),
+]);
+
+const res = await t.app.inject({ method: 'GET', url: '/accounting/accounts' });
+expect(res.statusCode).toBe(200);
+
+await t.close();
+```
+
+The module input is a factory receiving `{ connection, mongoUri }` (or a plain module / array). It boots arc with `preset: 'testing'`, `auth: false` — override via `options.app`.
+
+## Transactions
+
+Modules that open multi-document transactions need a replica set:
+
+```ts
+const t = await bootModuleApp(({ connection }) => [createReservationModule({ connection, permissions })],
+  { replset: true });
+```
+
+## Bring your own backend
+
+The default backend is `mongoMemoryBackend()` from `@classytic/mongokit/testkit`. Override it to point at a shared server, a real Atlas cluster, or a different kit's backend — anything that satisfies the `TestBackend` shape (`setup() → { ctx: { connection, uri }, teardown }`):
+
+```ts
+import { mongoMemoryBackend } from '@classytic/mongokit/testkit';
+
+const t = await bootModuleApp(mods, {
+  backend: mongoMemoryBackend({ uri: process.env.ATLAS_TEST_URI }), // real cluster
+});
+```
+
+## API
+
+| Export | |
+| --- | --- |
+| `bootModuleApp(modules, options?)` | boot arc around modules on a backend; returns `{ app, connection, mongoUri, close }` |
+| `TestBackend` | the backend seam — `setup() → { ctx: { connection, uri }, teardown }` |
+| `TestkitContext` | what a module factory receives: `{ connection, mongoUri }` |
+| `BootModuleAppOptions` | `{ replset?, app?, backend? }` |
+
+## License
+
+MIT © Classytic

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { ArcModuleInput, CreateAppOptions } from "@classytic/arc/factory";
+import { FastifyInstance } from "fastify";
+import { Connection } from "mongoose";
+
+//#region src/index.d.ts
+/** The context a backend yields — a live connection + the URI it connects to. */
+interface BackendContext {
+  connection: Connection;
+  uri: string;
+}
+/**
+ * A pluggable database backend. Structurally satisfied by
+ * `@classytic/mongokit/testkit`'s `mongoMemoryBackend()` — no import of it in
+ * the type, so arc-testkit never hard-depends on the kit (one-way: arc-testkit
+ * consumes a backend by shape).
+ */
+interface TestBackend {
+  setup(): Promise<{
+    ctx: BackendContext;
+    teardown: () => Promise<void>;
+  }>;
+}
+/** What a module factory receives — the live connection + its URI. */
+interface TestkitContext {
+  connection: Connection;
+  mongoUri: string;
+}
+type ModulesInput = ArcModuleInput | readonly ArcModuleInput[] | ((ctx: TestkitContext) => ArcModuleInput | readonly ArcModuleInput[] | Promise<ArcModuleInput | readonly ArcModuleInput[]>);
+interface BootModuleAppOptions {
+  /**
+   * Use a single-node replica set instead of a standalone mongod. Required when
+   * the module under test opens multi-document transactions. Ignored when a
+   * custom `backend` is supplied. Default false.
+   */
+  replset?: boolean;
+  /** Merged over the testkit defaults (`preset: 'testing'`, `auth: false`). */
+  app?: Partial<CreateAppOptions>;
+  /**
+   * Override the database backend. Default: `mongoMemoryBackend()` from
+   * `@classytic/mongokit/testkit`. Supply your own to point at a shared server,
+   * a real Atlas cluster, or a different kit's backend.
+   */
+  backend?: TestBackend;
+}
+interface ModuleTestApp {
+  app: FastifyInstance;
+  connection: Connection;
+  mongoUri: string;
+  /** Close app → tear the backend down (disconnect + stop server). Idempotent. */
+  close(): Promise<void>;
+}
+declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;
+//#endregion
+export { BackendContext, BootModuleAppOptions, ModuleTestApp, ModulesInput, TestBackend, TestkitContext, bootModuleApp };

package/dist/index.mjs

@@ -0,0 +1,73 @@
+import { createApp } from "@classytic/arc/factory";
+//#region src/index.ts
+/**
+* `@classytic/arc-testkit` — boot a REAL arc app around the module(s) under
+* test, on a real (in-memory) database. The ecosystem's contributor contract:
+* **if your module boots green here, it composes into any arc host.**
+*
+* ```ts
+* const t = await bootModuleApp(({ connection }) => [
+*   createAccountingModule({ connection, permissions }),
+* ]);
+* const res = await t.app.inject({ method: 'GET', url: '/accounting/accounts' });
+* await t.close();
+* ```
+*
+* This is a thin generic core: `bootModuleApp` resolves the module list, opens a
+* database via a pluggable **backend**, and boots arc around it. The default
+* backend is `mongoMemoryBackend()` from `@classytic/mongokit/testkit` — loaded
+* via dynamic `import()` so `@classytic/mongokit` + `mongodb-memory-server` stay
+* OPTIONAL peers (needed only when you use the default backend). Pass your own
+* `backend` — e.g. one pointed at a shared server, or a real Atlas cluster — to
+* override it.
+*
+* Modules usually need the live DB connection in their deps, so the primary
+* input is a FACTORY receiving `{ connection, mongoUri }`. Plain module lists
+* are also accepted.
+*/
+/** Load the default backend lazily so mongokit + memory-server stay optional. */
+async function defaultBackend(replset) {
+	try {
+		const { mongoMemoryBackend } = await import("@classytic/mongokit/testkit");
+		return mongoMemoryBackend({ replset });
+	} catch (err) {
+		throw new Error(`[arc-testkit] the default backend needs \`@classytic/mongokit\` (>=3.19.0) and \`mongodb-memory-server\` installed as devDependencies. Install them, or pass your own \`backend\` to bootModuleApp. Original error: ${err.message}`);
+	}
+}
+async function bootModuleApp(modules, options = {}) {
+	const { ctx, teardown } = await (options.backend ?? await defaultBackend(options.replset ?? false)).setup();
+	const testkitCtx = {
+		connection: ctx.connection,
+		mongoUri: ctx.uri
+	};
+	const resolved = typeof modules === "function" ? await modules(testkitCtx) : modules;
+	const list = Array.isArray(resolved) ? resolved : [resolved];
+	let app;
+	try {
+		app = await createApp({
+			preset: "testing",
+			auth: false,
+			sensible: false,
+			...options.app,
+			modules: list
+		});
+		await app.ready();
+	} catch (err) {
+		await teardown().catch(() => void 0);
+		throw err;
+	}
+	let closed = false;
+	return {
+		app,
+		connection: ctx.connection,
+		mongoUri: ctx.uri,
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await app.close().catch(() => void 0);
+			await teardown();
+		}
+	};
+}
+//#endregion
+export { bootModuleApp };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@classytic/arc-testkit",
+  "version": "0.1.0",
+  "description": "Boot a real @classytic/arc app around the module(s) under test on in-memory MongoDB — the ecosystem test harness. If your arc module boots green here, it composes into any arc host.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
+  },
+  "peerDependencies": {
+    "@classytic/arc": ">=2.20.0",
+    "@classytic/mongokit": ">=3.19.0",
+    "fastify": ">=5.0.0",
+    "mongodb-memory-server": ">=10.0.0",
+    "mongoose": ">=9.4.1"
+  },
+  "peerDependenciesMeta": {
+    "@classytic/mongokit": {
+      "optional": true
+    },
+    "mongodb-memory-server": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "arc",
+    "fastify",
+    "testing",
+    "test-harness",
+    "mongodb",
+    "in-memory",
+    "classytic"
+  ],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/arc-ecosystem.git",
+    "directory": "packages/arc-testkit"
+  }
+}