@acmekit/acmekit 2.13.83 → 2.13.85

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

@@ -10,39 +10,58 @@ 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.
 
+**jest.mock factories are hoisted.** `jest.mock()` runs BEFORE `const`/`let` declarations. Never reference file-level variables inside a `jest.mock()` factory — see "Unit Tests" section below.
+
+**Always add `jest.clearAllMocks()` in `beforeEach`.** Mock state leaks between test blocks. Without explicit cleanup, assertions on mock call counts fail from prior-test contamination.
+
+**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 +69,254 @@ 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,
+        })
+      })
+    })
+
+    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)
+      })
 
-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(),
+      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`: **automatically calls `waitWorkflowExecutions()`** from the previous test, then truncates all tables, re-runs module loaders, runs `createDefaultsWorkflow` (first test skips reset — state is already fresh after setup)
+- `afterAll`: drops DB, shuts down Express
+
+**IMPORTANT:** The runner calls `waitWorkflowExecutions()` automatically during the reset phase (before each subsequent test). 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 +339,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 +367,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 +380,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
+## 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`.
+**MANDATORY for `/admin/*` routes** — every HTTP test MUST have a `beforeEach` that creates admin credentials. Without it, admin routes return 401.
 
-```typescript
-import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
-```
-
-`adminHeaders` starts as `{ headers: { "x-acmekit-access-token": "test_token" } }`. After `createAdminUser` runs, it also has `authorization: Bearer <jwt>`.
-
-`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 +424,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,7 +453,7 @@ const apiKeyModule = container.resolve(Modules.API_KEY)
 const apiKey = await apiKeyModule.createApiKeys({
   title: "Test Client Key",
   type: ApiKeyType.CLIENT,
-  created_by: "system",
+  created_by: "test",
 })
 
 const clientHeaders = {
@@ -299,485 +461,490 @@ const clientHeaders = {
 }
 ```
 
-### Service Resolution
+---
 
-**ALWAYS use `Modules.*` constants** to resolve core services. NEVER use string literals like `"auth"`, `"user"`, `"customer"`.
+## Error Handling in HTTP Tests
 
 ```typescript
-// RIGHT
-const authModule = container.resolve(Modules.AUTH)
-const userModule = container.resolve(Modules.USER)
-const apiKeyModule = container.resolve(Modules.API_KEY)
+// 400 — validation error (axios throws on non-2xx)
+const { response } = await api
+  .post("/admin/posts", {}, adminHeaders)
+  .catch((e: any) => e)
+expect(response.status).toEqual(400)
+
+// 404 — not found (also check type and message)
+const { response } = await api
+  .get("/admin/posts/invalid-id", adminHeaders)
+  .catch((e: any) => e)
+expect(response.status).toEqual(404)
+expect(response.data.type).toEqual("not_found")
 
-// WRONG — string literals are fragile and may not match container keys
-const authModule = container.resolve("auth")        // ❌
-const userModule = container.resolve("user")        // ❌
+// 401 — unauthorized
+const error = await api.get("/admin/posts").catch((e: any) => e)
+expect(error.response.status).toEqual(401)
 ```
 
-### Admin Route Tests (`/admin/*`)
+---
 
-**MANDATORY:** Every `/admin/*` route test MUST have `beforeEach` with `createAdminUser`. Without it, admin routes return 401.
+## Response Shape Reference
 
 ```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
-import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
+// Single resource — nested under singular key
+expect(response.data.post).toEqual(
+  expect.objectContaining({
+    id: expect.any(String),
+    title: "Launch Announcement",
+    created_at: expect.any(String),
+    updated_at: expect.any(String),
+  })
+)
 
-jest.setTimeout(50000)
+// List resource — nested under plural key with pagination
+expect(response.data).toEqual(
+  expect.objectContaining({
+    posts: expect.arrayContaining([
+      expect.objectContaining({ title: "Post A" }),
+    ]),
+  })
+)
 
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    let user: any
+// Delete response — exact match
+expect(response.data).toEqual({
+  id: created.id,
+  object: "post",
+  deleted: true,
+})
+```
 
-    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: [],
-        })
-      })
-    })
+## Asserting Domain Events
 
-    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),
-          })
-        )
-      })
+Both runners inject `MockEventBusService` under `Modules.EVENT_BUS` in module mode. Spy on the **prototype**, not an instance.
 
-      it("should reject invalid body with 400", async () => {
-        const { response } = await api
-          .post("/admin/posts", {}, adminHeaders)
-          .catch((e) => e)
-        expect(response.status).toEqual(400)
-      })
+```typescript
+import { MockEventBusService } from "@acmekit/test-utils"
 
-      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)
-      })
-    })
+let eventBusSpy: jest.SpyInstance
 
-    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
+beforeEach(() => {
+  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
+})
 
-        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,
-        })
-      })
+afterEach(() => {
+  eventBusSpy.mockClear()
+})
 
-      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")
-      })
-    })
-  },
+it("should emit post.created event", async () => {
+  await service.createPosts([{ title: "Event Test" }])
+
+  const events = eventBusSpy.mock.calls[0][0]
+  expect(events).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        name: "post.created",
+        data: expect.objectContaining({ id: expect.any(String) }),
+      }),
+    ])
+  )
 })
 ```
 
-### Client Route Tests (`/client/*`)
+---
 
-**MANDATORY:** Every `/client/*` route test MUST have this `beforeEach` setup. Without `clientHeaders`, client route requests return 400 (`NOT_ALLOWED`).
+## Waiting for Subscribers
 
-```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
-import {
-  adminHeaders,
-  createAdminUser,
-  generateClientKey,
-  generateClientHeaders,
-} from "../../helpers/create-admin-user"
+Use `TestEventUtils.waitSubscribersExecution` when testing subscriber side-effects. **CRITICAL: create the promise BEFORE triggering the event.**
 
-jest.setTimeout(50000)
+### Pattern 1: Event bus driven (app mode with real event bus)
 
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    let clientHeaders: Record<string, any>
+```typescript
+import { integrationTestRunner, TestEventUtils } from "@acmekit/test-utils"
+import { Modules } from "@acmekit/framework/utils"
+import { BLOG_MODULE } from "../../src/modules/blog"
 
-    beforeEach(async () => {
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should execute subscriber side-effect", async () => {
       const container = getContainer()
-      await createAdminUser(dbConnection, adminHeaders, container)
+      const service: any = container.resolve(BLOG_MODULE)
+      const eventBus = container.resolve(Modules.EVENT_BUS)
 
-      const clientKey = await generateClientKey(container)
-      clientHeaders = generateClientHeaders({ publishableKey: clientKey })
+      const [blog] = await service.createBlogs([
+        { title: "Test", content: "Original", status: "published" },
+      ])
 
-      // Seed test data via admin API if needed
-      await api.post("/admin/products", { title: "Widget" }, adminHeaders)
-    })
+      // 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
 
-    it("should list products", async () => {
-      const response = await api.get("/client/products", clientHeaders)
-      expect(response.status).toEqual(200)
-      expect(response.data.products).toHaveLength(1)
+      // Verify subscriber side-effect
+      const updated = await service.retrieveBlog(blog.id)
+      expect(updated.content).toBe("Original [notified]")
     })
   },
 })
 ```
 
-If the public route needs no client key (rare), you can skip `generateClientKey`/`generateClientHeaders` — but most tests need them.
+---
+
+## Testing Jobs
 
-### Feature flags via `env` option
+Import the job function directly and call it with the container:
 
 ```typescript
-acmekitIntegrationTestRunner({
-  env: { ACMEKIT_FF_RBAC: true },
-  testSuite: ({ api, getContainer, dbConnection }) => { ... },
-})
-```
+import { integrationTestRunner } from "@acmekit/test-utils"
+import archiveOldBlogsJob from "../../src/jobs/archive-old-blogs"
+import { BLOG_MODULE } from "../../src/modules/blog"
 
----
+jest.setTimeout(60 * 1000)
 
-## Error Handling in HTTP Tests
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should soft-delete archived blogs", async () => {
+      const container = getContainer()
+      const service: any = container.resolve(BLOG_MODULE)
 
-```typescript
-// Error case — destructure response from caught error
-const { response } = await api
-  .post("/admin/posts", {}, adminHeaders)
-  .catch((e) => e)
-expect(response.status).toEqual(400)
-expect(response.data.message).toContain("is required")
+      await service.createBlogs([
+        { title: "Archived 1", status: "archived" },
+        { title: "Active", status: "published" },
+      ])
 
-// 404 case — also check type field
-const { response } = await api
-  .get("/admin/posts/invalid-id", adminHeaders)
-  .catch((e) => 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")
+      await archiveOldBlogsJob(container)
 
-// Alternative: capture full error for .message check (Axios error message)
-const error = await api
-  .post("/admin/posts", {}, { headers: {} })
-  .catch((e) => e)
-expect(error.response.status).toEqual(401)
+      const remaining = await service.listBlogs()
+      expect(remaining).toHaveLength(1)
+      expect(remaining[0].title).toBe("Active")
+    })
+  },
+})
 ```
 
 ---
 
-## Response Shape Reference
+## Workflow Testing
+
+### Direct execution (no HTTP)
 
 ```typescript
-// Single resource — nested under singular key
-expect(response.data.post).toEqual(
-  expect.objectContaining({
-    id: expect.any(String),
-    title: "Launch Announcement",
-    created_at: expect.any(String),
-    updated_at: expect.any(String),
-  })
-)
+import { createPostWorkflow } from "../../src/workflows/workflows"
 
-// 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" }),
-  ]),
-})
+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",
+        })
+      )
+    })
 
-// Delete response — exact match, no objectContaining
-expect(response.data).toEqual({
-  id: created.id,
-  object: "post",
-  deleted: true,
+    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")
+    })
+
+    // 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"),
+        })
+      )
+    })
+  },
 })
+```
 
-// Nested relations
-expect(response.data.post).toEqual(
-  expect.objectContaining({
-    comments: expect.arrayContaining([
-      expect.objectContaining({ body: "Great post" }),
-    ]),
-  })
-)
+### Via HTTP (when route triggers the workflow)
 
-// Negative assertion — item NOT in list
-expect(response.data.posts).toEqual(
-  expect.not.arrayContaining([
-    expect.objectContaining({ status: "archived" }),
-  ])
-)
+```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")
+})
 ```
 
 ---
 
-## Query Parameter Testing
+## Service Resolution
 
 ```typescript
-// Field selection — `*` prefix expands relations
-api.get(`/admin/posts/${id}?fields=*comments`, adminHeaders)
+// Custom modules — use module constant (matches the string passed to Module())
+import { BLOG_MODULE } from "../../src/modules/blog"  // BLOG_MODULE = "blog"
+const service = getContainer().resolve(BLOG_MODULE)
 
-// Pagination
-api.get("/admin/posts?limit=2&offset=1", adminHeaders)
+// Core modules — use Modules.* constants
+const userModule = getContainer().resolve(Modules.USER)
+const authModule = getContainer().resolve(Modules.AUTH)
 
-// Ordering — `-` prefix for descending
-api.get("/admin/posts?order=-created_at", adminHeaders)
+// Framework services
+const query = getContainer().resolve(ContainerRegistrationKeys.QUERY)
 
-// Free-text search
-api.get("/admin/posts?q=quarterly", adminHeaders)
+// WRONG — string literals are fragile
+getContainer().resolve("auth")            // ❌
+getContainer().resolve("blogModuleService")  // ❌
+```
 
-// 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)
+## Environment
 
-// With deleted
-api.get(`/admin/posts?with_deleted=true`, adminHeaders)
-```
+- `jest.config.js` loads `.env.test` via `@acmekit/utils` `loadEnv("test", process.cwd())`
+- `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>`
 
 ---
 
-## Asserting Domain Events
+## Unit Tests (No Framework Bootstrap)
 
-Both runners inject `MockEventBusService` under `Modules.EVENT_BUS`. Spy on the **prototype**, not an instance.
+For providers, utility functions, and standalone classes that don't need the database or AcmeKit container. Uses plain Jest — no `integrationTestRunner`.
 
-```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
+**File naming:** `src/**/__tests__/<name>.unit.spec.ts` — matches `TEST_TYPE=unit` in `jest.config.js`.
 
-let eventBusSpy: jest.SpyInstance
+### jest.mock Hoisting (Temporal Dead Zone)
 
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
+`jest.mock()` factories are **hoisted above all `const`/`let` declarations** by SWC/Babel. Referencing a file-level `const` inside a `jest.mock()` factory causes `ReferenceError: Cannot access before initialization`.
 
-afterEach(() => {
-  eventBusSpy.mockClear()
+```typescript
+// WRONG — TDZ error: mockSign is not yet initialized when factory runs
+const mockSign = jest.fn()
+jest.mock("tronweb", () => ({
+  TronWeb: jest.fn().mockImplementation(() => ({ trx: { sign: mockSign } })),
+}))
+
+// RIGHT — create mocks INSIDE the factory, expose via module return
+jest.mock("tronweb", () => {
+  const mocks = {
+    sign: jest.fn(),
+    isAddress: jest.fn().mockReturnValue(true),
+  }
+  const MockTronWeb = jest.fn().mockImplementation(() => ({
+    trx: { sign: mocks.sign },
+  }))
+  MockTronWeb.isAddress = mocks.isAddress
+  return { TronWeb: MockTronWeb, __mocks: mocks }
 })
 
-it("should emit post.created event", async () => {
-  await service.createPosts([{ title: "Event Test" }])
+// Access mocks after jest.mock via require()
+const { __mocks: tronMocks } = require("tronweb")
+```
 
-  // 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)
-  expect(events).toEqual(
-    expect.arrayContaining([
-      expect.objectContaining({
-        name: "post.created",
-        data: expect.objectContaining({ id: expect.any(String) }),
-      }),
-    ])
-  )
+**Rule:** All mock state must live INSIDE the `jest.mock()` factory or be accessed via `require()` after the mock is set up. Never reference file-level `const`/`let` from inside a `jest.mock()` factory.
+
+### Provider Unit Test Pattern
+
+Providers have a specific structure: constructor receives `(container, options)`, static `identifier`, optional static `validateOptions`. Test each part:
 
-  // Second argument is always { internal: true }
-  expect(eventBusSpy.mock.calls[0][1]).toEqual({ internal: true })
+```typescript
+jest.mock("external-sdk", () => {
+  const mocks = {
+    doThing: jest.fn(),
+  }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
 })
-```
 
----
+const { __mocks: sdkMocks } = require("external-sdk")
 
-## Waiting for Async Workflows
+import MyProvider from "../my-provider"
 
-The runner calls `waitWorkflowExecutions()` automatically in `afterEach`. Only call it explicitly when you need workflow results **between** two API calls in the same test:
+describe("MyProvider", () => {
+  let provider: MyProvider
 
-```typescript
-it("should process order via workflow", async () => {
-  await api.post("/admin/orders", { items: [...] }, adminHeaders)
+  const mockContainer = {} as any
+  const defaultOptions = { apiKey: "test-key" }
 
-  // ONLY needed because the next request depends on workflow completion
-  await utils.waitWorkflowExecutions()
+  beforeEach(() => {
+    jest.clearAllMocks()
+    provider = new MyProvider(mockContainer, defaultOptions)
+  })
 
-  const response = await api.get("/admin/orders", adminHeaders)
-  expect(response.data.orders[0].status).toBe("processed")
+  describe("static identifier", () => {
+    it("should have correct identifier", () => {
+      expect(MyProvider.identifier).toBe("my-provider")
+    })
+  })
+
+  describe("validateOptions", () => {
+    it("should accept valid options", () => {
+      expect(() =>
+        MyProvider.validateOptions({ apiKey: "key" })
+      ).not.toThrow()
+    })
+
+    it("should reject missing required option", () => {
+      expect(() => MyProvider.validateOptions({})).toThrow()
+    })
+  })
+
+  describe("doSomething", () => {
+    it("should delegate to SDK", async () => {
+      sdkMocks.doThing.mockResolvedValue({ success: true })
+      const result = await provider.doSomething({ input: "test" })
+      expect(result.success).toBe(true)
+      expect(sdkMocks.doThing).toHaveBeenCalledWith(
+        expect.objectContaining({ input: "test" })
+      )
+    })
+  })
 })
 ```
 
----
+### Mock Cleanup Between Tests
 
-## Waiting for Subscribers
+Mock state leaks between `describe` and `it` blocks. **Always add cleanup:**
 
-Use `TestEventUtils.waitSubscribersExecution` when testing subscriber side-effects. **CRITICAL: create the promise BEFORE triggering the event.**
+```typescript
+// Recommended: file-level cleanup
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+// Alternative: per-describe when different describes need different setups
+describe("feature A", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockFn.mockResolvedValue("A result")
+  })
+})
+```
+
+Without `jest.clearAllMocks()`, a mock called in one test still shows those calls in the next test:
 
 ```typescript
-import { TestEventUtils } from "@acmekit/test-utils"
+expect(mockSign).not.toHaveBeenCalled()  // FAILS — called by prior test
+```
 
-it("should handle the event", async () => {
-  const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+### Testing Code with Timers
 
-  // 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
+When code under test calls `setTimeout`, `setInterval`, or a `sleep()` function, tests time out or run slowly.
+
+```typescript
+// Option 1: Fake timers (for setTimeout/setInterval)
+beforeEach(() => {
+  jest.useFakeTimers()
+})
+afterEach(() => {
+  jest.useRealTimers()
+})
+it("should retry after delay", async () => {
+  const promise = provider.retryOperation()
+  await jest.advanceTimersByTimeAsync(3000)
+  const result = await promise
+  expect(result).toBeDefined()
+})
+
+// Option 2: Mock the sleep method (for custom sleep/delay functions)
+it("should complete without waiting", async () => {
+  jest.spyOn(provider as any, "sleep_").mockResolvedValue(undefined)
+  const result = await provider.longRunningOperation()
+  expect(result).toBeDefined()
 })
 ```
 
----
+### SWC Regex Limitation
 
-## Resolving Services in Tests
+SWC's regex parser fails on certain complex regex literals. If you get a `Syntax Error` from SWC on a line with a regex:
 
 ```typescript
-// In acmekitIntegrationTestRunner — use module constant (matches Module() key)
-import { BLOG_MODULE } from "../../src/modules/blog"  // BLOG_MODULE = "blog"
-const blogService = getContainer().resolve(BLOG_MODULE)
-const query = getContainer().resolve(ContainerRegistrationKeys.QUERY)
+// WRONG — SWC may fail to parse this
+const pattern = /^(\*|[0-9]+)(\/[0-9]+)?$|^\*\/[0-9]+$/
 
-// Core modules — use Modules.* constants
-const userModule = getContainer().resolve(Modules.USER)
-const authModule = getContainer().resolve(Modules.AUTH)
+// RIGHT — use RegExp constructor
+const pattern = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$|^\\*\\/[0-9]+$")
+```
 
-// Resolve in beforeAll for reuse (container proxy stays current)
-let container: AcmeKitContainer
-beforeAll(() => {
-  container = getContainer()
-})
+### Verifying Error Paths
 
-// In moduleIntegrationTestRunner — use the `service` fixture directly
-const result = await service.listPosts()
+When testing error cases, **read the implementation** to determine whether the method throws or returns an error object. Don't assume from the return type alone.
 
-// NEVER guess the key — "blogModuleService", "postModuleService" are all WRONG
-// The key is EXACTLY the string passed to Module() in your module definition
-```
+```typescript
+// If the method catches errors and returns { success: false }:
+const result = await provider.process(badInput)
+expect(result.success).toBe(false)
 
----
+// If the method throws (no internal try/catch on that path):
+await expect(provider.process(badInput)).rejects.toThrow("invalid")
 
-## Environment
+// If validation runs BEFORE a try/catch block:
+// validateInput() throws → not caught by the try/catch in process()
+await expect(provider.process(badInput)).rejects.toThrow("validation")
+```
 
-- `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)
-- 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>`
+**Tip:** Look for `try/catch` blocks in the implementation. Code that runs BEFORE or OUTSIDE a `try/catch` throws directly. Code INSIDE a `try/catch` may return an error result instead.
 
 ---
 
 ## 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 +954,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 +982,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 +991,81 @@ 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" }
-  )
+await api.post("/admin/posts", { title: "Test" }, adminHeaders)
 
-  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),
-    })
-  )
-})
-```
+// WRONG — vague range hides which error actually occurred
+expect(response.status).toBeGreaterThanOrEqual(400)  // ❌
+// RIGHT
+expect(response.status).toEqual(400)
 
----
+// 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" })
 
-## Link / Relation Testing
+// 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)
 
-Test cross-module links with `remoteLink` and `query.graph()`:
+// WRONG — using jsonwebtoken directly
+import jwt from "jsonwebtoken"
+const token = jwt.sign({ user_id: user.id }, "supersecret")  // ❌
+// RIGHT — use generateJwtToken with config-resolved secret
 
-```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 },
-  })
+// 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 }
 
-  expect(linkedPost.category.name).toBe("Tech")
-})
-```
+// WRONG — unused imports
+import { ContainerRegistrationKeys } from "@acmekit/framework/utils"  // ❌ if never used
 
----
+// WRONG — JSDoc comment blocks at file top (test files never have these)
+/** POST /admin/posts — validates body */  // ❌
 
-## Sorting / Ordering Verification
+// WRONG — type casts in tests
+const filtered = (operations as Array<{ status: string }>).filter(...)  // ❌
 
-```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 — referencing file-level const/let inside jest.mock factory (TDZ)
+const mockFn = jest.fn()
+jest.mock("lib", () => ({ thing: mockFn }))  // ❌ ReferenceError
+// RIGHT — create mocks inside factory, access via require()
+jest.mock("lib", () => {
+  const mocks = { thing: jest.fn() }
+  return { ...mocks, __mocks: mocks }
 })
-
-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())
-  }
+const { __mocks } = require("lib")
+
+// WRONG — no mock cleanup between tests
+describe("A", () => { it("calls mock", () => { mockFn() }) })
+describe("B", () => { it("mock is clean", () => {
+  expect(mockFn).not.toHaveBeenCalled()  // ❌ fails — leaked from A
+}) })
+// RIGHT — add beforeEach(() => jest.clearAllMocks())
+
+// WRONG — real timers in unit tests cause timeouts
+it("should process", async () => {
+  await relay.process(data)  // ❌ hangs — code calls sleep(3000) internally
 })
-```
-
----
-
-## Complex Seeding in beforeEach
+// RIGHT — mock timers or sleep method
+jest.useFakeTimers()
+// or: jest.spyOn(relay as any, "sleep_").mockResolvedValue(undefined)
 
-When tests need multiple related entities, seed them in `beforeEach` using admin API calls:
+// WRONG — complex regex literal that SWC can't parse
+const re = /^(\*|[0-9]+)(\/[0-9]+)?$/  // ❌ SWC Syntax Error
+// RIGHT
+const re = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$")
 
-```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 — assuming method returns error without reading implementation
+const result = await provider.process(bad)
+expect(result.success).toBe(false)  // ❌ actually throws
+// RIGHT — read implementation first to check if it throws or returns
 ```
-
----
-
-## 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")
-})