@arcote.tech/arc-testing 0.7.27

package/README.md

@@ -0,0 +1,94 @@
+# @arcote.tech/arc-testing
+
+In-process test harness for Arc. Write **use-case-shaped** tests on `bun:test`
+using the **same scope API the client uses** — no port, no mocks of the framework,
+full type inference from your context.
+
+```ts
+import { createHarness } from "@arcote.tech/arc-testing";
+
+const h = await createHarness(myContext);
+
+// declare current state
+await h.seed.rows("plan", [{ _id: "plan_pro", price: 4900 }]);
+
+// an authenticated actor — the SAME scope API as the app
+const creator = h.scope(userToken, { projectId });
+
+await creator.mutation().startCheckout({ projectId, planId: "plan_pro" });
+const order = await creator.query().paymentOrder.findOne({ _id: orderId });
+
+// a webhook / route, in-process (real route boundary, no port)
+await h.route("payuWebhook", { orderId, status: "COMPLETED" });
+
+// drain the async listener cascade deterministically (no setTimeout)
+await h.settle();
+
+// assert events + state with native bun:test expect
+expect(h.events.ofType("subscriptionActivated")).toHaveLength(1);
+expect(await creator.query().subscription.findOne({ _id: projectId }))
+  .toMatchObject({ status: "active" });
+```
+
+## API
+
+| | |
+|---|---|
+| `createHarness(context)` | builds the harness (in-memory SQLite, declarative seeds run, listeners active) |
+| `h.scope(token, params)` | an authenticated scope — `.mutation()` (= client `useMutation`), `.query()` (= client `useQuery`, awaited rows) |
+| `h.anonymous()` | a scope with no identity (public caller) |
+| `h.seed.rows(store, rows)` | raw insert into a view/aggregate store (like `withSeed`); rows need `_id` |
+| `h.seed.event(type, payload, { as })` | publish through real projection handlers (and listeners) |
+| `h.route(name, body, { headers, token })` | invoke a route/webhook in-process (real verification + protection gate) |
+| `h.settle()` | resolve once the async listener cascade has fully drained |
+| `h.events` | typed log: `.ofType(name)`, `.last(name)`, `.count(name)`, `.all()` |
+
+`mutation()` / `query()` are the exact client `ScopeAPI` accessors (core's
+`MutationExecutor` / `QueryAccessor`) — element names, params, payloads and rows
+are all inferred from your context. No new naming layer, no `any`.
+
+## Recipe: testing the real billing `buy-subscription-card` (platform)
+
+Prerequisites (one-time, user-gated):
+1. Publish `@arcote.tech/arc`, `@arcote.tech/arc-host`, `@arcote.tech/arc-testing` to npm.
+2. Add `@arcote.tech/arc-testing` to `packages/billing` devDependencies (npm, **not** `link:` — `link:` breaks the Docker build).
+
+PayU-free reaction test (avoids the external gateway by injecting the domain
+event, then asserting the **real** billing listener cascade — grant → activation):
+
+```ts
+import { describe, it, expect, beforeEach } from "bun:test";
+import { createHarness, type Harness } from "@arcote.tech/arc-testing";
+import { getBillingContext } from "@ndt/billing";
+import { userToken } from "@ndt/auth";
+
+describe("buy-subscription-card (billing reaction)", () => {
+  let h: Harness<ReturnType<typeof getBillingContext>>;
+  const accountId = "acc_test";
+
+  beforeEach(async () => { h = await createHarness(getBillingContext()); });
+
+  it("paid order → grant → subscription activated", async () => {
+    const user = h.scope(userToken, { accountId, role: "user" });
+
+    // inject the 'payment completed' domain event with the caller's identity,
+    // then let the real billingPaymentGrant → billingSubscriptionActivation chain run
+    await h.seed.event(
+      "paymentOrderCompleted",
+      { _id: "order_1", userId: accountId, amountPLNGrosz: 4900, kind: "subscription" },
+      { as: { tokenName: "user", params: { accountId, role: "user" } } },
+    );
+    await h.settle();
+
+    expect(h.events.ofType("subscriptionActivated")).toHaveLength(1);
+    const sub = await user.query().subscription.findOne({ _id: accountId });
+    expect(sub).toMatchObject({ /* active subscription shape */ });
+  });
+});
+```
+
+For the **full** checkout-through-webhook flow (`startCheckoutCardAsUser` →
+`payuWebhook`), stub the PayU client the checkout/route modules call, then drive
+it with `creator.mutation().startCheckoutCardAsUser(...)` and
+`h.route("payuWebhook", payuBody)` exactly as the self-proof does
+(`tests/buy-subscription-like.test.ts`).

package/dist/index.js

@@ -0,0 +1,121 @@
+// src/harness.ts
+import {
+  BunSQLiteDatabase,
+  createSQLiteAdapterFactory
+} from "@arcote.tech/arc-adapter-db-sqlite";
+import { ContextHandler } from "@arcote.tech/arc-host";
+
+// src/events.ts
+function createEventLog(publisher) {
+  const records = [];
+  publisher.subscribe("*", (ev) => {
+    records.push({
+      id: ev.id,
+      type: ev.type,
+      payload: ev.payload,
+      createdAt: ev.createdAt ?? new Date,
+      authContext: ev.authContext ?? null
+    });
+  });
+  const matches = (recordType, query) => recordType === query || recordType.endsWith(`.${query}`);
+  return {
+    all: () => [...records],
+    ofType: (type) => records.filter((r) => matches(r.type, type)),
+    last: (type) => {
+      for (let i = records.length - 1;i >= 0; i--) {
+        if (matches(records[i].type, type))
+          return records[i];
+      }
+      return;
+    },
+    count: (type) => records.filter((r) => matches(r.type, type)).length
+  };
+}
+
+// src/scope.ts
+import {
+  buildContextAccessor,
+  ScopedModel
+} from "@arcote.tech/arc";
+function createScope(model, name) {
+  const scoped = new ScopedModel(model, name);
+  const mutation = () => buildContextAccessor(scoped.context, scoped.getAdapters(), "mutateContext", (_descriptor, execute) => execute());
+  const query = () => buildContextAccessor(scoped.context, scoped.getAdapters(), "queryContext", (_descriptor, execute) => execute());
+  return {
+    mutation,
+    query,
+    setToken: (token) => scoped.setToken(token),
+    setIdentity: (tokenName, params) => {
+      scoped.getAdapters().authAdapter?.setDecoded({ tokenName, params });
+    },
+    scoped
+  };
+}
+
+// src/seed.ts
+function createSeed(dataStorage, publisher) {
+  let counter = 0;
+  return {
+    rows: async (store, rows) => {
+      const target = dataStorage.getStore(store);
+      await target.applyChanges(rows.map((data) => ({ type: "set", data })));
+    },
+    event: async (type, payload, opts) => {
+      await publisher.publish({
+        id: `seed_${type}_${++counter}`,
+        type,
+        payload,
+        createdAt: new Date,
+        authContext: opts?.as ?? null
+      });
+    }
+  };
+}
+
+// src/harness.ts
+var scopeCounter = 0;
+async function createHarness(context) {
+  const factory = createSQLiteAdapterFactory(new BunSQLiteDatabase(":memory:"));
+  const contextHandler = new ContextHandler(context, factory(context));
+  await contextHandler.init();
+  const model = contextHandler.getModel();
+  const dataStorage = contextHandler.getDataStorage();
+  const publisher = contextHandler.getEventPublisher();
+  const events = createEventLog(publisher);
+  const seed = createSeed(dataStorage, publisher);
+  function scope(tokenOrName, params) {
+    if (typeof tokenOrName === "string") {
+      return createScope(model, tokenOrName);
+    }
+    const s = createScope(model, `${tokenOrName.name}_${++scopeCounter}`);
+    s.setIdentity(tokenOrName.name, params ?? {});
+    return s;
+  }
+  return {
+    scope,
+    anonymous: () => createScope(model, `anon_${++scopeCounter}`),
+    seed,
+    events,
+    route: async (name, body, opts) => {
+      const response = await contextHandler.executeRoute(name, {
+        method: opts?.method,
+        body,
+        headers: opts?.headers,
+        query: opts?.query
+      }, opts?.token ?? null);
+      let json = null;
+      try {
+        json = await response.clone().json();
+      } catch {
+        json = null;
+      }
+      return { status: response.status, json, response };
+    },
+    settle: () => publisher.whenIdle?.() ?? Promise.resolve(),
+    destroy: () => dataStorage.destroy(),
+    contextHandler
+  };
+}
+export {
+  createHarness
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@arcote.tech/arc-testing",
+  "version": "0.7.27",
+  "type": "module",
+  "private": false,
+  "author": "Przemysław Krasiński [arcote.tech]",
+  "description": "In-process test harness for Arc — write use-case-shaped tests on bun:test with the same scope API the client uses",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node --format esm --external @arcote.tech/arc --external @arcote.tech/arc-host --external @arcote.tech/arc-adapter-db-sqlite && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declaration --declarationMap --outDir ./dist",
+    "postbuild": "rm -f tsconfig.tsbuildinfo",
+    "type-check": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "^0.7.27",
+    "@arcote.tech/arc-host": "^0.7.27",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.27"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}