@geonosis/testbed 1.0.0

package/dist/medusa-built/index.js

@@ -0,0 +1,91 @@
+import {
+  createDatabaseNamer,
+  fixturesOnly
+} from "../chunk-UZPJWPL3.js";
+
+// src/medusa-built/index.ts
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { resolve } from "path";
+var DEFAULT_BUILT_DIR = ".medusa/server";
+var DEFAULT_CONNECTION_ENV = ["DB_HOST", "DB_PORT", "DB_USERNAME"];
+var sha1Twelve = (description) => createHash("sha1").update(description).digest("hex").slice(0, 12);
+var createMedusaIntegrationTest = (options) => {
+  const builtDir = options.builtDir ?? DEFAULT_BUILT_DIR;
+  const connectionEnv = options.connectionEnv ?? DEFAULT_CONNECTION_ENV;
+  const nodeEnv = options.nodeEnv ?? "test";
+  const requireBuilt = options.requireBuilt ?? true;
+  const waitForMs = options.waitForMs ?? 3e4;
+  const cwd = resolve(options.root, builtDir);
+  const databaseNameFor = createDatabaseNamer(options.databaseName ?? sha1Twelve);
+  const refuseIfNotReady = () => {
+    if (nodeEnv !== false && process.env.NODE_ENV !== nodeEnv) {
+      throw new Error(
+        `NODE_ENV must be "${nodeEnv}" before Medusa loads; it is "${process.env.NODE_ENV ?? "(unset)"}". It selects the in-memory cache, event bus and workflow engine, and it is read while the app loads, so setting it afterwards is too late.`
+      );
+    }
+    if (requireBuilt && !existsSync(cwd)) {
+      throw new Error(
+        `the built server is not at ${cwd} \u2014 build the app before the integration suite. Unbuilt, the run dies inside a Medusa loader after the database has already been created.`
+      );
+    }
+    const unset = connectionEnv.filter((name) => (process.env[name] ?? "") === "");
+    if (unset.length > 0) {
+      throw new Error(
+        `${unset.join(", ")} ${unset.length === 1 ? "is" : "are"} unset, and Medusa has a default for each \u2014 so the suite would not fail, it would quietly connect to whatever is on the default host and port, which on a shared machine is another project's database.`
+      );
+    }
+  };
+  return {
+    adapterFor: (suite) => medusaBuiltAdapter(suite, waitForMs),
+    ...options.fixtures === void 0 ? {} : { fixture: fixturesOnly(options.fixtures) },
+    runIntegrationTest: (description, testSuite) => {
+      refuseIfNotReady();
+      const moduleName = databaseNameFor(description);
+      options.describe(description, () => {
+        options.runner({ cwd, env: options.env, moduleName, testSuite });
+      });
+    }
+  };
+};
+var medusaBuiltAdapter = (suite, waitForMs = 3e4) => {
+  let snapshotted = false;
+  return {
+    boot: async () => ({ db: suite, teardown: async () => {
+    } }),
+    id: "medusa-built",
+    restore: async () => {
+      if (!snapshotted) {
+        throw new Error(
+          "restore() before any snapshot() would return whichever template the runner last wrote, which on a reused database name is the previous suite. Take a snapshot first."
+        );
+      }
+      await suite.dbUtils.restore();
+    },
+    snapshot: async () => {
+      await suite.dbUtils.snapshot();
+      snapshotted = true;
+    },
+    waitKinds: ["workflows"],
+    waitFor: async (kind, predicate) => {
+      if (kind !== "workflows") {
+        throw new Error(
+          `the medusa-built adapter waits for "workflows"; it was asked for "${kind}"`
+        );
+      }
+      const deadline = Date.now() + waitForMs;
+      for (; ; ) {
+        await suite.utils.waitWorkflowExecutions();
+        if (await predicate()) return;
+        if (Date.now() >= deadline) {
+          throw new Error(`workflows did not settle the predicate within ${waitForMs}ms`);
+        }
+        await new Promise((done) => setTimeout(done, 25));
+      }
+    }
+  };
+};
+export {
+  createMedusaIntegrationTest,
+  medusaBuiltAdapter
+};

package/dist/types-D-uHas5h.d.ts

@@ -0,0 +1,68 @@
+/** Where a test may read and write, and nowhere else. during.day's §4.3, as a value. */
+type NetworkPolicy = 'none' | {
+    allow: readonly string[];
+};
+/** How long one database lives. dielime is `suite`; during.day is `run`. */
+type DatabaseLifetime = 'file' | 'run' | 'suite';
+type DatabaseSpec = {
+    /** The consumer's derivation. dielime's is `sha1(description).slice(0, 12)`. */
+    name: (key: string) => string;
+    per: DatabaseLifetime;
+};
+/** Everything an adapter is told, and the only thing it is told. Frozen before it is handed over. */
+type BootContext = {
+    readonly databaseName: string;
+    readonly fixtures: string;
+    readonly network: NetworkPolicy;
+};
+type BootResult<Db> = {
+    db: Db;
+    /** Called on the way out AND on a signal, so it has to be idempotent. */
+    teardown: () => Promise<void>;
+};
+/**
+ * The seam a testbed sits behind. `boot` is required; the rest are what a particular engine can
+ * do — Medusa can snapshot to a template database, workerd's cell cannot and truncates instead.
+ * Declaring one of `snapshot`/`restore` without the other is refused at define time.
+ */
+type TestbedAdapter<Db> = {
+    boot: (ctx: BootContext) => Promise<BootResult<Db>>;
+    id: string;
+    restore?: () => Promise<void>;
+    snapshot?: () => Promise<void>;
+    waitFor?: (kind: string, predicate: () => boolean | Promise<boolean>) => Promise<void>;
+    /**
+     * What this adapter can wait for — `['workflows']` for Medusa. Required alongside `waitFor` and
+     * refused without it: a wait whose kinds nobody knows is a wait nobody can call, and the
+     * conformance suite inventing one of its own is how that went unnoticed.
+     */
+    waitKinds?: readonly string[];
+};
+type TestbedConfig<Db> = {
+    adapter: TestbedAdapter<Db>;
+    database: DatabaseSpec;
+    fixtures: string;
+    network: NetworkPolicy;
+};
+type Testbed<Db> = {
+    adapterId: string;
+    allowsHost: (host: string) => boolean;
+    boot: (key: string) => Promise<BootResult<Db>>;
+    databaseNameFor: (key: string) => string;
+    fixture: (...segments: string[]) => string;
+    per: DatabaseLifetime;
+};
+type ConformanceCheck = {
+    detail: string;
+    name: string;
+    ok: boolean;
+};
+type ConformanceReport = {
+    adapterId: string;
+    checks: ConformanceCheck[];
+    passed: boolean;
+    /** Named, because a check that did not run is not a check that passed. */
+    skipped: string[];
+};
+
+export type { BootContext as B, ConformanceReport as C, DatabaseLifetime as D, NetworkPolicy as N, TestbedAdapter as T, TestbedConfig as a, Testbed as b, BootResult as c, ConformanceCheck as d, DatabaseSpec as e };

package/dist/workerd/index.d.ts

@@ -0,0 +1,117 @@
+import { T as TestbedAdapter } from '../types-D-uHas5h.js';
+
+type ClusterLike = {
+    initialise: () => Promise<void>;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+};
+type Cell = {
+    /** The role the code under test runs as — production's, not the migrator's. */
+    appConnectionString: string;
+    connectionString: string;
+    /** Owned clusters only: a database somebody else started is not this suite's to stop. */
+    stop: () => Promise<void>;
+};
+type CellServerOptions = {
+    /** `embedded-postgres` or another cluster, injected — never imported, so it stays a peer. */
+    cluster: (options: {
+        databaseDir: string;
+        port: number;
+    }) => ClusterLike;
+    connectionStringEnv?: string;
+    connectionStringOf?: (port: number) => string;
+    port?: number;
+    /** Migrate as the owner and grant the app role; returns the app's connection string. */
+    prepare: (connectionString: string) => Promise<string>;
+};
+/**
+ * One real Postgres for the whole run, migrated from zero.
+ *
+ * `CELL_CONNECTION_STRING` — or whatever a repo calls it — takes an externally-owned cell instead,
+ * which is how the same suite runs against the versions a deployment might actually use. That one
+ * is prepared and never stopped: in CI the container is thrown away; against a managed instance,
+ * stopping it is not the suite's to do.
+ */
+declare const createCellServer: (options: CellServerOptions) => Promise<Cell>;
+/**
+ * One statement, one round trip. A DELETE per table inside a transaction cost twenty-eight of them
+ * before every test in the repo this comes from.
+ */
+declare const truncateAllStatement: (tables: readonly string[]) => string;
+type WorkerdAdapterOptions = {
+    /** Statements to run before each reset — a trigger a test planted outlives the rows it refused. */
+    before?: readonly string[];
+    cell: Cell;
+    execute: (sql: string) => Promise<unknown>;
+    id?: string;
+    tables: readonly string[];
+};
+/**
+ * The cell as a testbed adapter.
+ *
+ * There is no template database here, so `restore()` is a TRUNCATE — and empty is the only state a
+ * truncate can return to. `snapshot()` therefore does not record the current rows: it EMPTIES the
+ * tables and marks that point, which is exactly the split the repo this comes from already has
+ * between its two setup files. A suite that seeds re-seeds after each restore.
+ *
+ * No `waitFor`: that repo has none, and its raised timeouts carry the waiting. Declaring a
+ * capability it does not have is the inert-capability failure this whole kit is written against.
+ */
+declare const workerdAdapter: (options: WorkerdAdapterOptions) => TestbedAdapter<Cell>;
+
+type LocalOnlyOptions = {
+    /** Vars naming something that lives outside the worker, so a suite's own seam is what is reached. */
+    dropVars?: readonly string[];
+    /** Bindings the platform cannot emulate locally. */
+    remoteOnly?: readonly string[];
+    source: string;
+    /** A file name — it must stay beside the source, and the refusal below says why. */
+    target?: string;
+};
+/**
+ * The real wrangler config, minus what cannot run locally — DERIVED on every start rather than kept
+ * as a second file, so a binding added to the real one is in the suites the same day and the one
+ * kind of binding that cannot be emulated is the one kind the suites never get.
+ *
+ * This is what makes "tests never call a model" a property of the runtime: in the test worker there
+ * is no `env.AI` to call.
+ */
+declare const deriveLocalOnlyConfig: (options: LocalOnlyOptions) => string;
+
+type VitestReport = {
+    numFailedTests?: number;
+    success?: boolean;
+} | null;
+type Verdict = {
+    ok: boolean;
+    why: string;
+};
+type StrictRun = {
+    /** The runner's own exit code, kept: a clean report does not make a non-zero exit fine. */
+    code: number;
+    reportPath: string;
+    verdict: Verdict;
+};
+type StrictOptions = {
+    args?: readonly string[];
+    command?: string;
+    /** How the runner is told where to write its report. */
+    reportArg?: (path: string) => string;
+    /** Where to keep it. Given one, the caller owns it; otherwise it is a temp file, removed. */
+    reportPath?: string;
+    stdio?: 'ignore' | 'inherit';
+};
+/**
+ * The runner's answer, from what it RECORDED rather than from how it exited.
+ *
+ * `@cloudflare/vitest-pool-workers` exits 0 with failing tests, so every workerd green in the repo
+ * this comes from was hollow until something read the report instead. The order of the two checks
+ * is load-bearing: `success !== true` is asked FIRST, because `{ success: false, numFailedTests: 0 }`
+ * — the run that died before it finished — reads as a pass to anything that counts failures.
+ */
+declare const verdictOf: (report: VitestReport) => Verdict;
+declare const readReport: (path: string) => VitestReport;
+/** Run a test runner and judge its report. The exit code is reported, never believed. */
+declare const runStrict: (options?: StrictOptions) => Promise<StrictRun>;
+
+export { type Cell, type CellServerOptions, type ClusterLike, type LocalOnlyOptions, type StrictOptions, type StrictRun, type Verdict, type VitestReport, type WorkerdAdapterOptions, createCellServer, deriveLocalOnlyConfig, readReport, runStrict, truncateAllStatement, verdictOf, workerdAdapter };

package/dist/workerd/index.js

@@ -0,0 +1,143 @@
+import {
+  readReport,
+  runStrict,
+  verdictOf
+} from "../chunk-ULJUJOSR.js";
+
+// src/workerd/cell.ts
+import { mkdtempSync } from "fs";
+import { createServer } from "net";
+import { tmpdir } from "os";
+import { join } from "path";
+var DEFAULT_CONNECTION_ENV = "CELL_CONNECTION_STRING";
+var freePort = () => new Promise((done) => {
+  const probe = createServer();
+  probe.listen(0, "127.0.0.1", () => {
+    const address = probe.address();
+    probe.close(() => done(typeof address === "object" && address ? address.port : 0));
+  });
+});
+var createCellServer = async (options) => {
+  const external = process.env[options.connectionStringEnv ?? DEFAULT_CONNECTION_ENV];
+  if (external !== void 0 && external !== "") {
+    return {
+      appConnectionString: await options.prepare(external),
+      connectionString: external,
+      stop: async () => {
+      }
+    };
+  }
+  const port = options.port ?? await freePort();
+  const cluster = options.cluster({
+    databaseDir: mkdtempSync(join(tmpdir(), "geonosis-cell-")),
+    port
+  });
+  await cluster.initialise();
+  await cluster.start();
+  let stopped = false;
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    await cluster.stop();
+  };
+  const connectionString = options.connectionStringOf?.(port) ?? `postgres://postgres:postgres@127.0.0.1:${port}/postgres`;
+  try {
+    return { appConnectionString: await options.prepare(connectionString), connectionString, stop };
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+};
+var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var truncateAllStatement = (tables) => {
+  if (tables.length === 0) {
+    throw new Error(
+      "truncateAllStatement needs at least one table; a reset that resets nothing reads as isolation"
+    );
+  }
+  for (const table of tables) {
+    if (!IDENTIFIER.test(table)) {
+      throw new Error(
+        `"${table}" is not a plain identifier, and this list is usually derived from a schema object \u2014 a name that can close its own quoting can start a statement`
+      );
+    }
+  }
+  return `truncate table ${tables.map((table) => `"${table}"`).join(", ")} restart identity cascade`;
+};
+var workerdAdapter = (options) => {
+  const statement = truncateAllStatement(options.tables);
+  let marked = false;
+  const reset = async () => {
+    for (const before of options.before ?? []) await options.execute(before);
+    await options.execute(statement);
+  };
+  return {
+    boot: async () => ({ db: options.cell, teardown: options.cell.stop }),
+    id: options.id ?? "workerd",
+    restore: async () => {
+      if (!marked) {
+        throw new Error(
+          "restore() before any snapshot() would empty tables nobody asked to be emptied. Take a snapshot first \u2014 on a truncating cell it is the empty state."
+        );
+      }
+      await reset();
+    },
+    snapshot: async () => {
+      await reset();
+      marked = true;
+    }
+  };
+};
+
+// src/workerd/local-only-config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join as join2, resolve } from "path";
+var DEFAULT_REMOTE_ONLY = ["ai"];
+var DEFAULT_TARGET = ".wrangler.local-only.json";
+var stripJsonc = (source) => source.replaceAll(/^[ \t]*\/\/.*$/gm, "").replaceAll(/,(\s*[}\]])/g, "$1");
+var withoutRemoteOnly = (block, remoteOnly, dropVars) => {
+  const cleaned = { ...block };
+  for (const binding of remoteOnly) delete cleaned[binding];
+  const vars = cleaned.vars;
+  if (vars) {
+    const kept = { ...vars };
+    for (const name of dropVars) delete kept[name];
+    cleaned.vars = kept;
+  }
+  return cleaned;
+};
+var deriveLocalOnlyConfig = (options) => {
+  const source = resolve(options.source);
+  if (!existsSync(source)) throw new Error(`no wrangler config at ${source}`);
+  const target = options.target ?? DEFAULT_TARGET;
+  if (target.includes("/") || target.includes("\\")) {
+    throw new Error(
+      `the derived config must sit in the same directory as ${source}: a wrangler config's relative paths resolve against its own directory, so "${target}" would break main and migrations_dir. Give a file name, not a path.`
+    );
+  }
+  const remoteOnly = options.remoteOnly ?? DEFAULT_REMOTE_ONLY;
+  const dropVars = options.dropVars ?? [];
+  const parsed = JSON.parse(stripJsonc(readFileSync(source, "utf8")));
+  const cleaned = withoutRemoteOnly(parsed, remoteOnly, dropVars);
+  if (cleaned.env) {
+    cleaned.env = Object.fromEntries(
+      Object.entries(cleaned.env).map(([name, block]) => [
+        name,
+        withoutRemoteOnly(block, remoteOnly, dropVars)
+      ])
+    );
+  }
+  const at = join2(dirname(source), target);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, JSON.stringify(cleaned, null, 2));
+  return at;
+};
+export {
+  createCellServer,
+  deriveLocalOnlyConfig,
+  readReport,
+  runStrict,
+  truncateAllStatement,
+  verdictOf,
+  workerdAdapter
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@geonosis/testbed",
+  "version": "1.0.0",
+  "description": "The fixtures law as code, one adapter contract for an integration harness, and the conformance suite an adapter has to pass. Extracted from dielime's Medusa runner and during.day's workerd cell.",
+  "keywords": [
+    "testing",
+    "fixtures",
+    "integration",
+    "medusa",
+    "workerd",
+    "postgres"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/testbed",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/testbed"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./medusa-built": "./dist/medusa-built/index.js",
+    "./workerd": "./dist/workerd/index.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "geonosis-testbed": "bin/geonosis-testbed.mjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/templates/ci/db-matrix.yml

@@ -0,0 +1,46 @@
+name: cells
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  cells-embedded:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - run: bun install --frozen-lockfile
+
+      - name: The data layer
+        run: bun run --cwd packages/db test
+
+  cells-postgres:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        postgres: ['17', '18']
+    services:
+      cell:
+        image: postgres:${{ matrix.postgres }}
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - run: bun install --frozen-lockfile
+
+      - name: The data layer
+        env:
+          CELL_CONNECTION_STRING: postgres://postgres:postgres@127.0.0.1:5432/postgres
+        run: bun run --cwd packages/db test