@xenosisorg/testing 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { AwilixContainer } from 'awilix';
+import { PeerApi, PeerClient, SchemaPackage, AutoloadOptions } from '@xenosisorg/xenosis-core';
+
+/**
+ * Apply a schema package's Prisma migrations onto a fresh in-memory engine by
+ * replaying the raw `migration.sql` files in order. Prisma's migrations are
+ * plain Postgres DDL, which PGlite executes natively — no Prisma CLI, no schema
+ * engine, no running server.
+ *
+ * `migrationsPath` is the package's `schema.migrationsPath` (the `prisma/
+ * migrations` dir). Each timestamped subfolder holds one `migration.sql`;
+ * lexical sort on the folder name is chronological by Prisma convention.
+ *
+ * `exec` runs one SQL string against the engine (e.g. `pglite.exec`).
+ */
+declare function replayPrismaMigrations(migrationsPath: string, exec: (sql: string) => Promise<unknown>): Promise<number>;
+
+/**
+ * Resolve the effective test config for a service.
+ *
+ * Base is the service's real `xenosis.config.json` (single source of structure:
+ * which schemas, peers, boundaries it has). Over it we layer
+ * `__tests__/test.config.json` — a DELTA holding only what a test needs to
+ * change (e.g. disable auth, point a schema at a test connector). Both files are
+ * optional; the test delta wins on conflicts.
+ *
+ * The delta may name a different base via `extends` (relative to the test file).
+ */
+declare function resolveTestConfig(serviceRoot: string): Promise<Record<string, any>>;
+
+/**
+ * Build a type-safe client for an API spec, routed at the in-process app.
+ * Returned by `ctx.client(apiSpec)`.
+ */
+declare function createInProcessClient<TApi extends Record<string, (...args: any[]) => Promise<any>>>(app: unknown, api: PeerApi<TApi>): PeerClient<TApi>;
+
+/** A schema binding for the test container: the package + its cradle key. */
+interface TestSchema {
+    /** Cradle key the service injects (e.g. `mainDb`). */
+    cradleKey: string;
+    /** The schema package module (default export or `{ createTestClient, schema }`). */
+    pkg: SchemaPackage;
+    /** Connector this binding would use in prod — only `type` matters for test dispatch. */
+    connector?: {
+        type: string;
+    } & Record<string, unknown>;
+}
+interface CreateTestContainerOptions {
+    /**
+     * Auto mode. Point at a service directory and the kit does the rest:
+     *   - reads `xenosis.config.json` layered with `__tests__/test.config.json`
+     *   - boots an in-memory engine for each `config.schemas` binding, importing
+     *     the package by its npm name and replaying its migrations
+     *   - autoloads repositories/services/controllers by the standard convention
+     * Override any piece with the explicit options below.
+     */
+    serviceRoot?: string;
+    /**
+     * The service config object. In `serviceRoot` mode this is the resolved
+     * config and is usually omitted; pass it to fully override. The schemas block
+     * drives in-memory engine setup.
+     */
+    config?: Record<string, unknown>;
+    /** Schema packages to back with an in-memory engine (explicit mode). */
+    schemas?: TestSchema[];
+    /**
+     * Peer mocks. Each key becomes both `cradle.<name>` and `cradle.api.<name>`,
+     * so a service can inject either `this.api.billing` or `billing` directly.
+     */
+    peers?: Record<string, Record<string, (...args: any[]) => unknown>>;
+    /**
+     * Autoload globs. Defaults (serviceRoot mode) to the standard convention
+     * rooted at serviceRoot: repository/*.repository, services/*.service,
+     * api/**\/*.controller.
+     */
+    autoload?: AutoloadOptions;
+    /** Extra cradle registrations (asValue) applied before autoload. */
+    register?: Record<string, unknown>;
+    /**
+     * Seed callback run after schema clients are ready and before the proof
+     * query. Receives the cradle so you can write rows via `cradle.<schemaKey>`.
+     */
+    seed?: (cradle: any) => Promise<void> | void;
+}
+interface TestContainer {
+    container: AwilixContainer;
+    /** The awilix cradle — read clients/services off it. */
+    cradle: any;
+    /** The live Express app — pass to supertest(app) without listening. */
+    server: any;
+    /**
+     * Build a type-safe client for an API contract, routed at the in-process app.
+     * Calls go through the same Proxy + zod + path-param machinery production
+     * callers use — but hit `server` directly, no port. Use it to exercise a
+     * service through its own `defineServiceApi` contract:
+     *
+     *   const billing = ctx.client(billingApi);
+     *   const charge = await billing.createCharge({ userId, amount, currency });
+     */
+    client: <TApi extends Record<string, (...args: any[]) => Promise<any>>>(api: PeerApi<TApi>) => PeerClient<TApi>;
+    /** Tear down in-memory engines and clients. Call in afterAll/afterEach. */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Boot a Xenosis service in-process for tests: real schema on an in-memory
+ * Postgres (PGlite), real controllers, peer calls replaced by mocks. No Docker,
+ * no network, no migrations CLI — the kit replays the package's migration SQL
+ * onto a fresh PGlite, then the package wraps it in its own Prisma client via
+ * `createTestClient`.
+ *
+ * This intentionally re-implements the xenosisBootstrap sequence (rather than
+ * calling it) so it can swap the schema layer for in-memory engines — bootstrap
+ * always builds the real connector clients.
+ */
+declare function createTestContainer(options?: CreateTestContainerOptions): Promise<TestContainer>;
+
+export { type CreateTestContainerOptions, type TestContainer, type TestSchema, createInProcessClient, createTestContainer, replayPrismaMigrations, resolveTestConfig };

package/dist/index.js

@@ -0,0 +1,224 @@
+// src/index.ts
+import { createContainer, asValue, asFunction } from "awilix";
+import {
+  loggerProvider,
+  serverProvider,
+  loadSharedModules,
+  runAutoload,
+  loadServiceApis,
+  mountOpenapi,
+  buildRequestContextMiddleware,
+  errorHandlerMiddleware
+} from "@xenosisorg/xenosis-core";
+import { join as join3 } from "path";
+
+// src/migrate.ts
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+async function replayPrismaMigrations(migrationsPath, exec) {
+  let entries;
+  try {
+    entries = (await readdir(migrationsPath, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+  } catch {
+    return 0;
+  }
+  let applied = 0;
+  for (const dir of entries) {
+    const sqlPath = join(migrationsPath, dir, "migration.sql");
+    let sql;
+    try {
+      sql = await readFile(sqlPath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (sql.trim()) {
+      await exec(sql);
+      applied++;
+    }
+  }
+  return applied;
+}
+
+// src/config.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2, isAbsolute, resolve } from "path";
+async function resolveTestConfig(serviceRoot) {
+  const base = await readJson(join2(serviceRoot, "xenosis.config.json"));
+  const testCfgPath = join2(serviceRoot, "__tests__", "test.config.json");
+  const delta = await readJson(testCfgPath);
+  let resolvedBase = base;
+  if (delta.extends) {
+    const extendsPath = isAbsolute(delta.extends) ? delta.extends : resolve(serviceRoot, "__tests__", delta.extends);
+    resolvedBase = await readJson(extendsPath);
+  }
+  const { extends: _drop, ...deltaRest } = delta;
+  return mergeConfig(resolvedBase, deltaRest);
+}
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile2(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function mergeConfig(base, delta) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(delta)) {
+    if (v && typeof v === "object" && !Array.isArray(v) && base[k] && typeof base[k] === "object" && !Array.isArray(base[k])) {
+      out[k] = { ...base[k], ...v };
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+// src/inProcessClient.ts
+import {
+  createPeerClient,
+  buildReliabilityPolicy
+} from "@xenosisorg/xenosis-core";
+import request from "supertest";
+function inProcessTransport(app) {
+  return {
+    async execute(req) {
+      const agent = request(app);
+      const method = req.method.toLowerCase();
+      let r = agent[method](req.url);
+      for (const [k, v] of Object.entries(req.headers ?? {})) r = r.set(k, String(v));
+      if (req.body !== void 0 && req.method !== "GET") r = r.send(req.body);
+      const res = await r;
+      if (res.status >= 400) {
+        const err = new Error(
+          `in-process ${req.method} ${req.url} \u2192 HTTP ${res.status}`
+        );
+        err.status = res.status;
+        err.body = res.body;
+        throw err;
+      }
+      return res.body;
+    }
+  };
+}
+function createInProcessClient(app, api) {
+  return createPeerClient({
+    api,
+    transport: inProcessTransport(app),
+    policy: buildReliabilityPolicy({})
+  });
+}
+
+// src/index.ts
+async function createTestContainer(options = {}) {
+  const cleanups = [];
+  let config = options.config ?? {};
+  let schemas = options.schemas ?? [];
+  let autoload = options.autoload;
+  if (options.serviceRoot) {
+    const root = options.serviceRoot;
+    if (!options.config) config = await resolveTestConfig(root);
+    if (!options.schemas) {
+      const cfgSchemas = config.schemas ?? {};
+      const cfgConnectors = config.connectors ?? {};
+      const derived = [];
+      for (const [cradleKey, binding] of Object.entries(cfgSchemas)) {
+        const mod = await import(binding.package);
+        const pkg = typeof mod.createClient === "function" ? mod : mod.default;
+        const connector = cfgConnectors[binding.connector] ?? { type: pkg.schema.type };
+        derived.push({ cradleKey, pkg, connector });
+      }
+      schemas = derived;
+    }
+    if (!options.autoload) {
+      autoload = {
+        repositories: { pattern: join3(root, "src/repository/*.repository.{ts,js}"), lifetime: "singleton" },
+        services: { pattern: join3(root, "src/services/*.service.{ts,js}"), lifetime: "singleton" },
+        controllers: { pattern: join3(root, "src/api/**/*.controller.{ts,js}"), style: "build" }
+      };
+    }
+  }
+  const container = createContainer();
+  container.register({
+    config: asValue(config),
+    logger: asFunction(loggerProvider).singleton(),
+    context: asValue({}),
+    errorHandlerMiddleware: asValue(errorHandlerMiddleware),
+    server: asFunction(serverProvider).singleton(),
+    // Disconnect arrays the loaders/commands expect to exist.
+    schemaDisconnects: asValue([]),
+    peerDisconnects: asValue([])
+  });
+  const logger = container.cradle.logger;
+  for (const s of schemas) {
+    const type = s.connector?.type ?? s.pkg.schema.type;
+    if (type === "postgres" || type === "prisma") {
+      if (typeof s.pkg.createTestClient !== "function") {
+        throw new Error(
+          `[testing] schema "${s.cradleKey}": package has no createTestClient \u2014 add it to support in-memory tests (see @xenosisorg/testing docs)`
+        );
+      }
+      const { PGlite } = await import("@electric-sql/pglite");
+      const pglite = new PGlite();
+      await pglite.waitReady;
+      if (s.pkg.schema.migrationsPath) {
+        await replayPrismaMigrations(
+          s.pkg.schema.migrationsPath,
+          (sql) => pglite.exec(sql)
+        );
+      }
+      const client = await s.pkg.createTestClient(pglite, s.connector ?? { type });
+      container.register({ [s.cradleKey]: asValue(client) });
+      cleanups.push(async () => {
+        if (typeof s.pkg.disconnect === "function") await s.pkg.disconnect(client);
+        await pglite.close();
+      });
+    } else {
+      throw new Error(
+        `[testing] schema "${s.cradleKey}": in-memory engine for type "${type}" is not implemented yet (prototype supports postgres/prisma)`
+      );
+    }
+  }
+  const api = {};
+  for (const [name, impl] of Object.entries(options.peers ?? {})) {
+    container.register({ [name]: asValue(impl) });
+    api[name] = impl;
+  }
+  await loadServiceApis(container, { ...config, peers: void 0 }, logger).catch(() => {
+  });
+  container.register({ api: asValue(api) });
+  for (const [k, v] of Object.entries(options.register ?? {})) {
+    container.register({ [k]: asValue(v) });
+  }
+  await loadSharedModules(container, logger).catch(() => {
+  });
+  const server = container.cradle.server;
+  server.use(buildRequestContextMiddleware(container, logger, config));
+  if (autoload) {
+    await runAutoload(container, autoload, logger);
+  }
+  if (config.openapi?.enabled !== false) {
+    try {
+      mountOpenapi(server, { ...config.openapi, name: config.name });
+    } catch {
+    }
+  }
+  server.use(errorHandlerMiddleware);
+  if (options.seed) {
+    await options.seed(container.cradle);
+  }
+  return {
+    container,
+    cradle: container.cradle,
+    server,
+    client: (api2) => createInProcessClient(server, api2),
+    cleanup: async () => {
+      for (const c of cleanups.reverse()) await c();
+    }
+  };
+}
+export {
+  createInProcessClient,
+  createTestContainer,
+  replayPrismaMigrations,
+  resolveTestConfig
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@xenosisorg/testing",
+  "version": "0.0.1",
+  "description": "In-memory test harness for Xenosis services — real schema, real SQL, no Docker.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aVujovic/xenosis.git",
+    "directory": "packages/testing-kit"
+  },
+  "homepage": "https://xenosis.org",
+  "bugs": {
+    "url": "https://github.com/aVujovic/xenosis/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "awilix": "^12.0.5",
+    "supertest": "^7.0.0"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": "^0.2.0",
+    "@xenosisorg/xenosis-core": ">=0.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.2.0",
+    "@example/psql-main": "workspace:*",
+    "@types/node": "^20.11.19",
+    "@types/supertest": "^6.0.2",
+    "@xenosisorg/xenosis-core": "workspace:*",
+    "pglite-prisma-adapter": "^0.6.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist"
+  ]
+}