@forinda/kickjs-testing 7.0.2 → 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -4
- package/dist/index.d.mts +39 -20
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -19,17 +19,39 @@ import { MockUserRepository } from './mocks'
|
|
|
19
19
|
|
|
20
20
|
describe('UserController', () => {
|
|
21
21
|
it('lists users', async () => {
|
|
22
|
-
const {
|
|
23
|
-
modules: [UserModule],
|
|
24
|
-
overrides:
|
|
22
|
+
const { app } = await createTestApp({
|
|
23
|
+
modules: [UserModule()],
|
|
24
|
+
overrides: [[USER_REPO, new MockUserRepository()]],
|
|
25
25
|
})
|
|
26
26
|
|
|
27
|
-
const res = await supertest(
|
|
27
|
+
const res = await supertest(app.handle.bind(app)).get('/api/v1/users')
|
|
28
28
|
expect(res.status).toBe(200)
|
|
29
29
|
})
|
|
30
30
|
})
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
+
Drive `app.handle` — it is the Application's own request listener and follows
|
|
34
|
+
whichever runtime is configured. (`expressApp` is deprecated and throws under
|
|
35
|
+
Fastify or h3.)
|
|
36
|
+
|
|
37
|
+
## Test the engine you deploy
|
|
38
|
+
|
|
39
|
+
Pass `runtime`, the same value you give `bootstrap()`. Routing, body parsing,
|
|
40
|
+
status handling and error mapping all live in the runtime seam, so a green
|
|
41
|
+
Express suite says nothing about them if you ship Fastify:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import { fastifyRuntime } from '@forinda/kickjs/fastify'
|
|
45
|
+
|
|
46
|
+
const { app } = await createTestApp({
|
|
47
|
+
modules: [UserModule()],
|
|
48
|
+
runtime: fastifyRuntime(),
|
|
49
|
+
})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`overrides` takes entries or a `Map` as well as an object — a `createToken()`
|
|
53
|
+
token is a frozen object, which TypeScript rejects as a computed key.
|
|
54
|
+
|
|
33
55
|
## Documentation
|
|
34
56
|
|
|
35
57
|
[kickjs.app/guide/testing](https://kickjs.app/guide/testing)
|
package/dist/index.d.mts
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
|
|
2
|
+
import { AppAdapter, AppModuleClass, AppModuleEntry, Application, ApplicationOptions, Container, ContextDecorator, ContextMetaKey, ContributorRegistration, ExecutionContext, KickPlugin, MetaValue, ModuleRoutes } from "@forinda/kickjs";
|
|
2
3
|
import express from "express";
|
|
3
|
-
import { AppAdapter, AppModuleClass, AppModuleEntry, Application, ApplicationOptions, Container, ContextDecorator, ContributorRegistration, ExecutionContext, KickPlugin, MetaValue, ModuleRoutes } from "@forinda/kickjs";
|
|
4
|
-
|
|
5
4
|
//#region src/index.d.ts
|
|
6
5
|
/**
|
|
7
6
|
* Bootstrap options forwarded verbatim to the underlying Application so
|
|
8
7
|
* test apps exercise the same HTTP pipeline shape as production.
|
|
9
8
|
*/
|
|
10
|
-
type BootstrapPassthroughOptions = Pick<ApplicationOptions, 'port' | 'apiPrefix' | 'defaultVersion' | '
|
|
9
|
+
type BootstrapPassthroughOptions = Pick<ApplicationOptions, 'port' | 'apiPrefix' | 'defaultVersion' | 'middlewares' | 'onError' | 'onNotFound' | 'plugins' | 'trustProxy' | 'jsonLimit' | 'security' | 'contributors' | 'contextStore' | 'runtime' | 'health'>;
|
|
11
10
|
/**
|
|
12
11
|
* Options for creating a test application.
|
|
13
12
|
* Disables helmet, cors, compression, and morgan by default.
|
|
@@ -22,8 +21,35 @@ interface CreateTestAppOptions extends BootstrapPassthroughOptions {
|
|
|
22
21
|
modules: AppModuleEntry[];
|
|
23
22
|
/** Adapters to attach (auth, queue, devtools, etc.) */
|
|
24
23
|
adapters?: AppAdapter[];
|
|
25
|
-
/**
|
|
26
|
-
|
|
24
|
+
/**
|
|
25
|
+
* DI overrides applied after module registration.
|
|
26
|
+
*
|
|
27
|
+
* An object literal covers string and symbol keys. It cannot cover
|
|
28
|
+
* `createToken()`, though — a token is a frozen OBJECT identified by
|
|
29
|
+
* reference, and TypeScript rejects an object as a computed key
|
|
30
|
+
* (`TS2464: A computed property name must be of type 'string', 'number',
|
|
31
|
+
* 'symbol', or 'any'`). Since tokens are the documented way to bind an
|
|
32
|
+
* interface to an implementation, that excluded exactly the key type most
|
|
33
|
+
* worth overriding in a test.
|
|
34
|
+
*
|
|
35
|
+
* Worse, the obvious workaround compiles and does nothing: `[TOKEN.name]` is
|
|
36
|
+
* a string, and the container keys tokens by reference, so the override is
|
|
37
|
+
* accepted and never applied.
|
|
38
|
+
*
|
|
39
|
+
* Pass entries to override a token:
|
|
40
|
+
*
|
|
41
|
+
* ```ts
|
|
42
|
+
* const DATABASE = createToken<Database>('app/Db/connection')
|
|
43
|
+
*
|
|
44
|
+
* await createTestApp({
|
|
45
|
+
* modules: [UserModule()],
|
|
46
|
+
* overrides: [[DATABASE, fakeDb()]],
|
|
47
|
+
* })
|
|
48
|
+
* ```
|
|
49
|
+
*
|
|
50
|
+
* A `Map` works too. The object form is unchanged.
|
|
51
|
+
*/
|
|
52
|
+
overrides?: Record<symbol | string, any> | ReadonlyArray<readonly [token: unknown, value: unknown]> | ReadonlyMap<unknown, unknown>;
|
|
27
53
|
/**
|
|
28
54
|
* Use an isolated container instead of the global singleton.
|
|
29
55
|
* Prevents concurrent tests from interfering with each other's DI state.
|
|
@@ -31,22 +57,15 @@ interface CreateTestAppOptions extends BootstrapPassthroughOptions {
|
|
|
31
57
|
*/
|
|
32
58
|
isolated?: boolean;
|
|
33
59
|
}
|
|
34
|
-
/**
|
|
35
|
-
* Create an Application instance configured for testing.
|
|
36
|
-
* Resets the DI container, registers modules, applies overrides,
|
|
37
|
-
* and returns both the Application and its Express app.
|
|
38
|
-
*
|
|
39
|
-
* @example
|
|
40
|
-
* ```ts
|
|
41
|
-
* const { expressApp, container } = await createTestApp({
|
|
42
|
-
* modules: [UserModule],
|
|
43
|
-
* overrides: { [USER_REPO]: new InMemoryUserRepo() },
|
|
44
|
-
* })
|
|
45
|
-
* const res = await request(expressApp).get('/api/v1/users')
|
|
46
|
-
* ```
|
|
47
|
-
*/
|
|
48
60
|
declare function createTestApp(options: CreateTestAppOptions): Promise<{
|
|
49
61
|
app: Application;
|
|
62
|
+
/**
|
|
63
|
+
* @deprecated Use `app.handle.bind(app)`. Only valid under the Express
|
|
64
|
+
* runtime — under
|
|
65
|
+
* any other engine this throws rather than handing back that engine's
|
|
66
|
+
* instance mistyped as `express.Express`, which is how a suite ends up
|
|
67
|
+
* silently exercising the wrong runtime.
|
|
68
|
+
*/
|
|
50
69
|
expressApp: express.Express;
|
|
51
70
|
container: Container;
|
|
52
71
|
}>;
|
|
@@ -135,7 +154,7 @@ interface RunContributorResult<K extends string> {
|
|
|
135
154
|
* expect(value).toEqual({ id: 'p-1', tenantId: 't-1' })
|
|
136
155
|
* ```
|
|
137
156
|
*/
|
|
138
|
-
declare function runContributor<K extends
|
|
157
|
+
declare function runContributor<K extends ContextMetaKey, D extends Record<string, any> = Record<string, never>>(decorator: ContextDecorator<K, D>, options?: RunContributorOptions): Promise<RunContributorResult<K>>;
|
|
139
158
|
/**
|
|
140
159
|
* Options for {@link createTestPlugin}.
|
|
141
160
|
*/
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;KAyBK,8BAA8B,KACjC;;;;;UA0Be,6BAA6B;;;;;;;EAO5C,SAAS;;EAET,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BX,YACI,+BACA,wBAAwB,gBAAgB,mBACxC;;;;;;EAMJ;;iBA6CoB,cAAc,SAAS,uBAAuB;EAClE,KAAK;;;;;;;;EAQL,YAAY,QAAQ;EACpB,WAAW;;;;;;;;;;;;;;;;;iBAqGG,iBAAiB;EAC/B,WAAW,WAAW;EACtB,cAAc,eAAe;IAC3B;;;;UAiBa;;;;;;;;;EASf,OAAO;;;;;;;EAQP,UAAU;;EAGV;;;;;UAMe,qBAAqB;;EAEpC,OAAO,UAAU;;EAEjB,KAAK;;;;;;EAML,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Bc,eACpB,UAAU,gBACV,UAAU,sBAAsB,uBAEhC,WAAW,iBAAiB,GAAG,IAC/B,UAAS,wBACR,QAAQ,qBAAqB;;;;UA+Bf;;;;;;EAMf;;;;;;EAOA;;;;;;;;UASe;;WAEN,QAAQ;;WAER,WAAW;;;;;EAMpB,eAAe;;;;;EAMf,YAAY;;;;;;;EAQZ,WAAW;;;;;EAMX,YAAY;;;;EAKZ;;;;;EAMA,gBAAgB;;;;;EAMhB,YAAY,UAAU,0BAA0B;;;;;;;EAQhD,gBAAgB,KAAK,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BpB,iBACpB,QAAQ,YACR,UAAS,0BACR,QAAQ;;cAoEE,mBAAU"}
|
package/dist/index.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @forinda/kickjs-testing
|
|
2
|
+
* @forinda/kickjs-testing v8.0.0
|
|
3
3
|
*
|
|
4
4
|
* Copyright (c) Felix Orinda
|
|
5
5
|
*
|
|
@@ -8,5 +8,5 @@
|
|
|
8
8
|
*
|
|
9
9
|
* @license MIT
|
|
10
10
|
*/
|
|
11
|
-
import
|
|
11
|
+
import{Application,Container,MissingContextValueError,buildPipeline,runContributors}from"@forinda/kickjs";function overrideEntries(overrides){if(Array.isArray(overrides))return overrides.map(([token,value])=>[token,value]);if(overrides instanceof Map)return[...overrides.entries()];let record=overrides;return Reflect.ownKeys(record).map(key=>[key,record[key]])}async function createTestApp(options){let container;options.isolated?container=Container.create():(Container.reset(),container=Container.getInstance());let app=new Application({modules:options.modules,adapters:options.adapters,port:options.port,apiPrefix:options.apiPrefix,defaultVersion:options.defaultVersion,middlewares:options.middlewares,onError:options.onError,onNotFound:options.onNotFound,plugins:options.plugins,trustProxy:options.trustProxy,jsonLimit:options.jsonLimit,security:options.security,contributors:options.contributors,contextStore:options.contextStore,runtime:options.runtime,health:options.health});if(await Promise.resolve(app.setup()),options.isolated){for(let entry of options.modules)(typeof entry==`function`?new entry:entry).register?.(container);container.bootstrap()}if(options.overrides)for(let[token,value]of overrideEntries(options.overrides))container.registerInstance(token,value);let runtimeName=app.getActiveRuntime().name;return{app,get expressApp(){if(runtimeName!==`express`)throw Error(`createTestApp: 'expressApp' is only available under the Express runtime — this app is running '${runtimeName}'. Drive the app instead, which follows whichever engine is configured: request(app.handle.bind(app)).get('/...').`);return app.getExpressApp()},container}}function createTestModule(config){class TestModule{register(container){config.register(container)}routes(){return config.routes()}}return TestModule}async function runContributor(decorator,options={}){let meta=new Map(Object.entries(options.initial??{})),ctx={get(key){return meta.get(key)},require(key){let value=meta.get(key);if(value===void 0)throw new MissingContextValueError(key);return value},set(key,value){meta.set(key,value)},requestId:options.requestId??`test-req`},value=await decorator.registration.resolve(ctx,options.deps??{});return meta.set(decorator.registration.key,value),{value,ctx,meta}}async function createTestPlugin(plugin,options={}){let container=options.isolated??!0?Container.create():(Container.reset(),Container.getInstance());return options.skipRegister||plugin.register?.(container),{plugin,container,async callOnReady(){await plugin.onReady?.(container)},async shutdown(){await plugin.shutdown?.()},modules(){return plugin.modules?.()??[]},adapters(){return plugin.adapters?.()??[]},middleware(){return plugin.middleware?.()??[]},contributors(){return[...plugin.contributors?.()??[]]},makeContext(initial={}){let meta=new Map(Object.entries(initial));return{get(key){return meta.get(key)},require(key){let value=meta.get(key);if(value===void 0)throw new MissingContextValueError(key);return value},set(key,value){meta.set(key,value)},requestId:`test-req`}},async runContributors(ctx){await runContributors({pipeline:buildPipeline([...plugin.contributors?.()??[]].map(registration=>({registration,source:`adapter`,label:plugin.name}))),ctx,container})}}}const testPlugin=createTestPlugin;export{createTestApp,createTestModule,createTestPlugin,runContributor,testPlugin};
|
|
12
12
|
//# sourceMappingURL=index.mjs.map
|
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import express from 'express'\nimport {\n Application,\n Container,\n buildPipeline,\n runContributors,\n type AppAdapter,\n type AppModule,\n type AppModuleClass,\n type AppModuleEntry,\n type ApplicationOptions,\n type ContextDecorator,\n type ContributorRegistration,\n type ExecutionContext,\n MissingContextValueError,\n type KickPlugin,\n type MetaValue,\n type ModuleRoutes,\n} from '@forinda/kickjs'\n\n/**\n * Bootstrap options forwarded verbatim to the underlying Application so\n * test apps exercise the same HTTP pipeline shape as production.\n */\ntype BootstrapPassthroughOptions = Pick<\n ApplicationOptions,\n | 'port'\n | 'apiPrefix'\n | 'defaultVersion'\n | 'middleware'\n | 'onError'\n | 'onNotFound'\n | 'plugins'\n | 'trustProxy'\n | 'jsonLimit'\n | 'security'\n | 'contributors'\n | 'contextStore'\n>\n\n/**\n * Options for creating a test application.\n * Disables helmet, cors, compression, and morgan by default.\n */\nexport interface CreateTestAppOptions extends BootstrapPassthroughOptions {\n /**\n * Modules registered for the test run. Accepts both legacy class form\n * (`UserModule extends AppModule`) and `defineModule` factory output\n * (call the factory: `UserModule()`) — `Application` discriminates\n * at boot.\n */\n modules: AppModuleEntry[]\n /** Adapters to attach (auth, queue, devtools, etc.) */\n adapters?: AppAdapter[]\n /** DI overrides applied after module registration. Supports both string and symbol keys. */\n overrides?: Record<symbol | string, any>\n /**\n * Use an isolated container instead of the global singleton.\n * Prevents concurrent tests from interfering with each other's DI state.\n * When true, Container.create() is used instead of Container.reset() + getInstance().\n */\n isolated?: boolean\n}\n\n/**\n * Create an Application instance configured for testing.\n * Resets the DI container, registers modules, applies overrides,\n * and returns both the Application and its Express app.\n *\n * @example\n * ```ts\n * const { expressApp, container } = await createTestApp({\n * modules: [UserModule],\n * overrides: { [USER_REPO]: new InMemoryUserRepo() },\n * })\n * const res = await request(expressApp).get('/api/v1/users')\n * ```\n */\nexport async function createTestApp(options: CreateTestAppOptions): Promise<{\n app: Application\n expressApp: express.Express\n container: Container\n}> {\n let container: Container\n if (options.isolated) {\n // Isolated container — safe for concurrent tests\n container = Container.create()\n } else {\n // Global singleton — reset for serial test isolation (default)\n Container.reset()\n container = Container.getInstance()\n }\n\n const app = new Application({\n modules: options.modules,\n adapters: options.adapters,\n port: options.port,\n apiPrefix: options.apiPrefix,\n defaultVersion: options.defaultVersion,\n // Use provided middleware, or default to JSON body parsing only\n middleware: options.middleware ?? [express.json()],\n onError: options.onError,\n onNotFound: options.onNotFound,\n plugins: options.plugins,\n trustProxy: options.trustProxy,\n jsonLimit: options.jsonLimit,\n security: options.security,\n contributors: options.contributors,\n contextStore: options.contextStore,\n })\n\n // Run setup — mounts routes, registers modules, initializes adapters.\n // Awaited to support future async adapter hooks.\n await Promise.resolve(app.setup())\n\n // When using an isolated container, Application.setup() registers modules\n // on the global singleton (Container.getInstance()). Re-register them on\n // the isolated container so that bindings are available there too.\n if (options.isolated) {\n for (const entry of options.modules) {\n // Discriminate class vs instance — `defineModule` factories return\n // AppModule instances, legacy classes need `new`. Same dispatch\n // Application.setup() runs at boot.\n const mod: AppModule = typeof entry === 'function' ? new (entry as AppModuleClass)() : entry\n // register() is optional — see AppModule docs\n mod.register?.(container)\n }\n container.bootstrap()\n }\n\n // Apply DI overrides AFTER setup so they take precedence over\n // bindings registered by modules during register().\n if (options.overrides) {\n for (const token of Reflect.ownKeys(options.overrides)) {\n container.registerInstance(token, options.overrides[token as any])\n }\n }\n\n return {\n app,\n expressApp: app.getExpressApp(),\n container,\n }\n}\n\n/**\n * Build a quick TestModule that explicitly registers dependencies.\n * Useful for integration tests that need to control the DI graph.\n *\n * @example\n * ```ts\n * const TestModule = createTestModule({\n * register: (c) => {\n * c.registerFactory(USER_REPO, () => new InMemoryUserRepo())\n * c.register(UserController)\n * },\n * routes: () => buildRoutes(UserController, '/users'),\n * })\n * ```\n */\nexport function createTestModule(config: {\n register: (container: Container) => void\n routes: () => ModuleRoutes | ModuleRoutes[] | null\n}): AppModuleClass {\n class TestModule implements AppModule {\n register(container: Container) {\n config.register(container)\n }\n routes() {\n return config.routes()\n }\n }\n return TestModule\n}\n\n// ── Context Contributor unit-test helper (#107) ─────────────────────────\n\n/**\n * Options for {@link runContributor}.\n */\nexport interface RunContributorOptions {\n /**\n * Resolved deps passed to `resolve(ctx, deps)`. Skips the DI container\n * entirely — bypass for unit tests that want to assert pure resolve()\n * behaviour without standing up a container.\n *\n * Property names must match the spec's `deps` keys; values can be real\n * service instances, mocks, or test doubles.\n */\n deps?: Record<string, unknown>\n\n /**\n * Pre-populate the fake context's metadata Map. Useful for testing\n * contributors with `dependsOn` without running the full pipeline:\n * pre-populate the dependency keys, then assert that `resolve()` reads\n * them and produces the expected output.\n */\n initial?: Record<string, unknown>\n\n /** Override the fake context's `requestId` (default: `'test-req'`). */\n requestId?: string\n}\n\n/**\n * Result of {@link runContributor}.\n */\nexport interface RunContributorResult<K extends string> {\n /** Value returned by the contributor's `resolve()` call. */\n value: MetaValue<K>\n /** The fake `ExecutionContext` used during the run. */\n ctx: ExecutionContext\n /**\n * Final state of the fake context's metadata Map after `resolve()`.\n * Includes any `ctx.set(...)` calls the resolver made plus the final\n * resolved value under the contributor's own key.\n */\n meta: Map<string, unknown>\n}\n\n/**\n * Run a single context contributor in isolation against a fake\n * {@link ExecutionContext}. Skips the container, the topo-sort, and the\n * §20.9 error matrix — calls `decorator.registration.resolve(ctx, deps)`\n * directly so unit tests can assert pure resolve behaviour.\n *\n * Errors thrown by `resolve()` propagate so tests can `expect(...).rejects`\n * or `await expect(...).rejects.toThrow()` against them. To exercise the\n * full error matrix (optional skip, onError replacement, etc.), build a\n * one-element pipeline with `buildPipeline()` and use `runContributors()`\n * directly.\n *\n * @example\n * ```ts\n * const LoadProject = defineContextDecorator({\n * key: 'project',\n * dependsOn: ['tenant'],\n * deps: { repo: ProjectRepo },\n * resolve: (ctx, { repo }) => repo.findByTenant(ctx.get('tenant')!.id),\n * })\n *\n * const { value } = await runContributor(LoadProject, {\n * initial: { tenant: { id: 't-1' } },\n * deps: { repo: new InMemoryProjectRepo([{ id: 'p-1', tenantId: 't-1' }]) },\n * })\n * expect(value).toEqual({ id: 'p-1', tenantId: 't-1' })\n * ```\n */\nexport async function runContributor<\n K extends string,\n D extends Record<string, any> = Record<string, never>,\n>(\n decorator: ContextDecorator<K, D>,\n options: RunContributorOptions = {},\n): Promise<RunContributorResult<K>> {\n const meta = new Map<string, unknown>(Object.entries(options.initial ?? {}))\n const ctx: ExecutionContext = {\n get(key) {\n return meta.get(key) as never\n },\n require(key) {\n // Same contract as RequestContext.require — a resolver under test\n // that depends on an upstream key should fail here exactly the way\n // it would in production, not read `undefined`.\n const value = meta.get(key)\n if (value === undefined) throw new MissingContextValueError(key)\n return value as never\n },\n set(key, value) {\n meta.set(key, value)\n },\n requestId: options.requestId ?? 'test-req',\n }\n\n const value = await decorator.registration.resolve(ctx, (options.deps ?? {}) as never)\n meta.set(decorator.registration.key, value)\n\n return { value: value as MetaValue<K>, ctx, meta }\n}\n\n// ── Plugin unit-test harness (architecture.md §21.3.2) ──────────────────\n\n/**\n * Options for {@link createTestPlugin}.\n */\nexport interface CreateTestPluginOptions {\n /**\n * Use an isolated container (default: `true`). Isolated harnesses never\n * touch the global `Container.getInstance()` singleton, so concurrent\n * tests can run without stomping each other's DI state.\n */\n isolated?: boolean\n\n /**\n * Skip auto-invoking `plugin.register(container)` — useful when a test\n * wants to assert container state *before* the plugin touches it.\n * Defaults to `false` (register is called eagerly).\n */\n skipRegister?: boolean\n}\n\n/**\n * Result of {@link createTestPlugin}. Mirrors the spec sketch in\n * `architecture.md` §21.3.2 — `.container`, lifecycle invokers, and a\n * `runContributors()` helper that builds a one-plugin pipeline against a\n * fake `ExecutionContext`.\n */\nexport interface PluginTestHarness {\n /** The plugin under test — exposed for direct introspection. */\n readonly plugin: KickPlugin\n /** Isolated (or shared) DI container the plugin registered into. */\n readonly container: Container\n\n /**\n * Invoke `plugin.onReady(container)`. No-op if the plugin does not\n * define the hook.\n */\n callOnReady(): Promise<void>\n\n /**\n * Invoke `plugin.shutdown()`. No-op if the plugin does not define the\n * hook.\n */\n shutdown(): Promise<void>\n\n /**\n * Returns the module classes the plugin ships via `plugin.modules?()`.\n * The harness does **not** auto-instantiate them — use `createTestApp`\n * for that. Useful for assertions like \"the plugin exposes the module I\n * expect\".\n */\n modules(): AppModuleEntry[]\n\n /**\n * Returns adapter instances the plugin ships via `plugin.adapters?()`.\n * Useful for testing the adapters alongside the plugin's DI bindings.\n */\n adapters(): AppAdapter[]\n\n /**\n * Returns middleware entries the plugin ships via `plugin.middleware?()`.\n */\n middleware(): any[]\n\n /**\n * Returns contributor registrations the plugin ships via\n * `plugin.contributors?()`.\n */\n contributors(): ContributorRegistration[]\n\n /**\n * Build a fake {@link ExecutionContext} pre-populated with the given\n * metadata. Symmetric with {@link runContributor}'s fake context.\n */\n makeContext(initial?: Record<string, unknown>): ExecutionContext\n\n /**\n * Run every contributor the plugin ships through a built pipeline\n * against the given context. Dependencies resolve through the harness's\n * container (same path production uses). Throws if the plugin's\n * contributors reference `dependsOn` keys no one in the plugin provides.\n */\n runContributors(ctx: ExecutionContext): Promise<void>\n}\n\n/**\n * Build an isolated test harness around a single {@link KickPlugin}.\n * Skips the full HTTP layer — symmetric with {@link runContributor} for\n * contributors and {@link createTestApp} for integration runs.\n *\n * @example\n * ```ts\n * const harness = await createTestPlugin(FlagsPlugin({ provider: scripted }))\n *\n * // The plugin's register() already ran — resolve any bindings.\n * const flags = harness.container.resolve(FLAGS_SERVICE)\n *\n * // Drive the post-bootstrap lifecycle.\n * await harness.callOnReady()\n *\n * // Exercise contributors shipped by the plugin.\n * const ctx = harness.makeContext({ requestId: 'req-1' })\n * await harness.runContributors(ctx)\n * expect(ctx.get('flags')).toEqual({ beta: true })\n *\n * await harness.shutdown()\n * ```\n */\nexport async function createTestPlugin(\n plugin: KickPlugin,\n options: CreateTestPluginOptions = {},\n): Promise<PluginTestHarness> {\n const isolated = options.isolated ?? true\n\n const container = isolated ? Container.create() : (Container.reset(), Container.getInstance())\n\n if (!options.skipRegister) plugin.register?.(container)\n\n return {\n plugin,\n container,\n\n async callOnReady() {\n await plugin.onReady?.(container)\n },\n\n async shutdown() {\n await plugin.shutdown?.()\n },\n\n modules() {\n return plugin.modules?.() ?? []\n },\n\n adapters() {\n return plugin.adapters?.() ?? []\n },\n\n middleware() {\n return plugin.middleware?.() ?? []\n },\n\n contributors() {\n return [...(plugin.contributors?.() ?? [])]\n },\n\n makeContext(initial: Record<string, unknown> = {}) {\n const meta = new Map<string, unknown>(Object.entries(initial))\n const ctx: ExecutionContext = {\n get(key) {\n return meta.get(key) as never\n },\n require(key) {\n const value = meta.get(key)\n if (value === undefined) throw new MissingContextValueError(key)\n return value as never\n },\n set(key, value) {\n meta.set(key, value)\n },\n requestId: 'test-req',\n }\n return ctx\n },\n\n async runContributors(ctx: ExecutionContext) {\n const regs = plugin.contributors?.() ?? []\n const sources = [...regs].map((registration) => ({\n registration,\n source: 'adapter' as const,\n label: plugin.name,\n }))\n const pipeline = buildPipeline(sources)\n await runContributors({ pipeline, ctx, container })\n },\n }\n}\n\n/** Alias for {@link createTestPlugin}, matching the `testPlugin` name used in the architecture spec. */\nexport const testPlugin = createTestPlugin\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import express from 'express'\nimport {\n Application,\n Container,\n buildPipeline,\n runContributors,\n type AppAdapter,\n type AppModule,\n type AppModuleClass,\n type AppModuleEntry,\n type ApplicationOptions,\n type ContextDecorator,\n type ContextMetaKey,\n type ContributorRegistration,\n type ExecutionContext,\n MissingContextValueError,\n type KickPlugin,\n type MetaValue,\n type ModuleRoutes,\n} from '@forinda/kickjs'\n\n/**\n * Bootstrap options forwarded verbatim to the underlying Application so\n * test apps exercise the same HTTP pipeline shape as production.\n */\ntype BootstrapPassthroughOptions = Pick<\n ApplicationOptions,\n | 'port'\n | 'apiPrefix'\n | 'defaultVersion'\n | 'middlewares'\n | 'onError'\n | 'onNotFound'\n | 'plugins'\n | 'trustProxy'\n | 'jsonLimit'\n | 'security'\n | 'contributors'\n | 'contextStore'\n // The engine under test. Without this every test ran Express while\n // production ran Fastify or h3 — the one thing an integration test exists\n // to rule out.\n | 'runtime'\n // Without this the option is accepted by the type and dropped on the way\n // through, so `health: false` silently kept the endpoints mounted.\n | 'health'\n>\n\n/**\n * Options for creating a test application.\n * Disables helmet, cors, compression, and morgan by default.\n */\nexport interface CreateTestAppOptions extends BootstrapPassthroughOptions {\n /**\n * Modules registered for the test run. Accepts both legacy class form\n * (`UserModule extends AppModule`) and `defineModule` factory output\n * (call the factory: `UserModule()`) — `Application` discriminates\n * at boot.\n */\n modules: AppModuleEntry[]\n /** Adapters to attach (auth, queue, devtools, etc.) */\n adapters?: AppAdapter[]\n /**\n * DI overrides applied after module registration.\n *\n * An object literal covers string and symbol keys. It cannot cover\n * `createToken()`, though — a token is a frozen OBJECT identified by\n * reference, and TypeScript rejects an object as a computed key\n * (`TS2464: A computed property name must be of type 'string', 'number',\n * 'symbol', or 'any'`). Since tokens are the documented way to bind an\n * interface to an implementation, that excluded exactly the key type most\n * worth overriding in a test.\n *\n * Worse, the obvious workaround compiles and does nothing: `[TOKEN.name]` is\n * a string, and the container keys tokens by reference, so the override is\n * accepted and never applied.\n *\n * Pass entries to override a token:\n *\n * ```ts\n * const DATABASE = createToken<Database>('app/Db/connection')\n *\n * await createTestApp({\n * modules: [UserModule()],\n * overrides: [[DATABASE, fakeDb()]],\n * })\n * ```\n *\n * A `Map` works too. The object form is unchanged.\n */\n overrides?:\n | Record<symbol | string, any>\n | ReadonlyArray<readonly [token: unknown, value: unknown]>\n | ReadonlyMap<unknown, unknown>\n /**\n * Use an isolated container instead of the global singleton.\n * Prevents concurrent tests from interfering with each other's DI state.\n * When true, Container.create() is used instead of Container.reset() + getInstance().\n */\n isolated?: boolean\n}\n\n/**\n * Create an Application instance configured for testing.\n * Resets the DI container, registers modules, applies overrides,\n * and returns the Application, which drives whichever runtime is configured.\n *\n * Drive it through `app` — `app.handle` is the Application's own Node request\n * listener and follows whichever runtime is configured, so the same test runs\n * against the engine you actually deploy.\n *\n * @example\n * ```ts\n * const { app, container } = await createTestApp({\n * modules: [UserModule],\n * overrides: { [USER_REPO]: new InMemoryUserRepo() },\n * })\n * const res = await request(app.handle.bind(app)).get('/api/v1/users')\n * ```\n *\n * @example Test the engine you actually deploy\n * ```ts\n * import { fastifyRuntime } from '@forinda/kickjs/fastify'\n *\n * const { app } = await createTestApp({ modules: [UserModule], runtime: fastifyRuntime() })\n * const res = await request(app.handle.bind(app)).get('/api/v1/users')\n * ```\n */\n/**\n * Normalize every accepted `overrides` shape to `[token, value]` pairs.\n *\n * An array or Map keeps the token's identity, which is what the container\n * matches on; an object literal is limited to string and symbol keys by the\n * language itself.\n */\nfunction overrideEntries(\n overrides: NonNullable<CreateTestAppOptions['overrides']>,\n): Array<[unknown, unknown]> {\n if (Array.isArray(overrides)) return overrides.map(([token, value]) => [token, value])\n if (overrides instanceof Map) return [...overrides.entries()]\n const record = overrides as Record<symbol | string, unknown>\n return Reflect.ownKeys(record).map((key) => [key, record[key as never]])\n}\n\nexport async function createTestApp(options: CreateTestAppOptions): Promise<{\n app: Application\n /**\n * @deprecated Use `app.handle.bind(app)`. Only valid under the Express\n * runtime — under\n * any other engine this throws rather than handing back that engine's\n * instance mistyped as `express.Express`, which is how a suite ends up\n * silently exercising the wrong runtime.\n */\n expressApp: express.Express\n container: Container\n}> {\n let container: Container\n if (options.isolated) {\n // Isolated container — safe for concurrent tests\n container = Container.create()\n } else {\n // Global singleton — reset for serial test isolation (default)\n Container.reset()\n container = Container.getInstance()\n }\n\n const app = new Application({\n modules: options.modules,\n adapters: options.adapters,\n port: options.port,\n apiPrefix: options.apiPrefix,\n defaultVersion: options.defaultVersion,\n // Left undefined so the Application applies its OWN defaults, including\n // the shared body-parsing policy (#590). Naming a middleware list here\n // put the Application on its user-declared branch, so a test app parsed\n // only `application/json` while the same app in production also parsed\n // `+json`, forms and text — the harness quietly tested a different\n // pipeline. The Application already guards on\n // `RuntimeCapabilities.nativeBodyParsing`, which is what kept a connect\n // parser off Fastify and h3.\n middlewares: options.middlewares,\n onError: options.onError,\n onNotFound: options.onNotFound,\n plugins: options.plugins,\n trustProxy: options.trustProxy,\n jsonLimit: options.jsonLimit,\n security: options.security,\n contributors: options.contributors,\n contextStore: options.contextStore,\n // Without this the option is accepted and ignored, which is worse than\n // not offering it: the suite reports Express while claiming Fastify.\n runtime: options.runtime,\n health: options.health,\n })\n\n // Run setup — mounts routes, registers modules, initializes adapters.\n // Awaited to support future async adapter hooks.\n await Promise.resolve(app.setup())\n\n // When using an isolated container, Application.setup() registers modules\n // on the global singleton (Container.getInstance()). Re-register them on\n // the isolated container so that bindings are available there too.\n if (options.isolated) {\n for (const entry of options.modules) {\n // Discriminate class vs instance — `defineModule` factories return\n // AppModule instances, legacy classes need `new`. Same dispatch\n // Application.setup() runs at boot.\n const mod: AppModule = typeof entry === 'function' ? new (entry as AppModuleClass)() : entry\n // register() is optional — see AppModule docs\n mod.register?.(container)\n }\n container.bootstrap()\n }\n\n // Apply DI overrides AFTER setup so they take precedence over\n // bindings registered by modules during register().\n if (options.overrides) {\n for (const [token, value] of overrideEntries(options.overrides)) {\n container.registerInstance(token, value)\n }\n }\n\n const runtimeName = app.getActiveRuntime().name\n\n return {\n app,\n get expressApp(): express.Express {\n if (runtimeName !== 'express') {\n throw new Error(\n `createTestApp: 'expressApp' is only available under the Express runtime — ` +\n `this app is running '${runtimeName}'. Drive the app instead, which follows ` +\n `whichever engine is configured: request(app.handle.bind(app)).get('/...').`,\n )\n }\n return app.getExpressApp()\n },\n container,\n }\n}\n\n/**\n * Build a quick TestModule that explicitly registers dependencies.\n * Useful for integration tests that need to control the DI graph.\n *\n * @example\n * ```ts\n * const TestModule = createTestModule({\n * register: (c) => {\n * c.registerFactory(USER_REPO, () => new InMemoryUserRepo())\n * c.register(UserController)\n * },\n * routes: () => buildRoutes(UserController, '/users'),\n * })\n * ```\n */\nexport function createTestModule(config: {\n register: (container: Container) => void\n routes: () => ModuleRoutes | ModuleRoutes[] | null\n}): AppModuleClass {\n class TestModule implements AppModule {\n register(container: Container) {\n config.register(container)\n }\n routes() {\n return config.routes()\n }\n }\n return TestModule\n}\n\n// ── Context Contributor unit-test helper (#107) ─────────────────────────\n\n/**\n * Options for {@link runContributor}.\n */\nexport interface RunContributorOptions {\n /**\n * Resolved deps passed to `resolve(ctx, deps)`. Skips the DI container\n * entirely — bypass for unit tests that want to assert pure resolve()\n * behaviour without standing up a container.\n *\n * Property names must match the spec's `deps` keys; values can be real\n * service instances, mocks, or test doubles.\n */\n deps?: Record<string, unknown>\n\n /**\n * Pre-populate the fake context's metadata Map. Useful for testing\n * contributors with `dependsOn` without running the full pipeline:\n * pre-populate the dependency keys, then assert that `resolve()` reads\n * them and produces the expected output.\n */\n initial?: Record<string, unknown>\n\n /** Override the fake context's `requestId` (default: `'test-req'`). */\n requestId?: string\n}\n\n/**\n * Result of {@link runContributor}.\n */\nexport interface RunContributorResult<K extends string> {\n /** Value returned by the contributor's `resolve()` call. */\n value: MetaValue<K>\n /** The fake `ExecutionContext` used during the run. */\n ctx: ExecutionContext\n /**\n * Final state of the fake context's metadata Map after `resolve()`.\n * Includes any `ctx.set(...)` calls the resolver made plus the final\n * resolved value under the contributor's own key.\n */\n meta: Map<string, unknown>\n}\n\n/**\n * Run a single context contributor in isolation against a fake\n * {@link ExecutionContext}. Skips the container, the topo-sort, and the\n * §20.9 error matrix — calls `decorator.registration.resolve(ctx, deps)`\n * directly so unit tests can assert pure resolve behaviour.\n *\n * Errors thrown by `resolve()` propagate so tests can `expect(...).rejects`\n * or `await expect(...).rejects.toThrow()` against them. To exercise the\n * full error matrix (optional skip, onError replacement, etc.), build a\n * one-element pipeline with `buildPipeline()` and use `runContributors()`\n * directly.\n *\n * @example\n * ```ts\n * const LoadProject = defineContextDecorator({\n * key: 'project',\n * dependsOn: ['tenant'],\n * deps: { repo: ProjectRepo },\n * resolve: (ctx, { repo }) => repo.findByTenant(ctx.get('tenant')!.id),\n * })\n *\n * const { value } = await runContributor(LoadProject, {\n * initial: { tenant: { id: 't-1' } },\n * deps: { repo: new InMemoryProjectRepo([{ id: 'p-1', tenantId: 't-1' }]) },\n * })\n * expect(value).toEqual({ id: 'p-1', tenantId: 't-1' })\n * ```\n */\nexport async function runContributor<\n K extends ContextMetaKey,\n D extends Record<string, any> = Record<string, never>,\n>(\n decorator: ContextDecorator<K, D>,\n options: RunContributorOptions = {},\n): Promise<RunContributorResult<K>> {\n const meta = new Map<string, unknown>(Object.entries(options.initial ?? {}))\n const ctx: ExecutionContext = {\n get(key) {\n return meta.get(key) as never\n },\n require(key) {\n // Same contract as RequestContext.require — a resolver under test\n // that depends on an upstream key should fail here exactly the way\n // it would in production, not read `undefined`.\n const value = meta.get(key)\n if (value === undefined) throw new MissingContextValueError(key)\n return value as never\n },\n set(key, value) {\n meta.set(key, value)\n },\n requestId: options.requestId ?? 'test-req',\n }\n\n const value = await decorator.registration.resolve(ctx, (options.deps ?? {}) as never)\n meta.set(decorator.registration.key, value)\n\n return { value: value as MetaValue<K>, ctx, meta }\n}\n\n// ── Plugin unit-test harness (architecture.md §21.3.2) ──────────────────\n\n/**\n * Options for {@link createTestPlugin}.\n */\nexport interface CreateTestPluginOptions {\n /**\n * Use an isolated container (default: `true`). Isolated harnesses never\n * touch the global `Container.getInstance()` singleton, so concurrent\n * tests can run without stomping each other's DI state.\n */\n isolated?: boolean\n\n /**\n * Skip auto-invoking `plugin.register(container)` — useful when a test\n * wants to assert container state *before* the plugin touches it.\n * Defaults to `false` (register is called eagerly).\n */\n skipRegister?: boolean\n}\n\n/**\n * Result of {@link createTestPlugin}. Mirrors the spec sketch in\n * `architecture.md` §21.3.2 — `.container`, lifecycle invokers, and a\n * `runContributors()` helper that builds a one-plugin pipeline against a\n * fake `ExecutionContext`.\n */\nexport interface PluginTestHarness {\n /** The plugin under test — exposed for direct introspection. */\n readonly plugin: KickPlugin\n /** Isolated (or shared) DI container the plugin registered into. */\n readonly container: Container\n\n /**\n * Invoke `plugin.onReady(container)`. No-op if the plugin does not\n * define the hook.\n */\n callOnReady(): Promise<void>\n\n /**\n * Invoke `plugin.shutdown()`. No-op if the plugin does not define the\n * hook.\n */\n shutdown(): Promise<void>\n\n /**\n * Returns the module classes the plugin ships via `plugin.modules?()`.\n * The harness does **not** auto-instantiate them — use `createTestApp`\n * for that. Useful for assertions like \"the plugin exposes the module I\n * expect\".\n */\n modules(): AppModuleEntry[]\n\n /**\n * Returns adapter instances the plugin ships via `plugin.adapters?()`.\n * Useful for testing the adapters alongside the plugin's DI bindings.\n */\n adapters(): AppAdapter[]\n\n /**\n * Returns middleware entries the plugin ships via `plugin.middleware?()`.\n */\n middleware(): any[]\n\n /**\n * Returns contributor registrations the plugin ships via\n * `plugin.contributors?()`.\n */\n contributors(): ContributorRegistration[]\n\n /**\n * Build a fake {@link ExecutionContext} pre-populated with the given\n * metadata. Symmetric with {@link runContributor}'s fake context.\n */\n makeContext(initial?: Record<string, unknown>): ExecutionContext\n\n /**\n * Run every contributor the plugin ships through a built pipeline\n * against the given context. Dependencies resolve through the harness's\n * container (same path production uses). Throws if the plugin's\n * contributors reference `dependsOn` keys no one in the plugin provides.\n */\n runContributors(ctx: ExecutionContext): Promise<void>\n}\n\n/**\n * Build an isolated test harness around a single {@link KickPlugin}.\n * Skips the full HTTP layer — symmetric with {@link runContributor} for\n * contributors and {@link createTestApp} for integration runs.\n *\n * @example\n * ```ts\n * const harness = await createTestPlugin(FlagsPlugin({ provider: scripted }))\n *\n * // The plugin's register() already ran — resolve any bindings.\n * const flags = harness.container.resolve(FLAGS_SERVICE)\n *\n * // Drive the post-bootstrap lifecycle.\n * await harness.callOnReady()\n *\n * // Exercise contributors shipped by the plugin.\n * const ctx = harness.makeContext({ requestId: 'req-1' })\n * await harness.runContributors(ctx)\n * expect(ctx.get('flags')).toEqual({ beta: true })\n *\n * await harness.shutdown()\n * ```\n */\nexport async function createTestPlugin(\n plugin: KickPlugin,\n options: CreateTestPluginOptions = {},\n): Promise<PluginTestHarness> {\n const isolated = options.isolated ?? true\n\n const container = isolated ? Container.create() : (Container.reset(), Container.getInstance())\n\n if (!options.skipRegister) plugin.register?.(container)\n\n return {\n plugin,\n container,\n\n async callOnReady() {\n await plugin.onReady?.(container)\n },\n\n async shutdown() {\n await plugin.shutdown?.()\n },\n\n modules() {\n return plugin.modules?.() ?? []\n },\n\n adapters() {\n return plugin.adapters?.() ?? []\n },\n\n middleware() {\n return plugin.middleware?.() ?? []\n },\n\n contributors() {\n return [...(plugin.contributors?.() ?? [])]\n },\n\n makeContext(initial: Record<string, unknown> = {}) {\n const meta = new Map<string, unknown>(Object.entries(initial))\n const ctx: ExecutionContext = {\n get(key) {\n return meta.get(key) as never\n },\n require(key) {\n const value = meta.get(key)\n if (value === undefined) throw new MissingContextValueError(key)\n return value as never\n },\n set(key, value) {\n meta.set(key, value)\n },\n requestId: 'test-req',\n }\n return ctx\n },\n\n async runContributors(ctx: ExecutionContext) {\n const regs = plugin.contributors?.() ?? []\n const sources = [...regs].map((registration) => ({\n registration,\n source: 'adapter' as const,\n label: plugin.name,\n }))\n const pipeline = buildPipeline(sources)\n await runContributors({ pipeline, ctx, container })\n },\n }\n}\n\n/** Alias for {@link createTestPlugin}, matching the `testPlugin` name used in the architecture spec. */\nexport const testPlugin = createTestPlugin\n"],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@forinda/kickjs-testing",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "8.0.0",
|
|
4
4
|
"description": "Test utilities, TestModule builder, and helpers for KickJS applications",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"kickjs",
|
|
@@ -33,16 +33,16 @@
|
|
|
33
33
|
"@forinda/kickjs": ">=5.18.0"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@swc/core": "^1.
|
|
36
|
+
"@swc/core": "^1.16.1",
|
|
37
37
|
"@types/express": "^5.0.6",
|
|
38
|
-
"@types/node": "^26.
|
|
39
|
-
"@types/supertest": "^7.2.
|
|
38
|
+
"@types/node": "^26.4.0",
|
|
39
|
+
"@types/supertest": "^7.2.1",
|
|
40
40
|
"express": "^5.1.0",
|
|
41
41
|
"reflect-metadata": "^0.2.2",
|
|
42
42
|
"supertest": "^7.2.2",
|
|
43
|
-
"typescript": "^
|
|
44
|
-
"vitest": "^4.1.
|
|
45
|
-
"@forinda/kickjs": "
|
|
43
|
+
"typescript": "^7.0.2",
|
|
44
|
+
"vitest": "^4.1.11",
|
|
45
|
+
"@forinda/kickjs": "8.0.0"
|
|
46
46
|
},
|
|
47
47
|
"publishConfig": {
|
|
48
48
|
"access": "public"
|
|
@@ -67,7 +67,7 @@
|
|
|
67
67
|
"dev": "tsdown --watch",
|
|
68
68
|
"test": "vitest run --passWithNoTests",
|
|
69
69
|
"test:watch": "vitest",
|
|
70
|
-
"typecheck": "
|
|
70
|
+
"typecheck": "tsc --noEmit",
|
|
71
71
|
"clean": "rm -rf dist .wireit"
|
|
72
72
|
}
|
|
73
73
|
}
|