@acmekit/acmekit 2.13.83 → 2.13.84

package/dist/templates/app/.claude/rules/testing.md

@@ -10,39 +10,54 @@ paths:
 
 ## Critical — Read Before Writing Any Test
 
+**Single unified runner.** Use `integrationTestRunner` from `@acmekit/test-utils` with a `mode` parameter. The old names (`acmekitIntegrationTestRunner`, `moduleIntegrationTestRunner`) are deprecated aliases — NEVER use them.
+
 **Service resolution key = module constant.** For core modules, use `Modules.AUTH`, `Modules.USER`, etc. For custom modules, use the constant from your module definition (e.g., `BLOG_MODULE = "blog"` — the string passed to `Module()`). NEVER guess `"blogModuleService"` or `"postModuleService"` — it won't resolve.
 
 **Workflow errors are plain objects, not Error instances.** The distributed transaction engine serializes them. NEVER use `.rejects.toThrow()` on workflows — it always fails with "Received function did not throw". Use `throwOnError: false` + `errors` array, or `.rejects.toEqual(expect.objectContaining({ message }))`.
 
 **Error path is `errors[0].error.message`** — NOT `errors[0].message`. Each item in the `errors` array wraps the actual error under `.error`.
 
-**`acmekitIntegrationTestRunner` runs real migrations** — custom modules MUST have migration files or you get `TableNotFoundException`. Run `npx acmekit db:generate <module>` and `npx acmekit db:migrate` before running HTTP integration tests. `moduleIntegrationTestRunner` syncs schema from entities (no migrations needed).
+**`mode: "app"` runs real migrations** — custom modules MUST have migration files or you get `TableNotFoundException`. Run `npx acmekit db:generate <module>` and `npx acmekit db:migrate` before running HTTP or app integration tests. `mode: "module"` syncs schema from entities (no migrations needed).
 
 **`.rejects.toThrow()` DOES work for service errors** (e.g., `service.retrievePost("bad-id")`). Services throw real `Error` instances. Only workflow errors are serialized.
 
+**Inline auth setup.** There is no `createAdminUser` helper. Resolve `Modules.USER`, `Modules.AUTH`, `Modules.API_KEY` from the container and create credentials directly in `beforeEach`.
+
 ---
 
 ## Test Runner Selection
 
-| What to test | Runner | Fixtures provided | DB setup |
-|---|---|---|---|
-| Module service CRUD | `moduleIntegrationTestRunner` | `service`, `MikroOrmWrapper`, `acmekitApp`, `dbConfig` | Schema sync (no migrations) |
-| HTTP API routes end-to-end | `acmekitIntegrationTestRunner` | `api`, `getContainer()`, `dbConnection`, `dbUtils`, `utils` | Runs migrations (files required) |
-| Pure functions (no DB) | Plain Jest `describe/it` | none | N/A |
+| What to test | Mode | HTTP? | Fixtures | DB setup |
+|---|---|---|---|---|
+| HTTP API routes end-to-end | `mode: "app"` | yes (default) | `api`, `getContainer()`, `container`, `dbConnection`, `dbUtils`, `utils` | Runs migrations |
+| Workflows, subscribers, jobs (no HTTP) | `mode: "app"` | yes (default) | `getContainer()`, `container`, `utils` | Runs migrations |
+| Module service CRUD in isolation | `mode: "module"` | no | `service`, `MikroOrmWrapper`, `acmekitApp`, `dbConfig` | Schema sync (no migrations) |
+| Pure functions (no DB) | Plain Jest `describe/it` | — | none | N/A |
+
+---
 
 ## File Locations (must match `jest.config.js` buckets)
 
 ```
 integration-tests/http/<feature>.spec.ts   → TEST_TYPE=integration:http
+integration-tests/app/<feature>.spec.ts    → TEST_TYPE=integration:app
 src/modules/<mod>/__tests__/<name>.spec.ts → TEST_TYPE=integration:modules
 src/**/__tests__/<name>.unit.spec.ts       → TEST_TYPE=unit
 ```
 
+**`integration-tests/http/`** — tests that need the `api` fixture (HTTP requests to admin/client routes).
+
+**`integration-tests/app/`** — tests that only need `getContainer()` (workflows, subscribers, jobs, direct service calls). Same `mode: "app"` runner, same migrations — but no need for auth setup or HTTP assertions.
+
+---
+
 ## Commands
 
 ```bash
 pnpm test:unit                    # Unit tests
 pnpm test:integration:modules     # Module integration tests
+pnpm test:integration:app         # App integration tests (no HTTP)
 pnpm test:integration:http        # HTTP integration tests
 ```
 
@@ -50,27 +65,255 @@ All integration tests require `NODE_OPTIONS=--experimental-vm-modules` (set in p
 
 ---
 
-## Module Integration Tests
+## HTTP Integration Tests (`integration-tests/http/`)
+
+**IMPORTANT:** `api` is a standard axios instance. Axios throws on non-2xx status codes. For error-case tests, use `.catch((e: any) => e)` to capture the error response.
 
 ```typescript
-import { moduleIntegrationTestRunner, MockEventBusService } from "@acmekit/test-utils"
-import { Modules } from "@acmekit/framework/utils"
+import { integrationTestRunner } from "@acmekit/test-utils"
+import {
+  ApiKeyType,
+  CLIENT_API_KEY_HEADER,
+  ContainerRegistrationKeys,
+  generateJwtToken,
+  Modules,
+} from "@acmekit/framework/utils"
 
-jest.setTimeout(30000)
+jest.setTimeout(60 * 1000)
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ api, getContainer }) => {
+    let adminHeaders: Record<string, any>
+    let clientHeaders: Record<string, any>
+
+    beforeEach(async () => {
+      const container = getContainer()
+      const userModule = container.resolve(Modules.USER)
+      const authModule = container.resolve(Modules.AUTH)
+      const apiKeyModule = container.resolve(Modules.API_KEY)
+
+      // Create admin user
+      const user = await userModule.createUsers({
+        email: "admin@test.js",
+      })
+
+      // Create auth identity
+      const authIdentity = await authModule.createAuthIdentities({
+        provider_identities: [
+          { provider: "emailpass", entity_id: "admin@test.js" },
+        ],
+        app_metadata: { user_id: user.id },
+      })
+
+      // Generate JWT from project config — NEVER hardcode the secret
+      const config = container.resolve(
+        ContainerRegistrationKeys.CONFIG_MODULE
+      )
+      const { jwtSecret, jwtOptions } = config.projectConfig.http
+
+      const token = generateJwtToken(
+        {
+          actor_id: user.id,
+          actor_type: "user",
+          auth_identity_id: authIdentity.id,
+          app_metadata: { user_id: user.id },
+        },
+        { secret: jwtSecret, expiresIn: "1d", jwtOptions }
+      )
+
+      adminHeaders = {
+        headers: { authorization: `Bearer ${token}` },
+      }
+
+      // Create client API key
+      const apiKey = await apiKeyModule.createApiKeys({
+        title: "Test Client Key",
+        type: ApiKeyType.CLIENT,
+        created_by: "test",
+      })
+
+      clientHeaders = {
+        headers: { [CLIENT_API_KEY_HEADER]: apiKey.token },
+      }
+    })
+
+    describe("GET /admin/posts", () => {
+      it("should list posts", async () => {
+        const response = await api.get("/admin/posts", adminHeaders)
+        expect(response.status).toEqual(200)
+        expect(response.data.posts).toBeDefined()
+      })
+    })
+
+    describe("POST /admin/posts", () => {
+      it("should create a post", async () => {
+        const response = await api.post(
+          "/admin/posts",
+          { title: "Launch Announcement" },
+          adminHeaders
+        )
+        expect(response.status).toEqual(200)
+        expect(response.data.post).toEqual(
+          expect.objectContaining({
+            id: expect.any(String),
+            title: "Launch Announcement",
+          })
+        )
+      })
+
+      it("should reject missing required fields with 400", async () => {
+        const { response } = await api
+          .post("/admin/posts", {}, adminHeaders)
+          .catch((e: any) => e)
+        expect(response.status).toEqual(400)
+      })
+    })
+
+    describe("DELETE /admin/posts/:id", () => {
+      it("should delete and return confirmation", async () => {
+        const created = (
+          await api.post("/admin/posts", { title: "To Remove" }, adminHeaders)
+        ).data.post
+
+        const response = await api.delete(
+          `/admin/posts/${created.id}`,
+          adminHeaders
+        )
+        expect(response.status).toEqual(200)
+        expect(response.data).toEqual({
+          id: created.id,
+          object: "post",
+          deleted: true,
+        })
+      })
+    })
 
-moduleIntegrationTestRunner<IMyModuleService>({
-  moduleName: Modules.MY_MODULE,
-  resolve: "./src/modules/my-module",  // path from CWD to module root (for model auto-discovery)
-  // moduleModels: [Post, Comment],  // OR pass models explicitly
-  // moduleOptions: { jwt_secret: "test" },
-  injectedDependencies: {
-    [Modules.EVENT_BUS]: new MockEventBusService(),
+    describe("Client routes", () => {
+      it("should return 200 with client API key", async () => {
+        const response = await api.get("/client/posts", clientHeaders)
+        expect(response.status).toEqual(200)
+      })
+
+      it("should return 400 without API key", async () => {
+        const error = await api.get("/client/posts").catch((e: any) => e)
+        expect(error.response.status).toEqual(400)
+      })
+    })
   },
-  testSuite: ({ service }) => {
-    afterEach(() => {
-      jest.restoreAllMocks()
+})
+```
+
+### `integrationTestRunner` Options (app mode)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"app"` | **(required)** | Selects app mode |
+| `testSuite` | `(options) => void` | **(required)** | Callback containing `describe`/`it` blocks |
+| `cwd` | `string` | `process.cwd()` | Project root directory |
+| `acmekitConfigFile` | `string` | from `cwd` | Path to directory with `acmekit-config.ts` |
+| `env` | `Record<string, any>` | `{}` | Values written to `process.env` before app starts |
+| `dbName` | `string` | auto-generated | Override the computed DB name |
+| `schema` | `string` | `"public"` | Postgres schema |
+| `debug` | `boolean` | `false` | Enables DB query logging |
+| `disableAutoTeardown` | `boolean` | `false` | Skips table TRUNCATE in `beforeEach` |
+| `hooks` | `RunnerHooks` | `{}` | Lifecycle hooks (see below) |
+
+### Fixtures (`testSuite` callback)
+
+- `api` — axios instance pointed at `http://localhost:<port>` (random port per run)
+- `getContainer()` — returns the live `AcmeKitContainer`
+- `container` — proxy to the live container (auto-refreshed each `beforeEach`)
+- `dbConnection` — proxy to the knex connection
+- `dbUtils` — `{ create, teardown, shutdown }` for manual DB control
+- `dbConfig` — `{ dbName, schema, clientUrl }`
+- `getAcmeKitApp()` — returns the running `AcmeKitApp`
+- `utils.waitWorkflowExecutions()` — polls until all in-flight workflows complete (60s timeout)
+
+### Lifecycle hooks
+
+```typescript
+integrationTestRunner({
+  mode: "app",
+  hooks: {
+    beforeSetup: async () => { /* before pipeline setup */ },
+    afterSetup: async ({ container, api }) => { /* after pipeline setup */ },
+    beforeReset: async () => { /* before each test reset */ },
+    afterReset: async () => { /* after each test reset */ },
+  },
+  testSuite: ({ api, getContainer }) => { ... },
+})
+```
+
+### HTTP test lifecycle
+
+- `beforeAll`: boots full Express app (resolves plugins, runs migrations, starts HTTP server)
+- `beforeEach`: truncates all tables, re-runs module loaders, runs `createDefaultsWorkflow`
+- `afterEach`: **automatically calls `waitWorkflowExecutions()`** then `dbUtils.teardown()`
+- `afterAll`: drops DB, shuts down Express
+
+**IMPORTANT:** The runner calls `waitWorkflowExecutions()` automatically in `afterEach`. You do NOT need to call it in your tests unless you need workflow results BETWEEN two API calls in the same test.
+
+---
+
+## App Integration Tests (`integration-tests/app/`)
+
+For workflows, subscribers, and jobs that only need the container — no auth setup, no `api` fixture:
+
+```typescript
+import { integrationTestRunner } from "@acmekit/test-utils"
+import { createBlogsWorkflow } from "../../src/workflows/workflows"
+import { BLOG_MODULE } from "../../src/modules/blog"
+
+jest.setTimeout(60 * 1000)
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    describe("createBlogsWorkflow", () => {
+      it("should create a blog with defaults", async () => {
+        const { result } = await createBlogsWorkflow(getContainer()).run({
+          input: { blogs: [{ title: "My First Blog" }] },
+        })
+
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual(
+          expect.objectContaining({
+            id: expect.any(String),
+            title: "My First Blog",
+            status: "draft",
+          })
+        )
+      })
+
+      it("should reject invalid status via validation step", async () => {
+        const { errors } = await createBlogsWorkflow(getContainer()).run({
+          input: { blogs: [{ title: "Bad", status: "invalid_status" }] },
+          throwOnError: false,
+        })
+
+        expect(errors).toHaveLength(1)
+        expect(errors[0].error.message).toContain("Invalid blog status")
+      })
     })
+  },
+})
+```
+
+---
+
+## Module Integration Tests
+
+```typescript
+import { integrationTestRunner } from "@acmekit/test-utils"
+
+jest.setTimeout(30000)
 
+integrationTestRunner<IPostModuleService>({
+  mode: "module",
+  moduleName: "post",
+  resolve: process.cwd() + "/src/modules/post",
+  testSuite: ({ service }) => {
     describe("createPosts", () => {
       it("should create a post", async () => {
         const result = await service.createPosts([
@@ -93,25 +336,21 @@ moduleIntegrationTestRunner<IMyModuleService>({
 })
 ```
 
-### `moduleIntegrationTestRunner` Options
+### Module mode options
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `moduleName` | `string` | **(required)** | Module key — use `Modules.*` constant |
-| `resolve` | `string` | `undefined` | Path to module root for model discovery. Omit if tests run from the module's own directory. |
+| `mode` | `"module"` | **(required)** | Selects module mode |
+| `moduleName` | `string` | **(required)** | Module key — the string passed to `Module()` |
+| `resolve` | `string` | `undefined` | Absolute path to module root for model discovery |
 | `moduleModels` | `any[]` | auto-discovered | Explicit model list; overrides auto-discovery |
-| `moduleOptions` | `Record<string, any>` | `{}` | Module configuration (merged with DB config) |
+| `moduleOptions` | `Record<string, any>` | `{}` | Module configuration |
 | `moduleDependencies` | `string[]` | `undefined` | Other module names this module depends on |
 | `joinerConfig` | `any[]` | `[]` | Module joiner configuration |
-| `injectedDependencies` | `Record<string, any>` | `{}` | Override container registrations (e.g., MockEventBusService) |
-| `schema` | `string` | `"public"` | Postgres schema |
-| `dbName` | `string` | auto-generated | Override the computed DB name |
-| `debug` | `boolean` | `false` | Enables DB query logging |
-| `cwd` | `string` | `process.cwd()` | Working directory for model discovery |
-| `hooks` | `{ beforeModuleInit?, afterModuleInit? }` | `{}` | Lifecycle hooks |
-| `testSuite` | `(options: SuiteOptions<TService>) => void` | **(required)** | Test callback |
+| `injectedDependencies` | `Record<string, any>` | `{}` | Override container registrations |
+| `testSuite` | `(options) => void` | **(required)** | Test callback |
 
-### `SuiteOptions<TService>` fields
+### Module mode fixtures
 
 - `service` — proxy to the module service (auto-refreshed each `beforeEach`)
 - `MikroOrmWrapper` — raw DB access: `.getManager()`, `.forkManager()`, `.getOrm()`
@@ -125,14 +364,12 @@ Each `it` block gets: schema drop + recreate → fresh module boot → test runs
 ### CRUD test patterns
 
 ```typescript
-// --- Create (single object → single result, array → array result) ---
+// --- Create ---
 const [post] = await service.createPosts([{ title: "Test" }])
 
-// --- List ---
-const posts = await service.listPosts()
+// --- List with filters ---
 const filtered = await service.listPosts({ status: "published" })
 const withRelations = await service.listPosts({}, { relations: ["comments"] })
-const withSelect = await service.listPosts({}, { select: ["id", "title"] })
 
 // --- List and count ---
 const [posts, count] = await service.listAndCountPosts()
@@ -140,115 +377,38 @@ expect(count).toEqual(2)
 
 // --- Retrieve ---
 const post = await service.retrievePost(id)
-const withSelect = await service.retrievePost(id, { select: ["id"] })
-const serialized = JSON.parse(JSON.stringify(withSelect))
-expect(serialized).toEqual({ id })  // verifies no extra fields
 
-// --- Update (single or batch) ---
+// --- Update ---
 const updated = await service.updatePosts(id, { title: "New Title" })
-const batchUpdated = await service.updatePosts([{ id, title: "New" }])
 
 // --- Soft delete / restore ---
 await service.softDeletePosts([id])
 const listed = await service.listPosts({ id })
 expect(listed).toHaveLength(0)
-const withDeleted = await service.listPosts({ id }, { withDeleted: true })
-expect(withDeleted[0].deleted_at).toBeDefined()
 await service.restorePosts([id])
 
 // --- Hard delete ---
 await service.deletePosts([id])
-const remaining = await service.listPosts({ id: [id] })
-expect(remaining).toHaveLength(0)
 ```
 
 ### Error handling in module tests
 
 ```typescript
-// Style 1: .catch((e) => e) — preferred when checking message
-const error = await service.retrievePost("nonexistent").catch((e) => e)
+// Style 1: .catch((e: any) => e) — preferred when checking message
+const error = await service.retrievePost("nonexistent").catch((e: any) => e)
 expect(error.message).toEqual("Post with id: nonexistent was not found")
 
 // Style 2: rejects.toThrow() — when only checking it throws
 await expect(service.createPosts([{}])).rejects.toThrow()
-
-// Style 3: try/catch — when checking error.type or multiple fields
-let error
-try {
-  await service.deleteApiKeys([unrevokedKey.id])
-} catch (e) {
-  error = e
-}
-expect(error.type).toEqual("not_allowed")
-expect(error.message).toContain("Cannot delete api keys that are not revoked")
-```
-
-### Related entity testing
-
-```typescript
-// Create parent → create child with parent ID → fetch with relations
-const [category] = await service.createCategories([{ name: "Tech" }])
-const [post] = await service.createPosts([{ title: "Test", category_id: category.id }])
-
-const withRelation = await service.retrievePost(post.id, {
-  relations: ["category"],
-})
-expect(withRelation.category.name).toBe("Tech")
 ```
 
 ---
 
-## HTTP Integration Tests
-
-**IMPORTANT:** `api` is a standard axios instance. Axios throws on non-2xx status codes. For error-case tests, use `.catch((e) => e)` to capture the error response.
-
-### `acmekitIntegrationTestRunner` Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `testSuite` | `(options) => void` | **(required)** | Callback containing `describe`/`it` blocks |
-| `moduleName` | `string` | `ulid()` | Derives the test DB name |
-| `dbName` | `string` | from `moduleName` | Overrides the computed DB name |
-| `acmekitConfigFile` | `string` | `process.cwd()` | Path to directory with `acmekit-config.ts` |
-| `schema` | `string` | `"public"` | Postgres schema |
-| `env` | `Record<string, any>` | `{}` | Values written to `process.env` before app starts |
-| `debug` | `boolean` | `false` | Enables DB query logging |
-| `hooks` | `{ beforeServerStart? }` | `{}` | Called with container before HTTP server starts |
-| `cwd` | `string` | from `acmekitConfigFile` | Working directory for config resolution |
-| `disableAutoTeardown` | `boolean` | `false` | Skips `dbUtils.teardown()` in `afterEach` |
-
-**Do NOT use options not listed above.** `inApp` is accepted but has no effect.
-
-### `AcmeKitSuiteOptions` fields
-
-- `api` — axios instance pointed at `http://localhost:<port>` (random port per run)
-- `getContainer()` — returns the live `AcmeKitContainer`
-- `dbConnection` — proxy to the knex connection
-- `dbUtils` — `{ create, teardown, shutdown }` for manual DB control
-- `dbConfig` — `{ dbName, schema, clientUrl }`
-- `getAcmeKitApp()` — returns the running `AcmeKitApp`
-- `utils.waitWorkflowExecutions()` — polls until all in-flight workflows complete (60s timeout)
-
-### HTTP test lifecycle
-
-- `beforeAll`: boots full Express app (resolves plugins, runs migrations, starts HTTP server)
-- `beforeEach`: truncates all tables, re-runs module loaders, runs `createDefaultsWorkflow`
-- `afterEach`: **automatically calls `waitWorkflowExecutions()`** then `dbUtils.teardown()`
-- `afterAll`: drops DB, shuts down Express
-
-**IMPORTANT:** The runner calls `waitWorkflowExecutions()` automatically in `afterEach`. You do NOT need to call it in your tests unless you need workflow results BETWEEN two API calls in the same test.
-
-### Admin Auth Setup
-
-`createAdminUser` resolves `Modules.USER` and `Modules.AUTH` from the container, creates a user, hashes a password, generates a JWT, and **mutates `adminHeaders` by reference** — adding `authorization: Bearer <jwt>` to `adminHeaders.headers`.
-
-```typescript
-import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
-```
+## Auth Setup
 
-`adminHeaders` starts as `{ headers: { "x-acmekit-access-token": "test_token" } }`. After `createAdminUser` runs, it also has `authorization: Bearer <jwt>`.
+**MANDATORY for `/admin/*` routes** — every HTTP test MUST have a `beforeEach` that creates admin credentials. Without it, admin routes return 401.
 
-`createAdminUser` returns `{ user, authIdentity }` — capture these when you need user IDs in tests.
+**MANDATORY for `/client/*` routes** — every HTTP test MUST also create a client API key. Without it, client routes return 400.
 
 ### JWT Token Generation
 
@@ -261,14 +421,13 @@ import {
   Modules,
 } from "@acmekit/framework/utils"
 
-// Resolve the JWT secret from the project config — NEVER hardcode "supersecret"
 const config = container.resolve(ContainerRegistrationKeys.CONFIG_MODULE)
 const { jwtSecret, jwtOptions } = config.projectConfig.http
 
 const token = generateJwtToken(
   {
     actor_id: user.id,
-    actor_type: "user",           // or "customer" for customer auth
+    actor_type: "user",
     auth_identity_id: authIdentity.id,
     app_metadata: { user_id: user.id },
   },
@@ -291,185 +450,12 @@ const apiKeyModule = container.resolve(Modules.API_KEY)
 const apiKey = await apiKeyModule.createApiKeys({
   title: "Test Client Key",
   type: ApiKeyType.CLIENT,
-  created_by: "system",
-})
-
-const clientHeaders = {
-  headers: { [CLIENT_API_KEY_HEADER]: apiKey.token },
-}
-```
-
-### Service Resolution
-
-**ALWAYS use `Modules.*` constants** to resolve core services. NEVER use string literals like `"auth"`, `"user"`, `"customer"`.
-
-```typescript
-// RIGHT
-const authModule = container.resolve(Modules.AUTH)
-const userModule = container.resolve(Modules.USER)
-const apiKeyModule = container.resolve(Modules.API_KEY)
-
-// WRONG — string literals are fragile and may not match container keys
-const authModule = container.resolve("auth")        // ❌
-const userModule = container.resolve("user")        // ❌
-```
-
-### Admin Route Tests (`/admin/*`)
-
-**MANDATORY:** Every `/admin/*` route test MUST have `beforeEach` with `createAdminUser`. Without it, admin routes return 401.
-
-```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
-import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
-
-jest.setTimeout(50000)
-
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    let user: any
-
-    beforeEach(async () => {
-      const result = await createAdminUser(
-        dbConnection,
-        adminHeaders,
-        getContainer()
-      )
-      user = result.user
-    })
-
-    describe("GET /admin/posts", () => {
-      it("should list posts", async () => {
-        const response = await api.get("/admin/posts", adminHeaders)
-        expect(response.status).toEqual(200)
-        expect(response.data).toEqual({
-          count: 0,
-          limit: 20,
-          offset: 0,
-          posts: [],
-        })
-      })
-    })
-
-    describe("POST /admin/posts", () => {
-      it("should create a post", async () => {
-        const response = await api.post(
-          "/admin/posts",
-          { title: "Launch Announcement", body: "We are live." },
-          adminHeaders
-        )
-        expect(response.status).toEqual(200)
-        expect(response.data.post).toEqual(
-          expect.objectContaining({
-            id: expect.any(String),
-            title: "Launch Announcement",
-            created_at: expect.any(String),
-            updated_at: expect.any(String),
-          })
-        )
-      })
-
-      it("should reject invalid body with 400", async () => {
-        const { response } = await api
-          .post("/admin/posts", {}, adminHeaders)
-          .catch((e) => e)
-        expect(response.status).toEqual(400)
-      })
-
-      it("should reject unknown fields when .strict()", async () => {
-        const { response } = await api
-          .post(
-            "/admin/posts",
-            { title: "Test", unknown_field: "bad" },
-            adminHeaders
-          )
-          .catch((e) => e)
-        expect(response.status).toEqual(400)
-      })
-    })
-
-    describe("DELETE /admin/posts/:id", () => {
-      it("should delete and return confirmation", async () => {
-        const created = (
-          await api.post(
-            "/admin/posts",
-            { title: "To Remove" },
-            adminHeaders
-          )
-        ).data.post
-
-        const response = await api.delete(
-          `/admin/posts/${created.id}`,
-          adminHeaders
-        )
-        expect(response.status).toEqual(200)
-        expect(response.data).toEqual({
-          id: created.id,
-          object: "post",
-          deleted: true,
-        })
-      })
-
-      it("should return 404 for non-existent post", async () => {
-        const { response } = await api
-          .delete("/admin/posts/non-existent-id", adminHeaders)
-          .catch((e) => e)
-        expect(response.status).toEqual(404)
-        expect(response.data.type).toEqual("not_found")
-        expect(response.data.message).toContain("not found")
-      })
-    })
-  },
-})
-```
-
-### Client Route Tests (`/client/*`)
-
-**MANDATORY:** Every `/client/*` route test MUST have this `beforeEach` setup. Without `clientHeaders`, client route requests return 400 (`NOT_ALLOWED`).
-
-```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
-import {
-  adminHeaders,
-  createAdminUser,
-  generateClientKey,
-  generateClientHeaders,
-} from "../../helpers/create-admin-user"
-
-jest.setTimeout(50000)
-
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    let clientHeaders: Record<string, any>
-
-    beforeEach(async () => {
-      const container = getContainer()
-      await createAdminUser(dbConnection, adminHeaders, container)
-
-      const clientKey = await generateClientKey(container)
-      clientHeaders = generateClientHeaders({ publishableKey: clientKey })
-
-      // Seed test data via admin API if needed
-      await api.post("/admin/products", { title: "Widget" }, adminHeaders)
-    })
-
-    it("should list products", async () => {
-      const response = await api.get("/client/products", clientHeaders)
-      expect(response.status).toEqual(200)
-      expect(response.data.products).toHaveLength(1)
-    })
-  },
+  created_by: "test",
 })
-```
 
-If the public route needs no client key (rare), you can skip `generateClientKey`/`generateClientHeaders` — but most tests need them.
-
-### Feature flags via `env` option
-
-```typescript
-acmekitIntegrationTestRunner({
-  env: { ACMEKIT_FF_RBAC: true },
-  testSuite: ({ api, getContainer, dbConnection }) => { ... },
-})
+const clientHeaders = {
+  headers: { [CLIENT_API_KEY_HEADER]: apiKey.token },
+}
 ```
 
 ---
@@ -477,25 +463,21 @@ acmekitIntegrationTestRunner({
 ## Error Handling in HTTP Tests
 
 ```typescript
-// Error case — destructure response from caught error
+// 400 — validation error (axios throws on non-2xx)
 const { response } = await api
   .post("/admin/posts", {}, adminHeaders)
-  .catch((e) => e)
+  .catch((e: any) => e)
 expect(response.status).toEqual(400)
-expect(response.data.message).toContain("is required")
 
-// 404 case — also check type field
+// 404 — not found (also check type and message)
 const { response } = await api
   .get("/admin/posts/invalid-id", adminHeaders)
-  .catch((e) => e)
+  .catch((e: any) => e)
 expect(response.status).toEqual(404)
 expect(response.data.type).toEqual("not_found")
-expect(response.data.message).toEqual("Post with id: invalid-id not found")
 
-// Alternative: capture full error for .message check (Axios error message)
-const error = await api
-  .post("/admin/posts", {}, { headers: {} })
-  .catch((e) => e)
+// 401 — unauthorized
+const error = await api.get("/admin/posts").catch((e: any) => e)
 expect(error.response.status).toEqual(401)
 ```
 
@@ -515,73 +497,27 @@ expect(response.data.post).toEqual(
 )
 
 // List resource — nested under plural key with pagination
-expect(response.data).toEqual({
-  count: 2,
-  limit: 20,
-  offset: 0,
-  posts: expect.arrayContaining([
-    expect.objectContaining({ title: "Post A" }),
-    expect.objectContaining({ title: "Post B" }),
-  ]),
-})
+expect(response.data).toEqual(
+  expect.objectContaining({
+    posts: expect.arrayContaining([
+      expect.objectContaining({ title: "Post A" }),
+    ]),
+  })
+)
 
-// Delete response — exact match, no objectContaining
+// Delete response — exact match
 expect(response.data).toEqual({
   id: created.id,
   object: "post",
   deleted: true,
 })
-
-// Nested relations
-expect(response.data.post).toEqual(
-  expect.objectContaining({
-    comments: expect.arrayContaining([
-      expect.objectContaining({ body: "Great post" }),
-    ]),
-  })
-)
-
-// Negative assertion — item NOT in list
-expect(response.data.posts).toEqual(
-  expect.not.arrayContaining([
-    expect.objectContaining({ status: "archived" }),
-  ])
-)
-```
-
----
-
-## Query Parameter Testing
-
-```typescript
-// Field selection — `*` prefix expands relations
-api.get(`/admin/posts/${id}?fields=*comments`, adminHeaders)
-
-// Pagination
-api.get("/admin/posts?limit=2&offset=1", adminHeaders)
-
-// Ordering — `-` prefix for descending
-api.get("/admin/posts?order=-created_at", adminHeaders)
-
-// Free-text search
-api.get("/admin/posts?q=quarterly", adminHeaders)
-
-// Array filters
-api.get(`/admin/posts?status[]=published`, adminHeaders)
-api.get(`/admin/posts?id[]=${id1},${id2}`, adminHeaders)
-
-// Boolean filters
-api.get("/admin/posts?is_featured=true", adminHeaders)
-
-// With deleted
-api.get(`/admin/posts?with_deleted=true`, adminHeaders)
 ```
 
 ---
 
 ## Asserting Domain Events
 
-Both runners inject `MockEventBusService` under `Modules.EVENT_BUS`. Spy on the **prototype**, not an instance.
+Both runners inject `MockEventBusService` under `Modules.EVENT_BUS` in module mode. Spy on the **prototype**, not an instance.
 
 ```typescript
 import { MockEventBusService } from "@acmekit/test-utils"
@@ -599,9 +535,7 @@ afterEach(() => {
 it("should emit post.created event", async () => {
   await service.createPosts([{ title: "Event Test" }])
 
-  // Direct access to mock.calls for precise assertions
-  const events = eventBusSpy.mock.calls[0][0]  // first call, first arg = events array
-  expect(events).toHaveLength(1)
+  const events = eventBusSpy.mock.calls[0][0]
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
@@ -610,78 +544,168 @@ it("should emit post.created event", async () => {
       }),
     ])
   )
+})
+```
+
+---
+
+## Waiting for Subscribers
+
+Use `TestEventUtils.waitSubscribersExecution` when testing subscriber side-effects. **CRITICAL: create the promise BEFORE triggering the event.**
+
+### Pattern 1: Event bus driven (app mode with real event bus)
+
+```typescript
+import { integrationTestRunner, TestEventUtils } from "@acmekit/test-utils"
+import { Modules } from "@acmekit/framework/utils"
+import { BLOG_MODULE } from "../../src/modules/blog"
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should execute subscriber side-effect", async () => {
+      const container = getContainer()
+      const service: any = container.resolve(BLOG_MODULE)
+      const eventBus = container.resolve(Modules.EVENT_BUS)
+
+      const [blog] = await service.createBlogs([
+        { title: "Test", content: "Original", status: "published" },
+      ])
 
-  // Second argument is always { internal: true }
-  expect(eventBusSpy.mock.calls[0][1]).toEqual({ internal: true })
+      // Create promise BEFORE emitting event
+      const subscriberDone = TestEventUtils.waitSubscribersExecution(
+        "blog.published",
+        eventBus
+      )
+
+      // Emit event — single object { name, data } format
+      await eventBus.emit({ name: "blog.published", data: { id: blog.id } })
+      await subscriberDone
+
+      // Verify subscriber side-effect
+      const updated = await service.retrieveBlog(blog.id)
+      expect(updated.content).toBe("Original [notified]")
+    })
+  },
 })
 ```
 
 ---
 
-## Waiting for Async Workflows
+## Testing Jobs
 
-The runner calls `waitWorkflowExecutions()` automatically in `afterEach`. Only call it explicitly when you need workflow results **between** two API calls in the same test:
+Import the job function directly and call it with the container:
 
 ```typescript
-it("should process order via workflow", async () => {
-  await api.post("/admin/orders", { items: [...] }, adminHeaders)
+import { integrationTestRunner } from "@acmekit/test-utils"
+import archiveOldBlogsJob from "../../src/jobs/archive-old-blogs"
+import { BLOG_MODULE } from "../../src/modules/blog"
 
-  // ONLY needed because the next request depends on workflow completion
-  await utils.waitWorkflowExecutions()
+jest.setTimeout(60 * 1000)
 
-  const response = await api.get("/admin/orders", adminHeaders)
-  expect(response.data.orders[0].status).toBe("processed")
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should soft-delete archived blogs", async () => {
+      const container = getContainer()
+      const service: any = container.resolve(BLOG_MODULE)
+
+      await service.createBlogs([
+        { title: "Archived 1", status: "archived" },
+        { title: "Active", status: "published" },
+      ])
+
+      await archiveOldBlogsJob(container)
+
+      const remaining = await service.listBlogs()
+      expect(remaining).toHaveLength(1)
+      expect(remaining[0].title).toBe("Active")
+    })
+  },
 })
 ```
 
 ---
 
-## Waiting for Subscribers
+## Workflow Testing
 
-Use `TestEventUtils.waitSubscribersExecution` when testing subscriber side-effects. **CRITICAL: create the promise BEFORE triggering the event.**
+### Direct execution (no HTTP)
 
 ```typescript
-import { TestEventUtils } from "@acmekit/test-utils"
+import { createPostWorkflow } from "../../src/workflows/workflows"
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should execute the workflow", async () => {
+      const { result } = await createPostWorkflow(getContainer()).run({
+        input: { title: "Launch Announcement" },
+      })
+      expect(result).toEqual(
+        expect.objectContaining({
+          id: expect.any(String),
+          title: "Launch Announcement",
+        })
+      )
+    })
 
-it("should handle the event", async () => {
-  const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+    it("should reject invalid input", async () => {
+      const { errors } = await createPostWorkflow(getContainer()).run({
+        input: {},
+        throwOnError: false,
+      })
+      expect(errors).toHaveLength(1)
+      expect(errors[0].error.message).toContain("title")
+    })
 
-  // Create promise BEFORE triggering event
-  const subscriberExecution = TestEventUtils.waitSubscribersExecution(
-    "post.created",
-    eventBus
-  )
-  await api.post("/admin/posts", { title: "Trigger" }, adminHeaders)
-  await subscriberExecution
-  // now assert subscriber side-effect
+    // Workflow engine serializes errors as plain objects —
+    // use .rejects.toEqual(), NOT .rejects.toThrow()
+    it("should throw by default on error", async () => {
+      await expect(
+        updatePostWorkflow(getContainer()).run({
+          input: { id: "nonexistent", title: "Nope" },
+        })
+      ).rejects.toEqual(
+        expect.objectContaining({
+          message: expect.stringContaining("not found"),
+        })
+      )
+    })
+  },
+})
+```
+
+### Via HTTP (when route triggers the workflow)
+
+```typescript
+it("should process via workflow", async () => {
+  await api.post("/admin/orders", { items: [...] }, adminHeaders)
+  // Only needed if next request depends on workflow completion
+  await utils.waitWorkflowExecutions()
+  const response = await api.get("/admin/orders", adminHeaders)
+  expect(response.data.orders[0].status).toBe("processed")
 })
 ```
 
 ---
 
-## Resolving Services in Tests
+## Service Resolution
 
 ```typescript
-// In acmekitIntegrationTestRunner — use module constant (matches Module() key)
+// Custom modules — use module constant (matches the string passed to Module())
 import { BLOG_MODULE } from "../../src/modules/blog"  // BLOG_MODULE = "blog"
-const blogService = getContainer().resolve(BLOG_MODULE)
-const query = getContainer().resolve(ContainerRegistrationKeys.QUERY)
+const service = getContainer().resolve(BLOG_MODULE)
 
 // Core modules — use Modules.* constants
 const userModule = getContainer().resolve(Modules.USER)
 const authModule = getContainer().resolve(Modules.AUTH)
 
-// Resolve in beforeAll for reuse (container proxy stays current)
-let container: AcmeKitContainer
-beforeAll(() => {
-  container = getContainer()
-})
-
-// In moduleIntegrationTestRunner — use the `service` fixture directly
-const result = await service.listPosts()
+// Framework services
+const query = getContainer().resolve(ContainerRegistrationKeys.QUERY)
 
-// NEVER guess the key — "blogModuleService", "postModuleService" are all WRONG
-// The key is EXACTLY the string passed to Module() in your module definition
+// WRONG — string literals are fragile
+getContainer().resolve("auth")            // ❌
+getContainer().resolve("blogModuleService")  // ❌
 ```
 
 ---
@@ -689,7 +713,7 @@ const result = await service.listPosts()
 ## Environment
 
 - `jest.config.js` loads `.env.test` via `@acmekit/utils` `loadEnv("test", process.cwd())`
-- `integration-tests/setup.js` clears `MetadataStorage` between test files (prevents MikroORM entity bleed)
+- `integration-tests/setup.js` clears `MetadataStorage` between test files
 - DB defaults: `DB_HOST=localhost`, `DB_USERNAME=postgres`, `DB_PASSWORD=""`, `DB_PORT=5432`
 - Each test run creates a unique DB: `acmekit-<module>-integration-<JEST_WORKER_ID>`
 
@@ -698,86 +722,44 @@ const result = await service.listPosts()
 ## Anti-Patterns — NEVER Do These
 
 ```typescript
-// WRONG — no beforeEach in HTTP tests
-acmekitIntegrationTestRunner({
-  testSuite: ({ api }) => {
-    it("should list", async () => {
-      await api.get("/admin/posts")  // ❌ 401 — no createAdminUser, no adminHeaders
-    })
-  },
+// WRONG — using deprecated runner names
+import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"  // ❌
+import { moduleIntegrationTestRunner } from "@acmekit/test-utils"  // ❌
+// RIGHT — use unified runner with mode
+import { integrationTestRunner } from "@acmekit/test-utils"
+integrationTestRunner({ mode: "app", testSuite: ... })
+integrationTestRunner({ mode: "module", moduleName: "post", ... })
+
+// WRONG — using createAdminUser helper (does not exist)
+import { createAdminUser } from "../../helpers/create-admin-user"  // ❌
+// RIGHT — inline auth setup in beforeEach (see Auth Setup section)
+
+// WRONG — no auth in HTTP tests
+it("should list", async () => {
+  await api.get("/admin/posts")  // ❌ 401 — no authorization header
 })
 
 // WRONG — client route without clientHeaders
 await api.get("/client/products")  // ❌ 400 — no client API key
-await api.post("/client/orders", body)  // ❌ same
-// RIGHT
-await api.get("/client/products", clientHeaders)
-await api.post("/client/orders", body, clientHeaders)
-
-// WRONG — forgetting adminHeaders on admin routes
-await api.get("/admin/posts")  // ❌ 401
-// RIGHT
-await api.get("/admin/posts", adminHeaders)
 
-// WRONG — asserting error responses without catching (axios throws on 4xx/5xx!)
+// WRONG — asserting error responses without catching (axios throws!)
 const response = await api.post("/admin/posts", {}, adminHeaders)
 expect(response.status).toEqual(400)  // ❌ never reached — axios threw
 // RIGHT
-const { response } = await api.post("/admin/posts", {}, adminHeaders).catch((e) => e)
-expect(response.status).toEqual(400)
-
-// WRONG — mixing success/error response access
-const result = await api.post("/admin/posts", body).catch((e) => e)
-const status = result.status ?? result.response?.status  // ❌ confused pattern
-// RIGHT — success: result.status / result.data; error: result.response.status / result.response.data
-
-// WRONG — silently passes without asserting
-const result = await api.post("/client/execute", body).catch((e) => e)
-if (result.status !== 200) return  // ❌ test passes with zero assertions!
-
-// WRONG — vague range hides which error actually occurred
-expect(response.status).toBeGreaterThanOrEqual(400)  // ❌
-// RIGHT
+const { response } = await api.post("/admin/posts", {}, adminHeaders).catch((e: any) => e)
 expect(response.status).toEqual(400)
 
-// WRONG — using non-standard Jest matchers (not available without jest-extended)
-expect(value).toBeOneOf([expect.any(String), null])  // ❌
-expect(value).toSatisfy(fn)  // ❌
-// RIGHT
-expect(value === null || typeof value === "string").toBe(true)
-
-// WRONG — typeof checks on response fields
-expect(typeof result.data.id).toBe("string")  // ❌
-// RIGHT
-expect(result.data.id).toEqual(expect.any(String))
-
-// WRONG — JSDoc comment block at file top (test files never have these)
-/** POST /admin/posts — validates body, creates post */  // ❌
-
-// WRONG — type casts in tests
-const filtered = (operations as Array<{ status: string }>).filter(...)  // ❌
-
-// WRONG — wrapping body in { body: ... }
-await api.post("/admin/posts", { body: { title: "Test" } })  // ❌
-// RIGHT
-await api.post("/admin/posts", { title: "Test" }, adminHeaders)
-
 // WRONG — calling waitWorkflowExecutions in every test
 await api.post("/admin/posts", body, adminHeaders)
 await utils.waitWorkflowExecutions()  // ❌ unnecessary — runner does this in afterEach
-expect(response.data.post.id).toBeDefined()
-// RIGHT — only call it when the NEXT request in the same test needs workflow results
 
 // WRONG — calling waitSubscribersExecution AFTER triggering event
-await api.post("/admin/posts", body, adminHeaders)
+await eventBus.emit({ name: "post.created", data: { id } })
 await TestEventUtils.waitSubscribersExecution("post.created", eventBus)  // ❌ may miss it
 // RIGHT — capture promise BEFORE triggering
-const execution = TestEventUtils.waitSubscribersExecution("post.created", eventBus)
-await api.post("/admin/posts", body, adminHeaders)
-await execution
-
-// WRONG — using `inApp: true` (accepted but no-op)
-acmekitIntegrationTestRunner({ inApp: true, testSuite: ... })  // ❌
+const done = TestEventUtils.waitSubscribersExecution("post.created", eventBus)
+await eventBus.emit({ name: "post.created", data: { id } })
+await done
 
 // WRONG — asserting exact objects (timestamps/IDs change)
 expect(result).toEqual({ id: "123", title: "Test", created_at: "2024-01-01" })  // ❌
@@ -787,44 +769,27 @@ expect(result).toEqual(expect.objectContaining({
   title: "Test",
 }))
 
-// WRONG — passing module object to resolve (type error: expects string)
-import MyModule from "../index"
-moduleIntegrationTestRunner({ resolve: MyModule, ... })  // ❌
-
-// WRONG — relative path from test file (model discovery uses CWD, not test file dir!)
-moduleIntegrationTestRunner({ resolve: "../index", ... })  // ❌ hangs — models not found
-// RIGHT — path from project root (CWD)
-moduleIntegrationTestRunner({ resolve: "./src/modules/my-module", ... })
-
-// WRONG — unused imports
-import { ContainerRegistrationKeys } from "@acmekit/framework/utils"  // ❌ if never used
-// RIGHT — only import what you use
-
-// WRONG — guessing service resolution key (AwilixResolutionError!)
-getContainer().resolve("myModuleService")  // ❌ wrong key — no such registration
-getContainer().resolve("my-module-service")  // ❌ also wrong
-// RIGHT — use module constant (matches the string passed to Module())
-import { MY_MODULE } from "../../src/modules/my-module"  // MY_MODULE = "my-module"
-getContainer().resolve(MY_MODULE)
+// WRONG — using non-standard Jest matchers
+expect(value).toBeOneOf([expect.any(String), null])  // ❌
+// RIGHT
+expect(value === null || typeof value === "string").toBe(true)
 
-// WRONG — putting test files in non-standard locations
-// src/modules/post/tests/post.test.ts  ← won't be picked up
+// WRONG — typeof checks on result fields
+expect(typeof result.id).toBe("string")  // ❌
 // RIGHT
-// src/modules/post/__tests__/post.spec.ts
+expect(result.id).toEqual(expect.any(String))
 
-// WRONG — calling workflow directly in tests without container
+// WRONG — calling workflow without passing container
 await createPostWorkflow.run({ input: { title: "Test" } })  // ❌
 // RIGHT
 await createPostWorkflow(getContainer()).run({ input: { title: "Test" } })
 
 // WRONG — using .rejects.toThrow() on workflow errors
-// The distributed transaction engine serializes errors into plain objects
-// (not Error instances), so .toThrow() never matches.
 await expect(
   createPostWorkflow(getContainer()).run({ input: {} })
-).rejects.toThrow()  // ❌ always fails — "Received function did not throw"
+).rejects.toThrow()  // ❌ always fails — plain object, not Error instance
 
-// RIGHT — Option 1: use throwOnError: false + errors array (recommended)
+// RIGHT — Option 1: throwOnError: false + errors array (recommended)
 const { errors } = await createPostWorkflow(getContainer()).run({
   input: {},
   throwOnError: false,
@@ -832,7 +797,7 @@ const { errors } = await createPostWorkflow(getContainer()).run({
 expect(errors).toHaveLength(1)
 expect(errors[0].error.message).toContain("title")
 
-// RIGHT — Option 2: use .rejects.toEqual() for plain object matching
+// RIGHT — Option 2: .rejects.toEqual() for plain object matching
 await expect(
   createPostWorkflow(getContainer()).run({ input: {} })
 ).rejects.toEqual(
@@ -841,364 +806,46 @@ await expect(
   })
 )
 
-// NOTE: .rejects.toThrow() DOES work for service-level errors (e.g.,
-// service.retrievePost("bad-id")) because services throw real Error
-// instances. The serialization only happens in the workflow engine.
-
-// WRONG — asserting batch results without checking each operation type
-expect(response.data).toBeDefined()  // ❌ too vague
+// WRONG — wrapping body in { body: ... }
+await api.post("/admin/posts", { body: { title: "Test" } })  // ❌
 // RIGHT
-expect(response.data.created).toHaveLength(1)
-expect(response.data.updated).toHaveLength(1)
-expect(response.data.deleted).toHaveLength(1)
-
-// WRONG — sorting assertion without reliable comparison
-expect(response.data.posts[0].title).toBe("Alpha")  // ❌ fragile
-// RIGHT — verify entire order
-const titles = response.data.posts.map((p) => p.title)
-expect(titles).toEqual([...titles].sort())
-```
-
----
-
-## Testing Workflows via HTTP
-
-Workflows triggered by API routes are tested end-to-end. The runner calls `waitWorkflowExecutions()` in `afterEach`, so simple create/update flows just work.
-
-### Direct workflow execution (no HTTP)
-
-For testing workflow logic in isolation within `acmekitIntegrationTestRunner`:
-
-```typescript
-import { createPostWorkflow } from "../../src/workflows"
-
-acmekitIntegrationTestRunner({
-  testSuite: ({ getContainer, dbConnection, api }) => {
-    beforeEach(async () => {
-      await createAdminUser(dbConnection, adminHeaders, getContainer())
-    })
-
-    it("should execute the workflow", async () => {
-      const { result } = await createPostWorkflow(getContainer()).run({
-        input: {
-          title: "Launch Announcement",
-          author_id: "auth_123",
-        },
-      })
-      expect(result.post).toEqual(
-        expect.objectContaining({
-          id: expect.any(String),
-          title: "Launch Announcement",
-        })
-      )
-    })
-
-    it("should reject invalid input via schema", async () => {
-      const { errors } = await createPostWorkflow(getContainer()).run({
-        input: {},
-        throwOnError: false,
-      })
-      expect(errors).toHaveLength(1)
-      expect(errors[0].error.message).toContain("title")
-    })
-  },
-})
-```
-
-### Long-running / async workflow testing
-
-For workflows with async steps (e.g., `createStep` with `async: true`), use `subscribe` + `setStepSuccess`:
-
-```typescript
-import { Modules } from "@acmekit/framework/utils"
-
-it("should complete async workflow", async () => {
-  const container = getContainer()
-  const workflowEngine = container.resolve(Modules.WORKFLOW_ENGINE)
-
-  // Start the workflow
-  const { transaction } = await processOrderWorkflow(container).run({
-    input: { orderId: order.id },
-    throwOnError: false,
-  })
-
-  // Subscribe to completion
-  const workflowCompletion = new Promise<void>((resolve) => {
-    workflowEngine.subscribe({
-      workflowId: "process-order",
-      transactionId: transaction.transactionId,
-      subscriber: (event) => {
-        if (event.eventType === "onFinish") {
-          resolve()
-        }
-      },
-    })
-  })
-
-  // Complete the async step
-  await workflowEngine.setStepSuccess({
-    idempotencyKey: {
-      action: "invoke",
-      stepId: "external-payment-step",
-      workflowId: "process-order",
-      transactionId: transaction.transactionId,
-    },
-    stepResponse: { paymentId: "pay_123" },
-  })
-
-  await workflowCompletion
-
-  // Verify final state
-  const processedOrder = await api.get(
-    `/admin/orders/${order.id}`,
-    adminHeaders
-  )
-  expect(processedOrder.data.order.status).toBe("processed")
-})
-```
-
----
-
-## Batch Operations
-
-Routes that accept `{ create, update, delete }` as input and return `{ created, updated, deleted }`:
-
-```typescript
-it("should handle batch operations", async () => {
-  // Seed existing data
-  const existing = (
-    await api.post(
-      "/admin/posts",
-      { title: "Existing Post" },
-      adminHeaders
-    )
-  ).data.post
-
-  const response = await api.post(
-    "/admin/posts/batch",
-    {
-      create: [{ title: "New Post" }],
-      update: [{ id: existing.id, title: "Updated Post" }],
-      delete: [existing.id],
-    },
-    adminHeaders
-  )
-
-  expect(response.status).toEqual(200)
-  expect(response.data.created).toHaveLength(1)
-  expect(response.data.created[0]).toEqual(
-    expect.objectContaining({ title: "New Post" })
-  )
-  expect(response.data.updated).toHaveLength(1)
-  expect(response.data.updated[0].title).toBe("Updated Post")
-  expect(response.data.deleted).toHaveLength(1)
-  expect(response.data.deleted[0].id).toBe(existing.id)
-})
-```
-
----
-
-## File Uploads
-
-Use `FormData` with `Buffer.from()` for file upload testing:
-
-```typescript
-import FormData from "form-data"
-
-it("should upload a file", async () => {
-  const form = new FormData()
-  form.append(
-    "files",
-    Buffer.from("file-content"),
-    { filename: "report.pdf" }
-  )
-
-  const response = await api.post(
-    "/admin/uploads",
-    form,
-    {
-      ...adminHeaders,
-      headers: {
-        ...adminHeaders.headers,
-        ...form.getHeaders(),
-      },
-    }
-  )
-  expect(response.status).toEqual(200)
-  expect(response.data.files).toHaveLength(1)
-  expect(response.data.files[0]).toEqual(
-    expect.objectContaining({
-      id: expect.any(String),
-      url: expect.any(String),
-    })
-  )
-})
-```
-
----
-
-## Link / Relation Testing
-
-Test cross-module links with `remoteLink` and `query.graph()`:
-
-```typescript
-import { ContainerRegistrationKeys, Modules } from "@acmekit/framework/utils"
-
-it("should create and query a link", async () => {
-  const container = getContainer()
-  const remoteLink = container.resolve(ContainerRegistrationKeys.LINK)
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
-
-  // Create linked entities
-  const post = (
-    await api.post("/admin/posts", { title: "Linked Post" }, adminHeaders)
-  ).data.post
-  const category = (
-    await api.post(
-      "/admin/categories",
-      { name: "Tech" },
-      adminHeaders
-    )
-  ).data.category
-
-  // Create the link
-  await remoteLink.create([{
-    [Modules.POST]: { post_id: post.id },
-    [Modules.CATEGORY]: { category_id: category.id },
-  }])
-
-  // Query with graph
-  const { data: [linkedPost] } = await query.graph({
-    entity: "post",
-    fields: ["id", "title", "category.*"],
-    filters: { id: post.id },
-  })
-
-  expect(linkedPost.category.name).toBe("Tech")
-})
-```
+await api.post("/admin/posts", { title: "Test" }, adminHeaders)
 
----
+// WRONG — vague range hides which error actually occurred
+expect(response.status).toBeGreaterThanOrEqual(400)  // ❌
+// RIGHT
+expect(response.status).toEqual(400)
 
-## Sorting / Ordering Verification
+// WRONG — resolve path as relative from test file
+integrationTestRunner({ mode: "module", moduleName: "post", resolve: "../index" })  // ❌
+// RIGHT — absolute path from CWD
+integrationTestRunner({ mode: "module", moduleName: "post", resolve: process.cwd() + "/src/modules/post" })
 
-```typescript
-it("should sort by name ascending", async () => {
-  await api.post("/admin/posts", { title: "Zeta" }, adminHeaders)
-  await api.post("/admin/posts", { title: "Alpha" }, adminHeaders)
-  await api.post("/admin/posts", { title: "Mu" }, adminHeaders)
-
-  const response = await api.get(
-    "/admin/posts?order=title",
-    adminHeaders
-  )
-  const titles = response.data.posts.map((p) => p.title)
-  expect(titles).toEqual(["Alpha", "Mu", "Zeta"])
-})
+// WRONG — guessing service resolution key
+getContainer().resolve("myModuleService")  // ❌
+getContainer().resolve("my-module-service")  // ❌
+// RIGHT
+import { MY_MODULE } from "../../src/modules/my-module"
+getContainer().resolve(MY_MODULE)
 
-it("should sort by created_at descending", async () => {
-  const response = await api.get(
-    "/admin/posts?order=-created_at",
-    adminHeaders
-  )
-  const dates = response.data.posts.map((p) => new Date(p.created_at))
-  for (let i = 1; i < dates.length; i++) {
-    expect(dates[i - 1].getTime()).toBeGreaterThanOrEqual(dates[i].getTime())
-  }
-})
-```
+// WRONG — using jsonwebtoken directly
+import jwt from "jsonwebtoken"
+const token = jwt.sign({ user_id: user.id }, "supersecret")  // ❌
+// RIGHT — use generateJwtToken with config-resolved secret
 
----
+// WRONG — using old publishable API key names
+await apiKeyModule.createApiKeys({ type: "publishable" })  // ❌
+headers: { "x-publishable-api-key": token }  // ❌
+// RIGHT
+await apiKeyModule.createApiKeys({ type: ApiKeyType.CLIENT })
+headers: { [CLIENT_API_KEY_HEADER]: token }
 
-## Complex Seeding in beforeEach
+// WRONG — unused imports
+import { ContainerRegistrationKeys } from "@acmekit/framework/utils"  // ❌ if never used
 
-When tests need multiple related entities, seed them in `beforeEach` using admin API calls:
+// WRONG — JSDoc comment blocks at file top (test files never have these)
+/** POST /admin/posts — validates body */  // ❌
 
-```typescript
-let order: any
-let product: any
-let customer: any
-
-beforeEach(async () => {
-  await createAdminUser(dbConnection, adminHeaders, getContainer())
-
-  // Seed product
-  product = (
-    await api.post(
-      "/admin/products",
-      { title: "Widget", status: "published" },
-      adminHeaders
-    )
-  ).data.product
-
-  // Seed customer via admin
-  customer = (
-    await api.post(
-      "/admin/customers",
-      { email: "test@example.com", first_name: "Jane" },
-      adminHeaders
-    )
-  ).data.customer
-
-  // Seed order linking both
-  order = (
-    await api.post(
-      "/admin/orders",
-      {
-        customer_id: customer.id,
-        items: [{ product_id: product.id, quantity: 2 }],
-      },
-      adminHeaders
-    )
-  ).data.order
-})
+// WRONG — type casts in tests
+const filtered = (operations as Array<{ status: string }>).filter(...)  // ❌
 ```
-
----
-
-## Multi-Step Flow Testing
-
-Chain multiple API calls in one test to verify end-to-end flows:
-
-```typescript
-it("should complete the full order lifecycle", async () => {
-  // 1. Create draft order
-  const created = (
-    await api.post(
-      "/admin/orders",
-      { customer_id: customer.id, items: [{ product_id: product.id, quantity: 1 }] },
-      adminHeaders
-    )
-  ).data.order
-  expect(created.status).toBe("draft")
-
-  // 2. Confirm order
-  const confirmed = (
-    await api.post(
-      `/admin/orders/${created.id}/confirm`,
-      {},
-      adminHeaders
-    )
-  ).data.order
-  expect(confirmed.status).toBe("confirmed")
-
-  // 3. Fulfill order
-  const fulfilled = (
-    await api.post(
-      `/admin/orders/${created.id}/fulfill`,
-      { tracking_number: "TRACK-123" },
-      adminHeaders
-    )
-  ).data.order
-  expect(fulfilled.status).toBe("fulfilled")
-
-  // 4. Verify final state with relations
-  const final = (
-    await api.get(
-      `/admin/orders/${created.id}?fields=*fulfillments`,
-      adminHeaders
-    )
-  ).data.order
-  expect(final.fulfillments).toHaveLength(1)
-  expect(final.fulfillments[0].tracking_number).toBe("TRACK-123")
-})