@acmekit/acmekit 2.13.83 → 2.13.84

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

@@ -10,13 +10,15 @@ paths:
 
 ## Critical — Read Before Writing Any Test
 
+**Single unified runner.** Use `integrationTestRunner` from `@acmekit/test-utils` with a `mode` parameter. The old names (`pluginIntegrationTestRunner`, `moduleIntegrationTestRunner`) are deprecated aliases — NEVER use them.
+
 **Service resolution key = module constant.** `container.resolve(MY_MODULE)` where `MY_MODULE = "my-module"` (the string passed to `Module()`). NEVER guess `"myModuleService"` — 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`.
 
-**Schema sync vs migrations.** `pluginIntegrationTestRunner` and `moduleIntegrationTestRunner` sync DB schema from entities — no migration files needed. `acmekitIntegrationTestRunner` (host app) runs real migrations — modules MUST have migration files or you get `TableNotFoundException`.
+**Schema sync vs migrations.** `mode: "plugin"` (without `http: true`) and `mode: "module"` sync DB schema from entities — no migration files needed. `mode: "plugin"` with `http: true` runs full migrations like app mode.
 
 **`.rejects.toThrow()` DOES work for service errors** (e.g., `service.retrievePost("bad-id")`). Services throw real `Error` instances. Only workflow errors are serialized.
 
@@ -24,860 +26,602 @@ paths:
 
 ## Test Runner Selection
 
-| What to test | Runner | Fixtures provided | DB setup |
-|---|---|---|---|
-| Full plugin (modules + workflows + subscribers + jobs) | `pluginIntegrationTestRunner` | `container`, `acmekitApp`, `MikroOrmWrapper`, `dbConfig` | Schema sync (no migrations) |
-| Module service CRUD in isolation | `moduleIntegrationTestRunner` | `service`, `MikroOrmWrapper`, `acmekitApp`, `dbConfig` | Schema sync (no migrations) |
-| Pure functions (no DB) | Plain Jest `describe/it` | none | N/A |
+| What to test | Mode | HTTP? | Fixtures | DB setup |
+|---|---|---|---|---|
+| Full plugin (modules + workflows + subscribers + jobs) | `mode: "plugin"` | no | `container`, `acmekitApp`, `MikroOrmWrapper`, `dbConfig` | Schema sync |
+| Plugin HTTP routes end-to-end | `mode: "plugin"` + `http: true` | yes | `api`, `container`, `dbConfig` | Runs migrations |
+| Module service CRUD in isolation | `mode: "module"` | no | `service`, `MikroOrmWrapper`, `acmekitApp`, `dbConfig` | Schema sync |
+| Pure functions (no DB) | Plain Jest `describe/it` | — | none | N/A |
 
-**No HTTP server:** `pluginIntegrationTestRunner` does NOT start an Express server. There is no `api` fixture. To test HTTP routes, mount the plugin in a host application and use `acmekitIntegrationTestRunner` there.
+---
 
 ## File Locations (must match `jest.config.js` buckets)
 
 ```
-integration-tests/plugin/<feature>.spec.ts   → TEST_TYPE=integration:plugin
-src/modules/<mod>/__tests__/<name>.spec.ts   → TEST_TYPE=integration:modules
-src/**/__tests__/<name>.unit.spec.ts         → TEST_TYPE=unit
+integration-tests/plugin/<feature>.spec.ts  → TEST_TYPE=integration:plugin
+integration-tests/http/<feature>.spec.ts    → TEST_TYPE=integration:http
+src/modules/<mod>/__tests__/<name>.spec.ts  → TEST_TYPE=integration:modules
+src/**/__tests__/<name>.unit.spec.ts        → TEST_TYPE=unit
 ```
 
+**`integration-tests/plugin/`** — container-only tests (module CRUD, workflows, subscribers, jobs, event spying). No HTTP server.
+
+**`integration-tests/http/`** — full HTTP tests with Express. Boots the entire framework with the plugin installed. Requires auth setup (JWT + client API key).
+
+---
+
 ## Commands
 
 ```bash
 pnpm test:unit                      # Unit tests
 pnpm test:integration:modules       # Module integration tests
-pnpm test:integration:plugin        # Full plugin integration tests
+pnpm test:integration:plugin        # Plugin integration tests (container-only)
+pnpm test:integration:http          # Plugin HTTP integration tests
 ```
 
 All integration tests require `NODE_OPTIONS=--experimental-vm-modules` (set in package.json scripts).
 
 ---
 
-## Plugin Integration Tests
+## Plugin Integration Tests (`integration-tests/plugin/`)
+
+No HTTP server — test services, workflows, subscribers, and jobs directly through the container.
 
 ```typescript
-import { pluginIntegrationTestRunner } from "@acmekit/test-utils"
-import { plugin } from "../../src/plugin"
-import { BLOG_MODULE } from "../../src/modules/blog"  // BLOG_MODULE = "blog" — must match Module() key
+import { integrationTestRunner, MockEventBusService } from "@acmekit/test-utils"
+import { Modules } from "@acmekit/framework/utils"
+import { GREETING_MODULE } from "../../src/modules/greeting"
 
 jest.setTimeout(60 * 1000)
 
-pluginIntegrationTestRunner({
+integrationTestRunner({
+  mode: "plugin",
   pluginPath: process.cwd(),
   pluginOptions: {
     apiKey: "test-api-key",
   },
-  // additionalModules: { myOtherModule: OtherModule },
-  // injectedDependencies: { externalApi: mockExternalApi },
-  testSuite: ({ container, acmekitApp, MikroOrmWrapper }) => {
+  testSuite: ({ container, acmekitApp }) => {
     describe("Plugin loading", () => {
-      it("should load plugin modules", () => {
+      it("should load plugin resources", () => {
         expect(acmekitApp.modules).toBeDefined()
       })
 
-      it("should resolve typed plugin options", () => {
-        const options = plugin.resolveOptions(container)
-        expect(options.apiKey).toBe("test-api-key")
+      it("should resolve EVENT_BUS as MockEventBusService", () => {
+        const eventBus = container.resolve(Modules.EVENT_BUS)
+        expect(eventBus).toBeInstanceOf(MockEventBusService)
       })
     })
 
-    describe("BlogModule CRUD", () => {
-      let service: any
-
-      beforeEach(() => {
-        service = container.resolve(BLOG_MODULE)
-      })
-
-      it("should create a blog post", async () => {
-        const result = await service.createBlogPosts([
-          { title: "Launch Announcement" },
+    describe("GreetingModule CRUD", () => {
+      it("should create a greeting", async () => {
+        const service: any = container.resolve(GREETING_MODULE)
+        const result = await service.createGreetings([
+          { message: "Hello World" },
         ])
         expect(result).toHaveLength(1)
         expect(result[0]).toEqual(
           expect.objectContaining({
             id: expect.any(String),
-            title: "Launch Announcement",
+            message: "Hello World",
           })
         )
       })
 
-      it("should list and count", async () => {
-        await service.createBlogPosts([
-          { title: "Post A" },
-          { title: "Post B" },
-        ])
-        const [posts, count] = await service.listAndCountBlogPosts()
-        expect(count).toBe(2)
-      })
-
-      it("should soft delete and restore", async () => {
-        const [created] = await service.createBlogPosts([
-          { title: "To Delete" },
-        ])
-        await service.softDeleteBlogPosts([created.id])
-        await expect(
-          service.retrieveBlogPost(created.id)
-        ).rejects.toThrow()
-
-        await service.restoreBlogPosts([created.id])
-        const restored = await service.retrieveBlogPost(created.id)
-        expect(restored.title).toBe("To Delete")
-      })
-
       it("should throw on missing required field", async () => {
-        await expect(service.createBlogPosts([{}])).rejects.toThrow()
+        const service: any = container.resolve(GREETING_MODULE)
+        await expect(service.createGreetings([{}])).rejects.toThrow()
       })
     })
   },
 })
 ```
 
-### `pluginIntegrationTestRunner` Options
+### Plugin mode options
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `pluginPath` | `string` | **(required)** | Path to plugin root (where `package.json` lives), usually `process.cwd()` |
-| `pluginOptions` | `Record<string, unknown>` | `{}` | Simulates host app plugin config from `acmekit-config.ts` |
+| `mode` | `"plugin"` | **(required)** | Selects plugin mode |
+| `pluginPath` | `string` | **(required)** | Path to plugin root — always use `process.cwd()` |
+| `pluginOptions` | `Record<string, unknown>` | `{}` | Simulates host app plugin config |
+| `http` | `boolean` | `false` | Set `true` to boot full Express server for HTTP tests |
 | `additionalModules` | `Record<string, any>` | `{}` | Extra modules to load alongside the plugin |
 | `injectedDependencies` | `Record<string, any>` | `{}` | Mock services to register in the container |
-| `schema` | `string` | `"public"` | Postgres schema |
 | `dbName` | `string` | auto-generated | Override the computed DB name |
+| `schema` | `string` | `"public"` | Postgres schema |
 | `debug` | `boolean` | `false` | Enables DB query logging |
-| `cwd` | `string` | `process.cwd()` | Working directory |
-| `hooks` | `{ beforePluginInit?, afterPluginInit? }` | `{}` | Lifecycle hooks |
-| `testSuite` | `(options: PluginSuiteOptions) => void` | **(required)** | Test callback |
+| `hooks` | `RunnerHooks` | `{}` | Lifecycle hooks |
+| `testSuite` | `(options) => void` | **(required)** | Test callback |
 
-### `PluginSuiteOptions` fields
+### Plugin mode fixtures (container-only)
 
 - `container` — proxy to the shared `AcmeKitContainer` (auto-refreshed each `beforeEach`)
 - `acmekitApp` — proxy to the `AcmeKitApp` instance (has `.modules`, `.sharedContainer`)
 - `MikroOrmWrapper` — raw DB access: `.getManager()`, `.forkManager()`, `.getOrm()`
-- `dbConfig` — `{ schema, clientUrl }`
+- `dbConfig` — `{ schema, clientUrl, dbName }`
+
+### Plugin test lifecycle (container-only)
 
-### Plugin test lifecycle
+Each `it` block gets: schema drop + recreate → fresh plugin boot (all modules, subscribers, workflows, jobs loaded) → test runs → schema clear → module shutdown. No manual cleanup needed.
 
-Each `it` block gets: schema drop + recreate → fresh plugin boot (all modules, subscribers, workflows, jobs loaded via SubscriberLoader, WorkflowLoader, JobLoader) → test runs → schema clear → module shutdown. No manual cleanup needed.
+---
 
-### Testing plugin options
+## Plugin HTTP Integration Tests (`integration-tests/http/`)
+
+Full Express server with the plugin installed. Boots the entire framework including all core modules (user, auth, api-key, etc.), runs migrations, and serves plugin routes.
 
 ```typescript
-import { plugin } from "../../src/plugin"
+import { integrationTestRunner } from "@acmekit/test-utils"
+import {
+  ApiKeyType,
+  CLIENT_API_KEY_HEADER,
+  ContainerRegistrationKeys,
+  generateJwtToken,
+  Modules,
+} from "@acmekit/framework/utils"
+import { GREETING_MODULE } from "../../src/modules/greeting"
+
+jest.setTimeout(120 * 1000)
 
-pluginIntegrationTestRunner({
+integrationTestRunner({
+  mode: "plugin",
+  http: true,
   pluginPath: process.cwd(),
-  pluginOptions: { apiKey: "test-key", debug: true },
-  testSuite: ({ container }) => {
-    it("should resolve typed plugin options", () => {
-      const options = plugin.resolveOptions(container)
-      expect(options.apiKey).toBe("test-key")
-      expect(options.debug).toBe(true)
+  pluginOptions: { apiKey: "test-api-key" },
+  testSuite: ({ api, container }) => {
+    let adminHeaders: Record<string, any>
+    let clientHeaders: Record<string, any>
+
+    beforeEach(async () => {
+      const userModule = container.resolve(Modules.USER)
+      const authModule = container.resolve(Modules.AUTH)
+      const apiKeyModule = container.resolve(Modules.API_KEY)
+
+      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}` },
+      }
+
+      const apiKey = await apiKeyModule.createApiKeys({
+        title: "Test Client Key",
+        type: ApiKeyType.CLIENT,
+        created_by: "test",
+      })
+
+      clientHeaders = {
+        headers: { [CLIENT_API_KEY_HEADER]: apiKey.token },
+      }
+    })
+
+    describe("Admin plugin routes", () => {
+      it("POST /admin/plugin/greetings creates a greeting", async () => {
+        const response = await api.post(
+          "/admin/plugin/greetings",
+          { message: "Hello from HTTP" },
+          adminHeaders
+        )
+        expect(response.status).toEqual(200)
+        expect(response.data.greeting).toEqual(
+          expect.objectContaining({
+            id: expect.any(String),
+            message: "Hello from HTTP",
+          })
+        )
+      })
+
+      it("DELETE /admin/plugin/greetings/:id soft-deletes", async () => {
+        const created = await api.post(
+          "/admin/plugin/greetings",
+          { message: "Delete me" },
+          adminHeaders
+        )
+        const response = await api.delete(
+          `/admin/plugin/greetings/${created.data.greeting.id}`,
+          adminHeaders
+        )
+        expect(response.data).toEqual({
+          id: created.data.greeting.id,
+          object: "greeting",
+          deleted: true,
+        })
+      })
+    })
+
+    describe("Client plugin routes", () => {
+      it("GET /client/plugin/greetings with API key", async () => {
+        await api.post(
+          "/admin/plugin/greetings",
+          { message: "Public" },
+          adminHeaders
+        )
+        const response = await api.get(
+          "/client/plugin/greetings",
+          clientHeaders
+        )
+        expect(response.status).toEqual(200)
+        expect(response.data.greetings).toHaveLength(1)
+      })
+    })
+
+    describe("Auth enforcement", () => {
+      it("admin route rejects without JWT", async () => {
+        const error = await api
+          .get("/admin/plugin")
+          .catch((e: any) => e)
+        expect(error.response.status).toEqual(401)
+      })
     })
   },
 })
 ```
 
+### Plugin HTTP fixtures
+
+- `api` — axios instance pointed at `http://localhost:<port>`
+- `container` — proxy to the live container (includes all framework modules)
+- `dbConfig` — `{ schema, clientUrl, dbName }`
+
 ---
 
 ## Module Integration Tests
 
 ```typescript
-import { moduleIntegrationTestRunner } from "@acmekit/test-utils"
-import { MY_MODULE } from "../../src/modules/my-module"  // MY_MODULE = "my-module" — must match Module() key
+import { integrationTestRunner } from "@acmekit/test-utils"
 
 jest.setTimeout(30000)
 
-moduleIntegrationTestRunner<IMyModuleService>({
-  moduleName: MY_MODULE,  // must match the string passed to Module(), e.g., "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" },
+integrationTestRunner<IGreetingModuleService>({
+  mode: "module",
+  moduleName: "greeting",
+  resolve: process.cwd() + "/src/modules/greeting",
   testSuite: ({ service }) => {
-    afterEach(() => {
-      jest.restoreAllMocks()
-    })
-
-    describe("createPosts", () => {
-      it("should create a post", async () => {
-        const result = await service.createPosts([
-          { title: "Quarterly Report" },
+    describe("createGreetings", () => {
+      it("should create a greeting", async () => {
+        const result = await service.createGreetings([
+          { message: "Hello" },
         ])
         expect(result).toHaveLength(1)
         expect(result[0]).toEqual(
           expect.objectContaining({
             id: expect.any(String),
-            title: "Quarterly Report",
+            message: "Hello",
           })
         )
       })
-
-      it("should throw on missing required field", async () => {
-        await expect(service.createPosts([{}])).rejects.toThrow()
-      })
     })
   },
 })
 ```
 
-### `SuiteOptions<TService>` fields
+### Module mode fixtures
 
 - `service` — proxy to the module service (auto-refreshed each `beforeEach`)
-- `MikroOrmWrapper` — raw DB access: `.getManager()`, `.forkManager()`, `.getOrm()`
+- `MikroOrmWrapper` — raw DB access
 - `acmekitApp` — proxy to the `AcmeKitApp` instance
 - `dbConfig` — `{ schema, clientUrl }`
 
-### CRUD test patterns
+### Module test lifecycle
 
-```typescript
-// --- Create ---
-const [post] = await service.createPosts([{ title: "Test" }])
-
-// --- List with filters ---
-const filtered = await service.listPosts({ status: "published" })
-const withRelations = await service.listPosts({}, { relations: ["comments"] })
-
-// --- List and count ---
-const [posts, count] = await service.listAndCountPosts()
-expect(count).toEqual(2)
-
-// --- Retrieve ---
-const post = await service.retrievePost(id)
-
-// --- Retrieve with select (verify no extra fields) ---
-const withSelect = await service.retrievePost(id, { select: ["id"] })
-const serialized = JSON.parse(JSON.stringify(withSelect))
-expect(serialized).toEqual({ id })
-
-// --- Update ---
-const updated = await service.updatePosts(id, { title: "New Title" })
-
-// --- Soft delete / restore ---
-await service.softDeletePosts([id])
-const listed = await service.listPosts({ id })
-expect(listed).toHaveLength(0)
-await service.restorePosts([id])
-const restored = await service.listPosts({ id })
-expect(restored).toHaveLength(1)
-
-// --- Hard delete ---
-await service.deletePosts([id])
-```
-
-### Error handling in module tests
-
-```typescript
-// Style 1: .catch((e) => e) — preferred when checking message
-const error = await service.retrievePost("nonexistent").catch((e) => 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: check error.type
-let error
-try {
-  await service.deleteApiKeys([unrevokedKey.id])
-} catch (e) {
-  error = e
-}
-expect(error.type).toEqual("not_allowed")
-```
-
-### Related entity testing
-
-```typescript
-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")
-```
+Each `it` block gets: schema drop + recreate → fresh module boot → test runs → schema clear → module shutdown. No manual cleanup needed.
 
 ---
 
-## Testing Workflows Through Container
+## Testing Workflows
 
-Workflows are tested by running them via `container` — NOT via HTTP:
+Workflows are called via `workflowFn(container).run({ input })`:
 
 ```typescript
-import { createOrderWorkflow } from "../../src/workflows"
+import { createGreetingsWorkflow } from "../../src/workflows"
 
-pluginIntegrationTestRunner({
+integrationTestRunner({
+  mode: "plugin",
   pluginPath: process.cwd(),
   testSuite: ({ container }) => {
-    it("should execute the create order workflow", async () => {
-      const { result } = await createOrderWorkflow(container).run({
-        input: {
-          customerId: "cus_123",
-          items: [{ sku: "SKU-001", qty: 2 }],
-        },
+    it("should create a greeting via workflow", async () => {
+      const { result } = await createGreetingsWorkflow(container).run({
+        input: { greetings: [{ message: "Workflow Hello" }] },
       })
-      expect(result.order).toEqual(
-        expect.objectContaining({ customerId: "cus_123" })
-      )
+      expect(result).toHaveLength(1)
+      expect(result[0].message).toBe("Workflow Hello")
     })
 
-    it("should reject invalid workflow input", async () => {
-      const { errors } = await createOrderWorkflow(container).run({
-        input: {},
+    it("should reject invalid input", async () => {
+      const { errors } = await createGreetingsWorkflow(container).run({
+        input: { greetings: [{ message: "", status: "invalid" }] },
         throwOnError: false,
       })
       expect(errors).toHaveLength(1)
+      expect(errors[0].error.message).toContain("Invalid")
     })
   },
 })
 ```
 
----
-
-## Asserting Domain Events
-
-Both runners inject `MockEventBusService` under `Modules.EVENT_BUS`. Spy on the **prototype**, not an instance.
+### Step compensation
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
-
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
-
-it("should emit blog-post.created event", async () => {
-  const service = container.resolve(BLOG_MODULE)  // "blog" — from Module() key
-  await service.createBlogPosts([{ title: "Event Test" }])
+it("should compensate on failure", async () => {
+  const service: any = container.resolve(GREETING_MODULE)
 
-  // 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: "blog-post.created",
-        data: expect.objectContaining({ id: expect.any(String) }),
-      }),
-    ])
-  )
+  const { errors } = await createGreetingsWorkflow(container).run({
+    input: { greetings: [{ message: "Will Fail", trigger_error: true }] },
+    throwOnError: false,
+  })
+  expect(errors).toHaveLength(1)
 
-  // Second argument is always { internal: true }
-  expect(eventBusSpy.mock.calls[0][1]).toEqual({ internal: true })
+  // Verify compensation ran — greeting rolled back
+  const greetings = await service.listGreetings()
+  expect(greetings).toHaveLength(0)
 })
 ```
 
 ---
 
-## Waiting for Subscribers
+## Testing Subscribers
 
-Use `waitSubscribersExecution` when testing subscriber side-effects. **CRITICAL: create the promise BEFORE triggering the event.**
+### Direct handler invocation (plugin mode — container-only)
 
-```typescript
-import { TestEventUtils } from "@acmekit/test-utils"
-import { Modules } from "@acmekit/framework/utils"
-
-it("should execute subscriber side-effect", async () => {
-  const eventBus = container.resolve(Modules.EVENT_BUS)
-
-  // Create promise BEFORE triggering event
-  const subscriberExecution = TestEventUtils.waitSubscribersExecution(
-    "blog-post.created",
-    eventBus
-  )
-  const service = container.resolve(BLOG_MODULE)  // "blog" — from Module() key
-  await service.createBlogPosts([{ title: "Trigger Event" }])
-  await subscriberExecution
-  // now assert subscriber side-effect
-})
-```
-
----
-
-## Resolving Services in Tests
+Import the handler and call it manually with `{ event, container }`:
 
 ```typescript
-// In pluginIntegrationTestRunner — use module constant (matches Module() key)
-import { BLOG_MODULE } from "../../src/modules/blog"  // BLOG_MODULE = "blog"
-const service = container.resolve(BLOG_MODULE)
-const query = container.resolve(ContainerRegistrationKeys.QUERY)
-
-// In moduleIntegrationTestRunner — use the service fixture directly
-const result = await service.listBlogPosts()
-
-// NEVER guess the key — "blogModuleService", "blog-module", "BlogModule" are all WRONG
-// The key is EXACTLY the string passed to Module() in your module definition
-```
-
----
-
-## JWT Token Generation
-
-**ALWAYS use `generateJwtToken` from `@acmekit/framework/utils`.** NEVER use `jsonwebtoken` directly or hardcode the JWT secret.
+import { integrationTestRunner } from "@acmekit/test-utils"
+import greetingCreatedHandler from "../../src/subscribers/greeting-created"
+import { GREETING_MODULE } from "../../src/modules/greeting"
 
-This applies when testing your plugin mounted in a host application with `acmekitIntegrationTestRunner`.
-
-```typescript
-import {
-  ContainerRegistrationKeys,
-  generateJwtToken,
-  Modules,
-} from "@acmekit/framework/utils"
+jest.setTimeout(60 * 1000)
 
-// Resolve the JWT secret from the project config — NEVER hardcode "supersecret"
-const config = container.resolve(ContainerRegistrationKeys.CONFIG_MODULE)
-const { jwtSecret, jwtOptions } = config.projectConfig.http
+integrationTestRunner({
+  mode: "plugin",
+  pluginPath: process.cwd(),
+  testSuite: ({ container }) => {
+    it("should append ' [notified]' to greeting message", async () => {
+      const service: any = container.resolve(GREETING_MODULE)
+      const [greeting] = await service.createGreetings([
+        { message: "Hello World" },
+      ])
+
+      await greetingCreatedHandler({
+        event: {
+          data: { id: greeting.id },
+          name: "greeting.created",
+        },
+        container,
+      })
 
-const token = generateJwtToken(
-  {
-    actor_id: user.id,
-    actor_type: "user",           // or "customer" for customer auth
-    auth_identity_id: authIdentity.id,
-    app_metadata: { user_id: user.id },
+      const updated = await service.retrieveGreeting(greeting.id)
+      expect(updated.message).toBe("Hello World [notified]")
+    })
   },
-  { secret: jwtSecret, expiresIn: "1d", jwtOptions }
-)
-```
-
----
-
-## Client API Key Generation
-
-**ALWAYS use `ApiKeyType.CLIENT` and `CLIENT_API_KEY_HEADER`.** NEVER use `type: "publishable"` or `"x-publishable-api-key"`.
-
-```typescript
-import {
-  ApiKeyType,
-  CLIENT_API_KEY_HEADER,
-  Modules,
-} from "@acmekit/framework/utils"
-
-const apiKeyModule = container.resolve(Modules.API_KEY)
-const apiKey = await apiKeyModule.createApiKeys({
-  title: "Test Client Key",
-  type: ApiKeyType.CLIENT,
-  created_by: "system",
 })
-
-const clientHeaders = {
-  headers: { [CLIENT_API_KEY_HEADER]: apiKey.token },
-}
 ```
 
----
+### Event bus driven (plugin HTTP mode or app mode)
 
-## Service Resolution
-
-**ALWAYS use `Modules.*` constants** to resolve core services. NEVER use string literals like `"auth"`, `"user"`, `"customer"`.
+Use `TestEventUtils.waitSubscribersExecution` with the real event bus:
 
 ```typescript
-// RIGHT
-const authModule = container.resolve(Modules.AUTH)
-const userModule = container.resolve(Modules.USER)
-const apiKeyModule = container.resolve(Modules.API_KEY)
+import { integrationTestRunner, TestEventUtils } from "@acmekit/test-utils"
 
-// WRONG — string literals are fragile and may not match container keys
-const authModule = container.resolve("auth")        // ❌
-const userModule = container.resolve("user")        // ❌
+// CRITICAL: create the promise BEFORE emitting the event
+const subscriberDone = TestEventUtils.waitSubscribersExecution(
+  "greeting.created",
+  eventBus
+)
+await eventBus.emit({ name: "greeting.created", data: { id } })
+await subscriberDone
 ```
 
 ---
 
-## Environment
-
-- `jest.config.js` loads `.env.test` via `@acmekit/utils` `loadEnv("test", process.cwd())`
-- `integration-tests/setup.js` clears `MetadataStorage` between test files (prevents MikroORM entity bleed)
-- 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>`
-
----
+## Testing Jobs
 
-## Anti-Patterns — NEVER Do These
+Import the job function directly and call with container:
 
 ```typescript
-// WRONG — using acmekitIntegrationTestRunner in a plugin
-import { acmekitIntegrationTestRunner } from "@acmekit/test-utils"  // ❌
-// RIGHT — use pluginIntegrationTestRunner for plugin tests
-import { pluginIntegrationTestRunner } from "@acmekit/test-utils"
-
-// WRONG — trying to use `api` in plugin tests (no HTTP server!)
-testSuite: ({ api }) => { ... }  // ❌ api is not available
-// RIGHT — resolve services from container and call methods directly
-testSuite: ({ container }) => {
-  const service = container.resolve(BLOG_MODULE)
-  await service.createBlogPosts([{ title: "Test" }])
-}
-
-// WRONG — silently passes without asserting
-const result = await createWorkflow(container).run({ input: body })
-if (!result.result) return  // ❌ test passes with zero assertions!
-// RIGHT
-const { result } = await createWorkflow(container).run({ input: body })
-expect(result).toBeDefined()
-
-// 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 result fields
-expect(typeof result.id).toBe("string")  // ❌
-// RIGHT
-expect(result.id).toEqual(expect.any(String))
-
-// WRONG — JSDoc comment block at file top (test files never have these)
-/** BlogModule — tests CRUD, validation, events */  // ❌
-
-// WRONG — type casts in tests
-const filtered = (operations as Array<{ status: string }>).filter(...)  // ❌
-
-// WRONG — vague range assertions
-expect(someStatus).toBeGreaterThanOrEqual(400)  // ❌
-// RIGHT
-expect(someStatus).toEqual("voided")
-
-// WRONG — asserting exact objects (timestamps/IDs change)
-expect(result).toEqual({ id: "123", title: "Test", created_at: "..." })  // ❌
-// RIGHT
-expect(result).toEqual(expect.objectContaining({
-  id: expect.any(String),
-  title: "Test",
-}))
-
-// WRONG — calling waitSubscribersExecution AFTER triggering event
-await service.createBlogPosts([{ title: "Test" }])
-await TestEventUtils.waitSubscribersExecution("blog-post.created", eventBus)  // ❌ may miss it
-// RIGHT — capture promise BEFORE triggering
-const execution = TestEventUtils.waitSubscribersExecution("blog-post.created", eventBus)
-await service.createBlogPosts([{ title: "Test" }])
-await execution
-
-// WRONG — putting test files in non-standard locations
-// integration-tests/tests/plugin.test.ts  ← won't be picked up
-// RIGHT
-// integration-tests/plugin/plugin.spec.ts
-
-// WRONG — hardcoding pluginPath
-pluginIntegrationTestRunner({ pluginPath: "/absolute/path/to/plugin" })  // ❌
-// RIGHT
-pluginIntegrationTestRunner({ pluginPath: process.cwd() })
-
-// 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 — calling plugin.resolveOptions(container) in module loaders
-// Module container is scoped, not root — resolveOptions needs root container
-// RIGHT — only use plugin.resolveOptions(container) in tests, subscribers, and workflows
-
-// WRONG — calling workflow without passing container
-await createOrderWorkflow.run({ input: { ... } })  // ❌
-// RIGHT
-await createOrderWorkflow(container).run({ input: { ... } })
-
-// WRONG — using jsonwebtoken directly or hardcoding JWT secrets
-import jwt from "jsonwebtoken"
-const token = jwt.sign({ user_id: user.id }, "supersecret")  // ❌
-// RIGHT — use generateJwtToken with config-resolved secret
-import { generateJwtToken, ContainerRegistrationKeys } from "@acmekit/framework/utils"
-const config = container.resolve(ContainerRegistrationKeys.CONFIG_MODULE)
-const token = generateJwtToken(payload, { secret: config.projectConfig.http.jwtSecret })
-
-// WRONG — using string "publishable" for API key type
-await apiKeyModule.createApiKeys({ type: "publishable" })  // ❌
-// RIGHT — use ApiKeyType.CLIENT enum
-import { ApiKeyType } from "@acmekit/framework/utils"
-await apiKeyModule.createApiKeys({ type: ApiKeyType.CLIENT })
-
-// WRONG — using old publishable header name
-headers: { "x-publishable-api-key": token }  // ❌
-// RIGHT — use CLIENT_API_KEY_HEADER constant
-import { CLIENT_API_KEY_HEADER } from "@acmekit/framework/utils"
-headers: { [CLIENT_API_KEY_HEADER]: token }
-
-// WRONG — resolving core services with string literals
-container.resolve("auth")  // ❌
-container.resolve("user")  // ❌
-// RIGHT — use Modules.* constants
-container.resolve(Modules.AUTH)
-container.resolve(Modules.USER)
+import { integrationTestRunner } from "@acmekit/test-utils"
+import cleanupGreetingsJob from "../../src/jobs/cleanup-greetings"
+import { GREETING_MODULE } from "../../src/modules/greeting"
 
-// 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(
-  createOrderWorkflow(container).run({ input: {} })
-).rejects.toThrow()  // ❌ always fails — "Received function did not throw"
-
-// RIGHT — Option 1: use throwOnError: false + errors array (recommended)
-const { errors } = await createOrderWorkflow(container).run({
-  input: {},
-  throwOnError: false,
-})
-expect(errors).toHaveLength(1)
-expect(errors[0].error.message).toContain("customerId")
-
-// RIGHT — Option 2: use .rejects.toEqual() for plain object matching
-await expect(
-  createOrderWorkflow(container).run({ input: {} })
-).rejects.toEqual(
-  expect.objectContaining({
-    message: expect.stringContaining("customerId"),
-  })
-)
+jest.setTimeout(60 * 1000)
 
-// 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.
-```
+integrationTestRunner({
+  mode: "plugin",
+  pluginPath: process.cwd(),
+  testSuite: ({ container }) => {
+    it("should soft-delete greetings with lang='old'", async () => {
+      const service: any = container.resolve(GREETING_MODULE)
 
----
+      await service.createGreetings([
+        { message: "Old 1", lang: "old" },
+        { message: "Old 2", lang: "old" },
+        { message: "Current", lang: "en" },
+      ])
 
-## Workflow Composition Testing
+      await cleanupGreetingsJob(container)
 
-### Happy path + error inspection
+      const remaining = await service.listGreetings()
+      expect(remaining).toHaveLength(1)
+      expect(remaining[0].lang).toBe("en")
+    })
 
-```typescript
-import { createOrderWorkflow } from "../../src/workflows"
+    it("should do nothing when no old greetings exist", async () => {
+      const service: any = container.resolve(GREETING_MODULE)
+      await service.createGreetings([{ message: "Hello", lang: "en" }])
 
-pluginIntegrationTestRunner({
-  pluginPath: process.cwd(),
-  testSuite: ({ container }) => {
-    it("should execute the workflow", async () => {
-      const { result } = await createOrderWorkflow(container).run({
-        input: {
-          customerId: "cus_123",
-          items: [{ sku: "SKU-001", qty: 2 }],
-        },
-      })
-      expect(result.order).toEqual(
-        expect.objectContaining({ customerId: "cus_123" })
-      )
-    })
+      await cleanupGreetingsJob(container)
 
-    it("should reject invalid input via inputSchema", async () => {
-      const { errors } = await createOrderWorkflow(container).run({
-        input: {},
-        throwOnError: false,
-      })
-      expect(errors).toHaveLength(1)
-      expect(errors[0].error.message).toContain("customerId")
+      const remaining = await service.listGreetings()
+      expect(remaining).toHaveLength(1)
     })
   },
 })
 ```
 
-### Step compensation
-
-Test that compensation reverses side-effects when a later step fails:
+---
 
-```typescript
-it("should compensate on failure", async () => {
-  const service = container.resolve("orderModuleService")
-
-  // Run workflow that will fail at payment step
-  const { errors } = await createOrderWorkflow(container).run({
-    input: {
-      customerId: "cus_123",
-      items: [{ sku: "SKU-001", qty: 2 }],
-      paymentMethod: "invalid-method",  // triggers payment step failure
-    },
-    throwOnError: false,
-  })
+## Asserting Domain Events
 
-  expect(errors).toHaveLength(1)
+Plugin mode (without HTTP) injects `MockEventBusService`. Spy on the **prototype**, not an instance.
 
-  // Verify compensation ran — order should not exist
-  const orders = await service.listOrders({ customerId: "cus_123" })
-  expect(orders).toHaveLength(0)
-})
-```
+```typescript
+import { MockEventBusService } from "@acmekit/test-utils"
 
-### `when()` branches
+it("should capture events", async () => {
+  const spy = jest.spyOn(MockEventBusService.prototype, "emit")
+  const eventBus = container.resolve(Modules.EVENT_BUS)
 
-```typescript
-it("should skip notification when flag is false", async () => {
-  const eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-
-  await createOrderWorkflow(container).run({
-    input: {
-      customerId: "cus_123",
-      items: [{ sku: "SKU-001", qty: 1 }],
-      sendNotification: false,
-    },
-  })
+  await eventBus.emit([
+    { name: "greeting.created", data: { id: "g1", message: "Hello" } },
+  ])
 
-  // No notification event emitted
-  const allEvents = eventBusSpy.mock.calls.flatMap((call) => call[0])
-  expect(allEvents).toEqual(
-    expect.not.arrayContaining([
-      expect.objectContaining({ name: "order.notification.sent" }),
+  expect(spy).toHaveBeenCalledTimes(1)
+  expect(spy.mock.calls[0][0]).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        name: "greeting.created",
+        data: expect.objectContaining({ id: "g1" }),
+      }),
     ])
   )
-  eventBusSpy.mockRestore()
-})
-```
-
-### `parallelize()` results
 
-```typescript
-it("should run parallel steps", async () => {
-  const { result } = await enrichOrderWorkflow(container).run({
-    input: { orderId: order.id },
-  })
-
-  // Both parallel branches produce results
-  expect(result.customerDetails).toBeDefined()
-  expect(result.inventoryCheck).toBeDefined()
-  expect(result.customerDetails.name).toBe("Jane Doe")
-  expect(result.inventoryCheck.available).toBe(true)
+  spy.mockRestore()
 })
 ```
 
-### `StepResponse.permanentFailure()` and `StepResponse.skip()`
-
-```typescript
-it("should permanently fail without compensation", async () => {
-  const { errors } = await validatePaymentWorkflow(container).run({
-    input: { paymentId: "fraudulent-id" },
-    throwOnError: false,
-  })
-
-  expect(errors).toHaveLength(1)
-  expect(errors[0].error.message).toContain("Fraudulent payment detected")
-  // permanentFailure skips compensation — verify no rollback happened
-})
+**Note:** MockEventBusService `emit` takes an **array** of events. Real event bus `emit` takes a single `{ name, data }` object.
 
-it("should skip optional step", async () => {
-  const { result } = await processOrderWorkflow(container).run({
-    input: { orderId: order.id, skipLoyaltyPoints: true },
-  })
-
-  // Workflow completes successfully, loyalty step was skipped
-  expect(result.order.status).toBe("processed")
-  expect(result.loyaltyPoints).toBeUndefined()
-})
-```
+---
 
-### Workflow hooks
+## Service Resolution
 
 ```typescript
-it("should execute hook handler", async () => {
-  const hookResult: any[] = []
-
-  const workflow = createOrderWorkflow(container)
-  workflow.hooks.orderCreated((input) => {
-    hookResult.push(input)
-  })
+// Custom modules — use module constant
+import { GREETING_MODULE } from "../../src/modules/greeting"
+const service = container.resolve(GREETING_MODULE)
 
-  await workflow.run({
-    input: { customerId: "cus_123", items: [{ sku: "SKU-001", qty: 1 }] },
-  })
+// Core modules — use Modules.* constants
+container.resolve(Modules.AUTH)
+container.resolve(Modules.USER)
 
-  expect(hookResult).toHaveLength(1)
-  expect(hookResult[0]).toEqual(
-    expect.objectContaining({ orderId: expect.any(String) })
-  )
-})
+// WRONG
+container.resolve("greetingModuleService")  // ❌
+container.resolve("auth")  // ❌
 ```
 
 ---
 
-## Cross-Module Testing with additionalModules
-
-When a plugin workflow depends on another module (e.g., a payment module):
+## Anti-Patterns — NEVER Do These
 
 ```typescript
-import { PaymentModule } from "@acmekit/payment"
-
-pluginIntegrationTestRunner({
+// WRONG — using deprecated runner names
+import { pluginIntegrationTestRunner } from "@acmekit/test-utils"  // ❌
+import { moduleIntegrationTestRunner } from "@acmekit/test-utils"  // ❌
+// RIGHT — use unified runner with mode
+import { integrationTestRunner } from "@acmekit/test-utils"
+integrationTestRunner({ mode: "plugin", pluginPath: process.cwd(), ... })
+
+// WRONG — trying to use `api` in container-only plugin tests
+integrationTestRunner({
+  mode: "plugin",
   pluginPath: process.cwd(),
-  additionalModules: {
-    paymentModuleService: PaymentModule,
-  },
-  testSuite: ({ container }) => {
-    it("should process order with payment", async () => {
-      const { result } = await createOrderWorkflow(container).run({
-        input: {
-          customerId: "cus_123",
-          items: [{ sku: "SKU-001", qty: 2 }],
-          paymentMethod: "card",
-        },
-      })
-      expect(result.payment).toEqual(
-        expect.objectContaining({ status: "captured" })
-      )
-    })
+  testSuite: ({ api }) => {  // ❌ api is not available without http: true
+    await api.get("/admin/plugin")
   },
 })
-```
 
----
-
-## Link / Relation Testing in Plugin Context
-
-Test cross-module links via `container.resolve`:
-
-```typescript
-import { ContainerRegistrationKeys } from "@acmekit/framework/utils"
-
-it("should create and query a link", async () => {
-  const remoteLink = container.resolve(ContainerRegistrationKeys.LINK)
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+// WRONG — hardcoding pluginPath
+integrationTestRunner({ mode: "plugin", pluginPath: "/absolute/path" })  // ❌
+// RIGHT
+integrationTestRunner({ mode: "plugin", pluginPath: process.cwd() })
 
-  const blogService = container.resolve(BLOG_MODULE)  // "blog" — from Module() key
-  const [post] = await blogService.createBlogPosts([{ title: "Linked Post" }])
-  const [category] = await blogService.createBlogCategories([{ name: "Tech" }])
+// WRONG — no auth in HTTP tests
+it("should list", async () => {
+  await api.get("/admin/plugin")  // ❌ 401
+})
 
-  await remoteLink.create([{
-    blogModuleService: { blog_post_id: post.id },
-    blogCategoryModuleService: { blog_category_id: category.id },
-  }])
+// WRONG — asserting error responses without catching (axios throws!)
+const response = await api.post("/admin/plugin/greetings", {}, adminHeaders)
+expect(response.status).toEqual(400)  // ❌ never reached
+// RIGHT
+const { response } = await api.post("/admin/plugin/greetings", {}, adminHeaders).catch((e: any) => e)
+expect(response.status).toEqual(400)
 
-  const { data: [linkedPost] } = await query.graph({
-    entity: "blog_post",
-    fields: ["id", "title", "category.*"],
-    filters: { id: post.id },
-  })
+// WRONG — calling workflow without passing container
+await createGreetingsWorkflow.run({ input: {} })  // ❌
+// RIGHT
+await createGreetingsWorkflow(container).run({ input: {} })
 
-  expect(linkedPost.category.name).toBe("Tech")
+// WRONG — using .rejects.toThrow() on workflow errors
+await expect(
+  createGreetingsWorkflow(container).run({ input: {} })
+).rejects.toThrow()  // ❌ plain object, not Error instance
+// RIGHT
+const { errors } = await createGreetingsWorkflow(container).run({
+  input: {},
+  throwOnError: false,
 })
-```
+expect(errors[0].error.message).toContain("message")
 
----
-
-## What to Test
-
-**Plugin loading:** Modules resolve from container, plugin options accessible via `plugin.resolveOptions(container)`, auto-discovered resources (subscribers, workflows, jobs) are loaded.
+// WRONG — calling waitSubscribersExecution AFTER triggering event
+await eventBus.emit({ name: "greeting.created", data: { id } })
+await TestEventUtils.waitSubscribersExecution("greeting.created", eventBus)  // ❌
+// RIGHT — capture promise BEFORE
+const done = TestEventUtils.waitSubscribersExecution("greeting.created", eventBus)
+await eventBus.emit({ name: "greeting.created", data: { id } })
+await done
+
+// WRONG — exact object assertions (timestamps/IDs change)
+expect(result).toEqual({ id: "123", message: "Test" })  // ❌
+// RIGHT
+expect(result).toEqual(expect.objectContaining({
+  id: expect.any(String),
+  message: "Test",
+}))
 
-**Module services:** CRUD operations (create, retrieve, list, update, softDelete, restore), custom methods, validation (required fields → `rejects.toThrow()`, not found → check error.message), related entities with `{ relations: [...] }`.
+// WRONG — non-standard Jest matchers
+expect(value).toBeOneOf([expect.any(String), null])  // ❌
+// RIGHT
+expect(value === null || typeof value === "string").toBe(true)
 
-**Workflows:**
-- Happy path + correct result
-- `throwOnError: false` + `errors` array inspection
-- `inputSchema` rejection with specific error messages
-- Compensation on failure (verify side-effects rolled back)
-- `when()` branches (verify skipped/executed paths)
-- `parallelize()` results (verify both branches complete)
-- `StepResponse.permanentFailure()` (no compensation)
-- `StepResponse.skip()` (optional steps)
-- Hook handlers (`workflow.hooks.hookName(handler)`)
+// WRONG — resolve path as relative from test file
+integrationTestRunner({ mode: "module", moduleName: "greeting", resolve: "../index" })  // ❌
+// RIGHT
+integrationTestRunner({ mode: "module", moduleName: "greeting", resolve: process.cwd() + "/src/modules/greeting" })
 
-**Subscribers/Events:** Spy on `MockEventBusService.prototype.emit`, access events via `mock.calls[0][0]`, use `TestEventUtils.waitSubscribersExecution` for async subscriber side-effects.
+// WRONG — using jsonwebtoken directly
+import jwt from "jsonwebtoken"  // ❌
+// RIGHT — use generateJwtToken from @acmekit/framework/utils
 
-**Links:** `remoteLink.create()` + `query.graph()` with related fields.
+// WRONG — using old publishable API key names
+{ type: "publishable" }  // ❌
+{ "x-publishable-api-key": token }  // ❌
+// RIGHT
+{ type: ApiKeyType.CLIENT }
+{ [CLIENT_API_KEY_HEADER]: token }
 
-**HTTP routes:** Cannot be tested with `pluginIntegrationTestRunner`. Mount the plugin in a host app and use `acmekitIntegrationTestRunner` there.
+// WRONG — unused imports, JSDoc blocks, type casts in tests
+```