@acmekit/acmekit 2.13.83 → 2.13.85

package/dist/templates/app/.claude/agents/test-writer.md

@@ -1,182 +1,113 @@
 ---
 name: test-writer
-description: Generates comprehensive integration tests for AcmeKit modules, workflows, and API routes. Auto-detects the correct test runner (acmekitIntegrationTestRunner for HTTP, moduleIntegrationTestRunner for modules). Use proactively after implementing a feature to add test coverage.
+description: Generates comprehensive integration tests for AcmeKit modules, workflows, subscribers, jobs, and API routes. Auto-detects the correct mode (app for HTTP/container, module for isolated services). Use proactively after implementing a feature to add test coverage.
 tools: Read, Write, Edit, Glob, Grep
 model: sonnet
 maxTurns: 20
 ---
 
-You are an AcmeKit test engineer. Generate comprehensive integration tests using the correct test runner and patterns.
+You are an AcmeKit test engineer. Generate comprehensive integration tests using the unified `integrationTestRunner` with the correct mode and patterns.
 
 **BEFORE writing any test:**
-1. Read `.claude/rules/testing.md` — it contains anti-patterns and response shapes you MUST follow
+1. Read `.claude/rules/testing.md` — it contains anti-patterns, fixtures, lifecycle, and error handling rules you MUST follow
 2. Read the source code you're testing — understand service methods, route paths, validators, and response shapes
-3. Identify whether this is a module test or HTTP test
+3. Identify the correct test tier (HTTP, app, module, or unit)
 
 ---
 
-## Test Runner Selection
+## Test Runner — `integrationTestRunner` (unified)
 
-| What to test | Runner | Test location |
-|---|---|---|
-| API routes (HTTP end-to-end) | `acmekitIntegrationTestRunner` | `integration-tests/http/<feature>.spec.ts` |
-| Module service CRUD (no HTTP) | `moduleIntegrationTestRunner` | `src/modules/<mod>/__tests__/<name>.spec.ts` |
-| Pure functions (no DB) | Plain Jest `describe/it` | `src/**/__tests__/<name>.unit.spec.ts` |
-
-**Decision rule:** If the code under test is an API route → `acmekitIntegrationTestRunner`. If it's a module service method → `moduleIntegrationTestRunner`.
-
----
-
-## Module Integration Test Template
+**NEVER use `acmekitIntegrationTestRunner` or `moduleIntegrationTestRunner` — those are deprecated.**
 
 ```typescript
-import { moduleIntegrationTestRunner, MockEventBusService } from "@acmekit/test-utils"
-import { Modules } from "@acmekit/framework/utils"
-
-jest.setTimeout(30000)
+import { integrationTestRunner } from "@acmekit/test-utils"
+```
 
-moduleIntegrationTestRunner<IMyModuleService>({
-  moduleName: Modules.MY_MODULE,
-  resolve: "./src/modules/my-module",
-  injectedDependencies: {
-    [Modules.EVENT_BUS]: new MockEventBusService(),
-  },
-  testSuite: ({ service }) => {
-    afterEach(() => {
-      jest.restoreAllMocks()
-    })
+| What to test | Mode | File location |
+|---|---|---|
+| API routes (HTTP end-to-end) | `mode: "app"` | `integration-tests/http/<feature>.spec.ts` |
+| Workflows, subscribers, jobs (container) | `mode: "app"` | `integration-tests/app/<feature>.spec.ts` |
+| Module service CRUD (isolated) | `mode: "module"` | `src/modules/<mod>/__tests__/<name>.spec.ts` |
+| Pure functions (no DB) | Plain Jest | `src/**/__tests__/<name>.unit.spec.ts` |
 
-    describe("createMyEntities", () => {
-      it("should create an entity", async () => {
-        const result = await service.createMyEntities([
-          { title: "Quarterly Report" },
-        ])
-        expect(result).toHaveLength(1)
-        expect(result[0]).toEqual(
-          expect.objectContaining({
-            id: expect.any(String),
-            title: "Quarterly Report",
-          })
-        )
-      })
+---
 
-      it("should throw on missing required field", async () => {
-        await expect(service.createMyEntities([{}])).rejects.toThrow()
-      })
-    })
+## HTTP Integration Test Template
 
-    describe("listMyEntities", () => {
-      it("should list with filters", async () => {
-        await service.createMyEntities([
-          { title: "Post A", status: "active" },
-          { title: "Post B", status: "draft" },
-        ])
-        const filtered = await service.listMyEntities({ status: "active" })
-        expect(filtered).toHaveLength(1)
-        expect(filtered[0].title).toBe("Post A")
-      })
-
-      it("should list and count", async () => {
-        await service.createMyEntities([
-          { title: "Post A" },
-          { title: "Post B" },
-        ])
-        const [items, count] = await service.listAndCountMyEntities()
-        expect(count).toEqual(2)
-      })
-    })
+```typescript
+import { integrationTestRunner } from "@acmekit/test-utils"
+import {
+  ApiKeyType,
+  CLIENT_API_KEY_HEADER,
+  ContainerRegistrationKeys,
+  generateJwtToken,
+  Modules,
+} from "@acmekit/framework/utils"
+
+jest.setTimeout(60 * 1000)
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ api, getContainer }) => {
+    let adminHeaders: Record<string, any>
+    let clientHeaders: Record<string, any>
 
-    describe("retrieveMyEntity", () => {
-      it("should retrieve by id", async () => {
-        const [created] = await service.createMyEntities([
-          { title: "Retrieve Me" },
-        ])
-        const retrieved = await service.retrieveMyEntity(created.id)
-        expect(retrieved.title).toBe("Retrieve Me")
-      })
+    beforeEach(async () => {
+      const container = getContainer()
+      const userModule = container.resolve(Modules.USER)
+      const authModule = container.resolve(Modules.AUTH)
+      const apiKeyModule = container.resolve(Modules.API_KEY)
 
-      it("should throw when not found", async () => {
-        const error = await service
-          .retrieveMyEntity("nonexistent")
-          .catch((e) => e)
-        expect(error.message).toContain("not found")
+      // Create admin user
+      const user = await userModule.createUsers({
+        email: "admin@test.js",
       })
-    })
 
-    describe("updateMyEntities", () => {
-      it("should update and return updated entity", async () => {
-        const [created] = await service.createMyEntities([
-          { title: "Old Title" },
-        ])
-        const updated = await service.updateMyEntities(created.id, {
-          title: "New Title",
-        })
-        expect(updated.title).toBe("New Title")
+      // Create auth identity
+      const authIdentity = await authModule.createAuthIdentities({
+        provider_identities: [
+          { provider: "emailpass", entity_id: "admin@test.js" },
+        ],
+        app_metadata: { user_id: user.id },
       })
-    })
-
-    describe("softDeleteMyEntities / restoreMyEntities", () => {
-      it("should soft delete and restore", async () => {
-        const [created] = await service.createMyEntities([
-          { title: "To Delete" },
-        ])
-        await service.softDeleteMyEntities([created.id])
 
-        const listed = await service.listMyEntities({ id: created.id })
-        expect(listed).toHaveLength(0)
+      // 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 }
+      )
 
-        await service.restoreMyEntities([created.id])
+      adminHeaders = {
+        headers: { authorization: `Bearer ${token}` },
+      }
 
-        const restored = await service.listMyEntities({ id: created.id })
-        expect(restored).toHaveLength(1)
+      // Create client API key
+      const apiKey = await apiKeyModule.createApiKeys({
+        title: "Test Client Key",
+        type: ApiKeyType.CLIENT,
+        created_by: "test",
       })
-    })
-  },
-})
-```
-
-**Lifecycle:** Each `it` gets schema drop + recreate → fresh module boot. No manual cleanup needed.
-
----
-
-## HTTP Admin Route Test Template
-
-```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
-import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
 
-jest.setTimeout(50000)
-
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    beforeEach(async () => {
-      await createAdminUser(dbConnection, adminHeaders, getContainer())
+      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).toEqual({
-          count: 0,
-          limit: 20,
-          offset: 0,
-          posts: [],
-        })
-      })
-
-      it("should support field selection", async () => {
-        await api.post(
-          "/admin/posts",
-          { title: "Test" },
-          adminHeaders
-        )
-        const response = await api.get(
-          "/admin/posts?fields=id,title",
-          adminHeaders
-        )
-        expect(response.status).toEqual(200)
-        expect(response.data.posts).toHaveLength(1)
+        expect(response.data.posts).toBeDefined()
       })
     })
 
@@ -184,7 +115,7 @@ acmekitIntegrationTestRunner({
       it("should create a post", async () => {
         const response = await api.post(
           "/admin/posts",
-          { title: "Launch Announcement", body: "We are live." },
+          { title: "Launch Announcement" },
           adminHeaders
         )
         expect(response.status).toEqual(200)
@@ -199,18 +130,7 @@ acmekitIntegrationTestRunner({
       it("should reject missing required fields with 400", async () => {
         const { response } = await api
           .post("/admin/posts", {}, adminHeaders)
-          .catch((e) => e)
-        expect(response.status).toEqual(400)
-      })
-
-      it("should reject unknown fields with 400", async () => {
-        const { response } = await api
-          .post(
-            "/admin/posts",
-            { title: "Test", unknown_field: "bad" },
-            adminHeaders
-          )
-          .catch((e) => e)
+          .catch((e: any) => e)
         expect(response.status).toEqual(400)
       })
     })
@@ -236,13 +156,17 @@ acmekitIntegrationTestRunner({
           deleted: true,
         })
       })
+    })
 
-      it("should return 404 for non-existent id", 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")
+    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)
       })
     })
   },
@@ -251,51 +175,86 @@ acmekitIntegrationTestRunner({
 
 ---
 
-## HTTP Client Route Test Template
+## App Integration Test Template (workflows, subscribers, jobs)
 
-**MANDATORY: Every `/client/*` test MUST have this setup. Without it, requests return 400 (`NOT_ALLOWED`).**
+For tests that only need `getContainer()` — no auth setup, no HTTP assertions:
 
 ```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
-import {
-  adminHeaders,
-  createAdminUser,
-  generatePublishableKey,
-  generateClientHeaders,
-} from "../../helpers/create-admin-user"
+import { integrationTestRunner } from "@acmekit/test-utils"
+import { createPostsWorkflow } from "../../src/workflows/workflows"
+import { POST_MODULE } from "../../src/modules/post"
+
+jest.setTimeout(60 * 1000)
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    describe("createPostsWorkflow", () => {
+      it("should create posts with defaults", async () => {
+        const { result } = await createPostsWorkflow(getContainer()).run({
+          input: { posts: [{ title: "My First Post" }] },
+        })
 
-jest.setTimeout(50000)
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual(
+          expect.objectContaining({
+            id: expect.any(String),
+            title: "My First Post",
+          })
+        )
+      })
 
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    let clientHeaders: Record<string, any>
+      it("should reject invalid input via validation step", async () => {
+        const { errors } = await createPostsWorkflow(getContainer()).run({
+          input: { posts: [{ title: "", status: "bad" }] },
+          throwOnError: false,
+        })
 
-    beforeEach(async () => {
+        expect(errors).toHaveLength(1)
+        expect(errors[0].error.message).toContain("Invalid")
+      })
+    })
+  },
+})
+```
+
+---
+
+## Subscriber Test Template
+
+Uses `TestEventUtils.waitSubscribersExecution` with the real event bus. **CRITICAL: create the promise BEFORE emitting the event.**
+
+```typescript
+import { integrationTestRunner, TestEventUtils } from "@acmekit/test-utils"
+import { Modules } from "@acmekit/framework/utils"
+import { POST_MODULE } from "../../src/modules/post"
+
+jest.setTimeout(60 * 1000)
+
+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(POST_MODULE)
+      const eventBus = container.resolve(Modules.EVENT_BUS)
 
-      const publishableKey = await generatePublishableKey(container)
-      clientHeaders = generateClientHeaders({ publishableKey })
+      const [post] = await service.createPosts([
+        { title: "Test", content: "Original" },
+      ])
 
-      // Seed test data via admin API
-      await api.post(
-        "/admin/products",
-        { title: "Widget", status: "published" },
-        adminHeaders
+      // CRITICAL: create promise BEFORE emitting
+      const subscriberDone = TestEventUtils.waitSubscribersExecution(
+        "post.published",
+        eventBus
       )
-    })
 
-    it("should list products", async () => {
-      const response = await api.get("/client/products", clientHeaders)
-      expect(response.status).toEqual(200)
-      expect(response.data.products).toHaveLength(1)
-    })
+      // Emit event — single object { name, data } format (real event bus)
+      await eventBus.emit({ name: "post.published", data: { id: post.id } })
+      await subscriberDone
 
-    it("should reject requests without client API key", async () => {
-      const { response } = await api
-        .get("/client/products")
-        .catch((e) => e)
-      expect(response.status).toEqual(400)
+      const updated = await service.retrievePost(post.id)
+      expect(updated.content).toBe("Original [notified]")
     })
   },
 })
@@ -303,98 +262,119 @@ acmekitIntegrationTestRunner({
 
 ---
 
-## Error Testing Patterns
+## Job Test Template
+
+Import the job function directly and call with container:
 
 ```typescript
-// 400 — validation error
-const { response } = await api
-  .post("/admin/posts", {}, adminHeaders)
-  .catch((e) => 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) => e)
-expect(response.status).toEqual(404)
-expect(response.data.type).toEqual("not_found")
-expect(response.data.message).toContain("not found")
-
-// 401 — unauthorized
-const { response } = await api
-  .get("/admin/posts")
-  .catch((e) => e)
-expect(response.status).toEqual(401)
-```
+import { integrationTestRunner } from "@acmekit/test-utils"
+import archiveOldPostsJob from "../../src/jobs/archive-old-posts"
+import { POST_MODULE } from "../../src/modules/post"
 
----
+jest.setTimeout(60 * 1000)
 
-## Asserting Domain Events
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should soft-delete archived posts", async () => {
+      const container = getContainer()
+      const service: any = container.resolve(POST_MODULE)
 
-```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
+      await service.createPosts([
+        { title: "Archived Post", status: "archived" },
+        { title: "Active Post", status: "published" },
+      ])
 
-let eventBusSpy: jest.SpyInstance
+      await archiveOldPostsJob(container)
 
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
+      const remaining = await service.listPosts()
+      expect(remaining).toHaveLength(1)
+      expect(remaining[0].title).toBe("Active Post")
+    })
 
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
+    it("should handle empty set gracefully", async () => {
+      const container = getContainer()
+      const service: any = container.resolve(POST_MODULE)
 
-it("should emit post.created event", async () => {
-  await service.createMyEntities([{ title: "Event Test" }])
+      await service.createPosts([
+        { title: "Active", status: "published" },
+      ])
 
-  const events = eventBusSpy.mock.calls[0][0]
-  expect(events).toHaveLength(1)
-  expect(events).toEqual(
-    expect.arrayContaining([
-      expect.objectContaining({
-        name: "post.created",
-        data: expect.objectContaining({ id: expect.any(String) }),
-      }),
-    ])
-  )
+      await archiveOldPostsJob(container)
+
+      const remaining = await service.listPosts()
+      expect(remaining).toHaveLength(1)
+    })
+  },
 })
 ```
 
 ---
 
-## Workflow Testing (Direct Execution)
-
-Test workflows directly without HTTP when testing workflow logic in isolation:
+## Module Integration Test Template
 
 ```typescript
-import { createPostWorkflow } from "../../src/workflows"
-import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
+import { integrationTestRunner } from "@acmekit/test-utils"
 
-acmekitIntegrationTestRunner({
-  testSuite: ({ getContainer, dbConnection }) => {
-    beforeEach(async () => {
-      await createAdminUser(dbConnection, adminHeaders, getContainer())
+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([
+          { title: "Quarterly Report" },
+        ])
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual(
+          expect.objectContaining({
+            id: expect.any(String),
+            title: "Quarterly Report",
+          })
+        )
+      })
+
+      it("should throw on missing required field", async () => {
+        await expect(service.createPosts([{}])).rejects.toThrow()
+      })
     })
 
-    it("should execute the workflow", async () => {
-      const { result } = await createPostWorkflow(getContainer()).run({
-        input: { title: "Launch Announcement", author_id: "auth_123" },
+    describe("listPosts", () => {
+      it("should filter by field", async () => {
+        await service.createPosts([
+          { title: "Active", status: "published" },
+          { title: "Draft", status: "draft" },
+        ])
+        const published = await service.listPosts({ status: "published" })
+        expect(published).toHaveLength(1)
+        expect(published[0].title).toBe("Active")
+      })
+
+      it("should list and count", async () => {
+        await service.createPosts([{ title: "A" }, { title: "B" }])
+        const [items, count] = await service.listAndCountPosts()
+        expect(count).toEqual(2)
       })
-      expect(result.post).toEqual(
-        expect.objectContaining({
-          id: expect.any(String),
-          title: "Launch Announcement",
-        })
-      )
     })
 
-    it("should reject invalid input", async () => {
-      const { errors } = await createPostWorkflow(getContainer()).run({
-        input: {},
-        throwOnError: false,
+    describe("softDeletePosts / restorePosts", () => {
+      it("should soft delete and restore", async () => {
+        const [created] = await service.createPosts([
+          { title: "To Delete" },
+        ])
+        await service.softDeletePosts([created.id])
+
+        const listed = await service.listPosts({ id: created.id })
+        expect(listed).toHaveLength(0)
+
+        await service.restorePosts([created.id])
+
+        const restored = await service.listPosts({ id: created.id })
+        expect(restored).toHaveLength(1)
       })
-      expect(errors).toHaveLength(1)
-      expect(errors[0].error.message).toContain("title")
     })
   },
 })
@@ -402,95 +382,101 @@ acmekitIntegrationTestRunner({
 
 ---
 
-## Subscriber Testing
+## Unit Test Template (No Framework Bootstrap)
 
-Test subscriber side-effects using `TestEventUtils.waitSubscribersExecution`. **CRITICAL: create the promise BEFORE triggering the event.**
+For providers, utilities, and standalone classes. Uses plain Jest with `jest.mock`.
+
+**CRITICAL — jest.mock hoisting:** `jest.mock()` factories are hoisted above `const`/`let` by SWC. Never reference file-level variables inside a factory. Create mocks INSIDE the factory and access via `require()`.
 
 ```typescript
-import { TestEventUtils } from "@acmekit/test-utils"
-import { Modules } from "@acmekit/framework/utils"
+// Provider unit test pattern
+jest.mock("external-sdk", () => {
+  const mocks = {
+    doThing: jest.fn(),
+  }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
+})
 
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, dbConnection }) => {
-    beforeEach(async () => {
-      await createAdminUser(dbConnection, adminHeaders, getContainer())
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  let provider: MyProvider
+  const mockContainer = {} as any
+  const defaultOptions = { apiKey: "test-key" }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    provider = new MyProvider(mockContainer, defaultOptions)
+  })
+
+  describe("static identifier", () => {
+    it("should have correct identifier", () => {
+      expect(MyProvider.identifier).toBe("my-provider")
     })
+  })
 
-    it("should execute subscriber on post creation", async () => {
-      const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+  describe("validateOptions", () => {
+    it("should accept valid options", () => {
+      expect(() =>
+        MyProvider.validateOptions({ apiKey: "key" })
+      ).not.toThrow()
+    })
 
-      // Create promise BEFORE triggering event
-      const subscriberExecution = TestEventUtils.waitSubscribersExecution(
-        "post.created",
-        eventBus
-      )
-      await api.post("/admin/posts", { title: "Trigger" }, adminHeaders)
-      await subscriberExecution
-
-      // Assert subscriber side-effect (e.g., audit log created)
-      const response = await api.get("/admin/audit-logs", adminHeaders)
-      expect(response.data.audit_logs).toEqual(
-        expect.arrayContaining([
-          expect.objectContaining({ event: "post.created" }),
-        ])
-      )
+    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)
+    })
+  })
 })
 ```
 
----
+**Timer mocking:** If code under test uses `setTimeout` or `sleep()`, use `jest.useFakeTimers()` + `jest.advanceTimersByTimeAsync()` or mock the sleep method.
 
-## Batch Operation Testing
+**SWC regex:** Complex regex literals may fail. Use `new RegExp("...")` instead.
 
-```typescript
-it("should handle batch create/update/delete", async () => {
-  const existing = (
-    await api.post("/admin/posts", { title: "Existing" }, adminHeaders)
-  ).data.post
-
-  const response = await api.post(
-    "/admin/posts/batch",
-    {
-      create: [{ title: "New Post" }],
-      update: [{ id: existing.id, title: "Updated" }],
-      delete: [existing.id],
-    },
-    adminHeaders
-  )
-  expect(response.status).toEqual(200)
-  expect(response.data.created).toHaveLength(1)
-  expect(response.data.updated).toHaveLength(1)
-  expect(response.data.deleted).toHaveLength(1)
-})
-```
+**Error paths:** Read the implementation to check whether errors are thrown or returned. Don't assume from the return type.
 
 ---
 
-## Link / Relation Testing
+## Asserting Domain Events (module mode)
 
 ```typescript
-import { ContainerRegistrationKeys, Modules } from "@acmekit/framework/utils"
+import { MockEventBusService } from "@acmekit/test-utils"
 
-it("should create and query a cross-module link", async () => {
-  const container = getContainer()
-  const remoteLink = container.resolve(ContainerRegistrationKeys.LINK)
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+let eventBusSpy: jest.SpyInstance
 
-  const post = (await api.post("/admin/posts", { title: "Linked" }, adminHeaders)).data.post
-  const category = (await api.post("/admin/categories", { name: "Tech" }, adminHeaders)).data.category
+beforeEach(() => {
+  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
+})
+
+afterEach(() => {
+  eventBusSpy.mockClear()
+})
 
-  await remoteLink.create([{
-    [Modules.POST]: { post_id: post.id },
-    [Modules.CATEGORY]: { category_id: category.id },
-  }])
+it("should emit post.created event", async () => {
+  await service.createPosts([{ title: "Event Test" }])
 
-  const { data: [linkedPost] } = await query.graph({
-    entity: "post",
-    fields: ["id", "title", "category.*"],
-    filters: { id: post.id },
-  })
-  expect(linkedPost.category.name).toBe("Tech")
+  const events = eventBusSpy.mock.calls[0][0]
+  expect(events).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        name: "post.created",
+        data: expect.objectContaining({ id: expect.any(String) }),
+      }),
+    ])
+  )
 })
 ```
 
@@ -501,80 +487,74 @@ it("should create and query a cross-module link", async () => {
 **For module services:**
 - Create (single + batch), list (with filters), listAndCount, retrieve, update, softDelete/restore
 - Custom service methods
-- Validation (required fields → `rejects.toThrow()`, missing entity → check error.message)
+- Required field validation → `rejects.toThrow()`
+- Not found → `.catch((e: any) => e)` + `error.message` check
 - Edge cases (empty arrays, duplicate unique constraints)
-- Related entities (create parent → child, retrieve with `{ relations: [...] }`)
 
 **For HTTP routes:**
 - Success responses with correct shape (`expect.objectContaining`)
-- List responses with pagination shape (`{ count, limit, offset, <resources> }`)
-- Delete responses with `{ id, object, deleted: true }`
-- Validation errors (400 via `.catch((e) => e)`)
-- Not found (404 — also check `response.data.type` and `response.data.message`)
-- Auth required (401 for `/admin/*` without headers, 400 for `/client/*` without client API key)
-- `.strict()` rejecting unknown fields (400)
-- Query parameters (`?fields=`, `?limit=`, `?offset=`, `?order=`, `?q=`)
-- Sorting verification (`?order=title`, `?order=-created_at`)
-- Batch operations (`{ create, update, delete }` → `{ created, updated, deleted }`)
+- List responses with pagination shape
+- Delete responses with `{ id, object: "resource", deleted: true }`
+- Validation errors (400 via `.catch((e: any) => e)`)
+- Not found (404)
+- Auth required (401 for `/admin/*` without headers, 400 for `/client/*` without API key)
+- Query parameters (`?fields=`, `?limit=`, `?offset=`)
 
 **For workflows:**
-- Happy path + correct result via `workflow(container).run({ input })`
-- `throwOnError: false` + `errors` inspection for invalid input
-- `inputSchema` rejection messages
-- Long-running workflows: `subscribe` + `setStepSuccess` + completion promise
-- Workflow results available via HTTP after `waitWorkflowExecutions()`
+- Happy path + correct result via `workflow(getContainer()).run({ input })`
+- `throwOnError: false` + `errors[0].error.message` for invalid input
+- Step compensation on failure (verify side-effects rolled back)
 
 **For subscribers:**
 - `TestEventUtils.waitSubscribersExecution` promise BEFORE triggering action
 - Verify subscriber side-effects after awaiting the promise
 
-**For links:**
-- `remoteLink.create()` + `query.graph()` with related fields
+**For jobs:**
+- Direct function import + call with `container` or `getContainer()`
+- Verify mutations (records created/deleted/updated)
+- Handle no-op case (empty result set)
 
 ---
 
 ## Rules
 
-### MANDATORY Setup
+### MANDATORY
 
-- **Every HTTP test MUST have `beforeEach`** that calls `createAdminUser`
-- `/admin/*` routes: pass `adminHeaders` to every `api` call
-- `/client/*` routes: also call `generatePublishableKey` + `generateClientHeaders`; pass `clientHeaders` to every `api` call
-- Fixture destructuring: use `({ api, getContainer, dbConnection })` — these three cover 95% of tests
-- For workflow-only tests in `acmekitIntegrationTestRunner`: still need `createAdminUser` for container to have auth context
+- **Unified runner only** — `integrationTestRunner` with `mode`, never deprecated names
+- **Inline auth setup** — no `createAdminUser` helper exists. Resolve `Modules.USER`, `Modules.AUTH`, `Modules.API_KEY` in `beforeEach`
+- **JWT from config** — use `generateJwtToken` from `@acmekit/framework/utils` with `config.projectConfig.http.jwtSecret`
+- **Client API key** — use `ApiKeyType.CLIENT` and `CLIENT_API_KEY_HEADER` constants. NEVER `"publishable"` or `"x-publishable-api-key"`
+- **Every `/admin/*` request needs `adminHeaders`** — without it, 401
+- **Every `/client/*` request needs `clientHeaders`** — without it, 400
 
 ### Assertions
 
 - Use `.toEqual()` for status codes and exact matches
 - Use `expect.objectContaining()` with `expect.any(String)` for IDs and timestamps
 - Use `expect.arrayContaining()` for list assertions
-- Use `expect.not.arrayContaining()` for negative list assertions
 - Delete responses are exact: `{ id, object: "resource", deleted: true }`
 - **Only standard Jest matchers** — NEVER `expect.toBeOneOf()`, `expect.toSatisfy()`
 - For nullable fields: `expect(value === null || typeof value === "string").toBe(true)`
-- For sorting: map to array of values, compare against sorted copy
 
 ### Error Testing
 
-- Use `.catch((e) => e)` then destructure `{ response }` for HTTP error assertions
+- Use `.catch((e: any) => e)` then destructure `{ response }` for HTTP errors
 - Always check exact status code (`.toEqual(400)`) — never ranges
-- For 404: also check `response.data.type` ("not_found") and `response.data.message`
 - For workflow errors: `{ errors } = await workflow.run({ throwOnError: false })`, check `errors[0].error.message`
-
-### Workflow & Event Patterns
-
-- `waitWorkflowExecutions()` is called automatically in `afterEach` — only call it explicitly between two API calls when the second depends on workflow completion
-- `waitSubscribersExecution` promise MUST be created BEFORE the triggering action
-- Spy on `MockEventBusService.prototype.emit` (prototype, not instance)
-- Access events via `eventBusSpy.mock.calls[0][0]` (array of event objects)
-- Direct workflow execution: `workflow(getContainer()).run({ input })` — always pass container
-- Use `throwOnError: false` to inspect workflow errors without throwing
+- NEVER use `.rejects.toThrow()` on workflows — always fails (plain objects, not Error instances)
 
 ### Imports & Style
 
 - **Only import what you use** — remove unused imports
-- Resolve services via module constant: `getContainer().resolve(POST_MODULE)` where POST_MODULE matches the string in `Module()`
+- Resolve services via module constant: `getContainer().resolve(POST_MODULE)`
 - Use realistic test data ("Launch Announcement", "Quarterly Report") not "test", "foo"
 - Pass body directly: `api.post(url, body, headers)` — NOT `{ body: {...} }`
 - Runners handle DB setup/teardown — no manual cleanup needed
 - Use `jest.restoreAllMocks()` in `afterEach` when spying
+- Direct workflow execution: `workflow(getContainer()).run({ input })`
+- `waitSubscribersExecution` promise BEFORE triggering event
+- NEVER use JSDoc blocks or type casts in test files
+- **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
+- **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error
+- **Mock timers or sleep** when code under test has delays — prevents timeouts
+- **Use `new RegExp()` over complex regex literals** — SWC parser has edge cases