@acmekit/acmekit 2.13.83 → 2.13.85

package/dist/templates/app/.claude/skills/write-test/SKILL.md

@@ -1,61 +1,95 @@
 ---
 name: write-test
-description: "Generates integration or unit tests using the correct AcmeKit test runner. Auto-detects whether to use acmekitIntegrationTestRunner (HTTP routes) or moduleIntegrationTestRunner (module services). Use when adding tests for modules, workflows, API routes, or service methods."
+description: "Generates integration or unit tests using the unified integrationTestRunner. Auto-detects the correct mode (app for HTTP/workflows, module for isolated services). Use when adding tests for modules, workflows, subscribers, jobs, or API routes."
 argument-hint: "[module-or-feature]"
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob
 ---
 
 # Write Test
 
-Generate tests for AcmeKit applications using the correct test runner and patterns.
+Generate tests for AcmeKit applications using `integrationTestRunner` with the correct mode and patterns.
 
 ## Current Test Files
 
 - Existing tests: !`find src -name "*.spec.ts" -o -name "*.test.ts" 2>/dev/null | head -20 || echo "(none)"`
 - HTTP integration tests: !`ls integration-tests/http/*.spec.ts 2>/dev/null || echo "(none)"`
+- App integration tests: !`ls integration-tests/app/*.spec.ts 2>/dev/null || echo "(none)"`
 
 ## Critical Gotchas — Every Test Must Get These Right
 
-1. **Service resolution key = module constant.** For core modules: `Modules.AUTH`, `Modules.USER`. For custom modules: `container.resolve(BLOG_MODULE)` where `BLOG_MODULE = "blog"` (the string passed to `Module()`). NEVER guess `"blogModuleService"` or `"postModuleService"` — it won't resolve (AwilixResolutionError).
-2. **`moduleName` in `moduleIntegrationTestRunner` = module constant.** Same rule: `moduleName: MY_MODULE`. NEVER use `"myModuleService"`.
-3. **`resolve` in `moduleIntegrationTestRunner` = string path from CWD.** Use `resolve: "./src/modules/my-module"`. NEVER pass the imported module object (`resolve: PostModule` hangs — models not found).
-4. **Workflow errors are plain objects, not Error instances.** NEVER use `.rejects.toThrow()` on workflows — always fails. Use `throwOnError: false` + `errors` array. Error path: `errors[0].error.message` (NOT `errors[0].message`).
-5. **`.rejects.toThrow()` DOES work for service errors** (e.g., `service.retrievePost("bad-id")`). Only workflow errors are serialized.
-6. **`acmekitIntegrationTestRunner` runs real migrations** — custom modules MUST have migration files or you get `TableNotFoundException`. `moduleIntegrationTestRunner` syncs schema from entities (no migrations needed).
-7. **Axios throws on 4xx/5xx.** Use `.catch((e) => e)` for error-case assertions. Access via `error.response.status` / `error.response.data`.
+1. **Unified runner only.** `import { integrationTestRunner } from "@acmekit/test-utils"`. NEVER use `acmekitIntegrationTestRunner` or `moduleIntegrationTestRunner` — those are deprecated.
+2. **Service resolution key = module constant.** `getContainer().resolve(BLOG_MODULE)` where `BLOG_MODULE = "blog"` (the string passed to `Module()`). NEVER guess `"blogModuleService"`.
+3. **`resolve` in module mode = absolute path.** Use `resolve: process.cwd() + "/src/modules/post"`. NEVER pass the imported module object.
+4. **Workflow errors are plain objects.** NEVER use `.rejects.toThrow()` on workflows. Use `throwOnError: false` + `errors` array. Error path: `errors[0].error.message`.
+5. **`.rejects.toThrow()` DOES work for service errors** (real `Error` instances). Only workflow errors are serialized.
+6. **Inline auth setup.** There is no `createAdminUser` helper. Resolve `Modules.USER`, `Modules.AUTH`, `Modules.API_KEY` directly in `beforeEach`.
+7. **Axios throws on 4xx/5xx.** Use `.catch((e: any) => e)` for error assertions.
 
 ## Instructions
 
 ### Step 1: Determine Test Type
 
-| What to test | Runner | File location |
+| What to test | Mode | File location |
 |---|---|---|
-| API routes (HTTP requests) | `acmekitIntegrationTestRunner` | `integration-tests/http/<feature>.spec.ts` |
-| Module service methods | `moduleIntegrationTestRunner` | `src/modules/<mod>/__tests__/<name>.spec.ts` |
-| Workflows (via HTTP) | `acmekitIntegrationTestRunner` | `integration-tests/http/<feature>.spec.ts` |
-| Workflows (direct) | call `workflow(getContainer()).run()` inside either runner | depends on test type |
-| Pure functions | Plain Jest `describe/it` | `src/**/__tests__/<name>.unit.spec.ts` |
+| API routes (HTTP) | `mode: "app"` | `integration-tests/http/<feature>.spec.ts` |
+| Workflows, subscribers, jobs | `mode: "app"` | `integration-tests/app/<feature>.spec.ts` |
+| Module service methods | `mode: "module"` | `src/modules/<mod>/__tests__/<name>.spec.ts` |
+| Pure functions | Plain Jest | `src/**/__tests__/<name>.unit.spec.ts` |
 
 ### Step 2: Generate Test File
 
 #### HTTP Integration Test
 
 ```typescript
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"
+import { integrationTestRunner } from "@acmekit/test-utils"
+import {
+  ApiKeyType,
+  CLIENT_API_KEY_HEADER,
+  ContainerRegistrationKeys,
+  generateJwtToken,
+  Modules,
+} from "@acmekit/framework/utils"
 
 jest.setTimeout(60 * 1000)
 
-const adminHeaders = {
-  headers: { "x-acmekit-access-token": "test_token" },
-}
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ api, getContainer }) => {
+    let adminHeaders: Record<string, any>
+
+    beforeEach(async () => {
+      const container = getContainer()
+      const userModule = container.resolve(Modules.USER)
+      const authModule = container.resolve(Modules.AUTH)
+
+      const user = await userModule.createUsers({ email: "admin@test.js" })
+      const authIdentity = await authModule.createAuthIdentities({
+        provider_identities: [
+          { provider: "emailpass", entity_id: "admin@test.js" },
+        ],
+        app_metadata: { user_id: user.id },
+      })
+
+      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}` } }
+    })
 
-acmekitIntegrationTestRunner({
-  testSuite: ({ api, getContainer, utils }) => {
     describe("GET /admin/posts", () => {
       it("should list posts", async () => {
         const response = await api.get("/admin/posts", adminHeaders)
-        expect(response.status).toBe(200)
-        expect(response.data.posts).toBeDefined()
+        expect(response.status).toEqual(200)
       })
     })
 
@@ -63,143 +97,207 @@ 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).toBe(201)
-        expect(response.data.post.title).toBe("Launch Announcement")
+        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 () => {
+      it("should reject missing required fields", async () => {
         const { response } = await api
           .post("/admin/posts", {}, adminHeaders)
-          .catch((e) => e)
+          .catch((e: any) => e)
         expect(response.status).toEqual(400)
       })
     })
 
     describe("DELETE /admin/posts/:id", () => {
       it("should delete and confirm", async () => {
-        const { data } = await api.post(
-          "/admin/posts",
-          { title: "To Remove" },
-          adminHeaders
-        )
+        const created = (
+          await api.post("/admin/posts", { title: "To Remove" }, adminHeaders)
+        ).data.post
+
         const response = await api.delete(
-          `/admin/posts/${data.post.id}`,
+          `/admin/posts/${created.id}`,
           adminHeaders
         )
-        expect(response.status).toBe(200)
-        expect(response.data).toEqual(
-          expect.objectContaining({ id: data.post.id, deleted: true })
-        )
+        expect(response.data).toEqual({
+          id: created.id,
+          object: "post",
+          deleted: true,
+        })
       })
     })
   },
 })
 ```
 
-**Fixtures:** `api` (axios), `getContainer()`, `dbConnection`, `dbUtils`, `getAcmeKitApp()`, `utils.waitWorkflowExecutions()`.
-
-#### Module Integration Test
+#### App Integration Test (workflows, subscribers, jobs)
 
 ```typescript
-import { moduleIntegrationTestRunner } from "@acmekit/test-utils"
-import { POST_MODULE } from "../../src/modules/post"  // POST_MODULE = "post" — must match Module() key
+import { integrationTestRunner } from "@acmekit/test-utils"
+import { createPostsWorkflow } from "../../src/workflows/workflows"
+import { POST_MODULE } from "../../src/modules/post"
 
-moduleIntegrationTestRunner<IPostModuleService>({
-  moduleName: POST_MODULE,  // must match Module() key
-  resolve: "./src/modules/post",  // string path from CWD — NEVER pass imported module object
-  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({ title: "Quarterly Report" })
-        )
+jest.setTimeout(60 * 1000)
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should create via workflow", async () => {
+      const { result } = await createPostsWorkflow(getContainer()).run({
+        input: { posts: [{ title: "My Post" }] },
       })
+      expect(result[0]).toEqual(
+        expect.objectContaining({ title: "My Post" })
+      )
+    })
 
-      it("should throw on invalid data", async () => {
-        await expect(service.createPosts([{}])).rejects.toThrow()
+    it("should reject invalid input", async () => {
+      const { errors } = await createPostsWorkflow(getContainer()).run({
+        input: { posts: [{ title: "", status: "bad" }] },
+        throwOnError: false,
       })
+      expect(errors).toHaveLength(1)
+      expect(errors[0].error.message).toContain("Invalid")
     })
   },
 })
 ```
 
-**Fixtures:** `service` (proxy), `MikroOrmWrapper`, `acmekitApp`, `dbConfig`.
+#### Subscriber Test
+
+```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()
+      const service: any = container.resolve(POST_MODULE)
+      const eventBus = container.resolve(Modules.EVENT_BUS)
+
+      const [post] = await service.createPosts([
+        { title: "Test", content: "Original" },
+      ])
+
+      // CRITICAL: create promise BEFORE emitting
+      const subscriberDone = TestEventUtils.waitSubscribersExecution(
+        "post.published",
+        eventBus
+      )
+      await eventBus.emit({ name: "post.published", data: { id: post.id } })
+      await subscriberDone
+
+      const updated = await service.retrievePost(post.id)
+      expect(updated.content).toBe("Original [notified]")
+    })
+  },
+})
+```
 
-#### Unit Test
+#### Job Test
 
 ```typescript
-import { formatOrderNumber } from "../format-order-number"
+import { integrationTestRunner } from "@acmekit/test-utils"
+import archiveOldPostsJob from "../../src/jobs/archive-old-posts"
+import { POST_MODULE } from "../../src/modules/post"
 
-describe("formatOrderNumber", () => {
-  it("should pad to 6 digits", () => {
-    expect(formatOrderNumber(42)).toBe("ORD-000042")
-  })
+jest.setTimeout(60 * 1000)
+
+integrationTestRunner({
+  mode: "app",
+  testSuite: ({ getContainer }) => {
+    it("should archive old posts", async () => {
+      const container = getContainer()
+      const service: any = container.resolve(POST_MODULE)
+
+      await service.createPosts([
+        { title: "Old", status: "archived" },
+        { title: "Active", status: "published" },
+      ])
+
+      await archiveOldPostsJob(container)
+
+      const remaining = await service.listPosts()
+      expect(remaining).toHaveLength(1)
+      expect(remaining[0].title).toBe("Active")
+    })
+  },
 })
 ```
 
-#### Testing Workflows
+#### Unit Test (No Framework Bootstrap)
+
+For providers, utilities, and standalone classes. **CRITICAL:** `jest.mock()` factories are hoisted above `const`/`let`. Create mocks INSIDE the factory, access via `require()`.
 
 ```typescript
-// Via HTTP (when route triggers the workflow)
-it("should process order via workflow", async () => {
-  await api.post("/admin/orders", { items: [...] }, adminHeaders)
-  await utils.waitWorkflowExecutions()  // wait for async workflows
-  const response = await api.get("/admin/orders", adminHeaders)
-  expect(response.data.orders[0].status).toBe("processed")
+jest.mock("external-sdk", () => {
+  const mocks = { doThing: jest.fn() }
+  const MockClient = jest.fn().mockImplementation(() => ({
+    doThing: mocks.doThing,
+  }))
+  return { Client: MockClient, __mocks: mocks }
 })
 
-// Direct execution — NEVER use .rejects.toThrow() on workflows
-it("should reject invalid workflow input", async () => {
-  const { errors } = await createPostWorkflow(getContainer()).run({
-    input: {},
-    throwOnError: false,
+const { __mocks: sdkMocks } = require("external-sdk")
+
+import MyProvider from "../my-provider"
+
+describe("MyProvider", () => {
+  const mockContainer = {} as any
+
+  beforeEach(() => {
+    jest.clearAllMocks()
   })
-  expect(errors).toHaveLength(1)
-  expect(errors[0].error.message).toContain("title")  // errors[0].error.message — NOT errors[0].message
-})
 
-// Typed errors — PermanentFailure stops retries, SkipStep skips gracefully
-it("should permanently fail on invalid card", async () => {
-  const { errors } = await chargeCardWorkflow(getContainer()).run({
-    input: { cardToken: "invalid", amount: 100 },
-    throwOnError: false,
+  it("should have correct identifier", () => {
+    expect(MyProvider.identifier).toBe("my-provider")
   })
-  expect(errors[0].error.message).toContain("Card declined")
-})
 
-it("should skip optional step when disabled", async () => {
-  const { result } = await processOrderWorkflow(getContainer()).run({
-    input: { items: [{ id: "item-1" }] },
-    throwOnError: false,
+  it("should delegate to SDK", async () => {
+    sdkMocks.doThing.mockResolvedValue({ success: true })
+    const provider = new MyProvider(mockContainer, { apiKey: "key" })
+    const result = await provider.doSomething({ input: "test" })
+    expect(result.success).toBe(true)
   })
-  // SkipStep doesn't produce errors — workflow continues
-  expect(result).toBeDefined()
 })
 ```
 
-#### Testing Domain Events
+**Timer mocking:** Use `jest.useFakeTimers()` + `jest.advanceTimersByTimeAsync()` or `jest.spyOn(instance, "sleep_").mockResolvedValue(undefined)`.
+
+**SWC regex:** Use `new RegExp("...")` instead of complex regex literals.
+
+#### Module Integration Test
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-beforeEach(() => { eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit") })
-afterEach(() => { eventBusSpy.mockRestore() })
-
-it("should emit post.created event", async () => {
-  await service.createPosts([{ title: "Event Test" }])
-  expect(eventBusSpy).toHaveBeenCalledWith(
-    expect.arrayContaining([
-      expect.objectContaining({ eventName: "post.created" }),
-    ])
-  )
+import { integrationTestRunner } from "@acmekit/test-utils"
+
+jest.setTimeout(30000)
+
+integrationTestRunner<IPostModuleService>({
+  mode: "module",
+  moduleName: "post",
+  resolve: process.cwd() + "/src/modules/post",
+  testSuite: ({ service }) => {
+    it("should create a post", async () => {
+      const result = await service.createPosts([{ title: "Test" }])
+      expect(result[0]).toEqual(
+        expect.objectContaining({ title: "Test" })
+      )
+    })
+  },
 })
 ```
 
@@ -208,17 +306,23 @@ it("should emit post.created event", async () => {
 ```bash
 pnpm test:unit                    # Unit tests
 pnpm test:integration:modules     # Module integration tests
+pnpm test:integration:app         # App integration tests (workflows/subscribers/jobs)
 pnpm test:integration:http        # HTTP integration tests
 ```
 
 ## Key Patterns
 
+- Use `integrationTestRunner` with `mode` — never the old deprecated runner names
 - Match the `jest.config.js` test buckets — don't invent new locations
-- All integration tests require `NODE_OPTIONS=--experimental-vm-modules`
-- Runners handle DB setup/teardown automatically — no manual cleanup needed
-- Always pass `adminHeaders` on `/admin/*` routes
-- Pass body directly to `api.post(url, body, headers)` — NOT `{ body: {...} }`
-- Use `.catch((e) => e)` for error-case assertions — axios throws on 4xx/5xx
+- Inline auth setup in `beforeEach` — no `createAdminUser` helper
+- Pass body directly: `api.post(url, body, headers)` — NOT `{ body: {...} }`
+- Use `.catch((e: any) => e)` for error assertions — axios throws on 4xx/5xx
 - Use `expect.objectContaining()` with `expect.any(String)` for IDs/timestamps
 - Call `waitSubscribersExecution` BEFORE triggering the event
+- Import jobs/subscribers directly and call with container
 - Use realistic test data, not "test" or "foo"
+- **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
+- **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error (SWC/Babel hoisting)
+- **Mock timers or sleep** when code under test has delays — prevents test timeouts
+- **Use `new RegExp()` over complex regex literals** — SWC parser fails on some patterns
+- **Read implementation to verify error paths** — check if errors are thrown vs returned