@dolphjs/testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The (MIT License)
+
+Copyright (c) 2026 dolphtech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @dolphjs/testing
+
+Official testing utilities for DolphJS apps. A devDependency, not part of the runtime bundle — nothing here ships to production.
+
+## Why this exists
+
+Dolph's DI isn't a request-scoped container like Nest's `TestingModule`. Services are resolved **once**, the moment the module declaring their `@Component` is first imported, and cached forever in a process-wide `GlobalServiceRegistry`. That's a deliberate, simpler design — but it means "mocking a service" is really "winning a race": your mock has to be sitting in the registry *before* the component module is imported for the first time, or the real service has already been built and cached first.
+
+Everything in this package exists to make that ordering a non-issue, and to keep tests fast by never paying for more framework machinery than a given test actually needs.
+
+## The three tiers
+
+Write specs at the cheapest tier that can prove the behavior. Most of your suite should be tier 1.
+
+### 1. Service unit tests — `*.spec.ts`
+
+Services are plain classes. `DolphServiceHandler` adds nothing but a `name` field — no decoration is required to construct one yourself. Don't touch `@dolphjs/testing` at all here; just `new` the service with mocked collaborators.
+
+```ts
+// order.service.spec.ts
+import { OrderService } from './order.service';
+
+it('rejects a negative total', async () => {
+    const mockRepo = { findTotalById: jest.fn().mockResolvedValue(-5) };
+    const service = new OrderService(mockRepo);
+
+    await expect(service.getTotal('o-1')).rejects.toThrow();
+});
+```
+
+### 2. Controller unit tests — `*.spec.ts`
+
+**Prefer constructor injection over named-property injection on controllers.** `@Component` populates both the same way at boot, but only constructor injection lets a test hand in a mock via plain `new`:
+
+```ts
+// good — testable with `new OrderController(mockService)`
+constructor(private readonly orderService: OrderService) { super(); }
+
+// works at runtime, but a unit test can't set this without reaching
+// past the type system: `(controller as any).OrderService = mock`
+private OrderService: OrderService;
+```
+
+Route handlers that `return` their result (rather than writing to `res` directly) can be called like any other method — no Express involved:
+
+```ts
+// order.controller.spec.ts
+import { OrderController } from './order.controller';
+
+it('delegates to the service', () => {
+    const mockService = { getTotal: jest.fn().mockReturnValue(99) };
+    const controller = new OrderController(mockService as any);
+
+    expect(controller.getTotal('o-1')).toEqual({ total: 99 });
+});
+```
+
+### 3. Component e2e tests — `*.e2e-spec.ts`
+
+For the routes/middleware/param-decoration path itself — real Express, real `@Component`/`@Route` metadata, mocked services underneath. Use `createTestingApp`:
+
+```ts
+// order.component.e2e-spec.ts
+import request from 'supertest';
+import { createTestingApp, TestingApp } from '@dolphjs/testing';
+import { OrderService } from './order.service';
+
+describe('OrderComponent', () => {
+    let app: TestingApp;
+
+    beforeAll(async () => {
+        app = await createTestingApp({
+            components: [() => import('./order.component').then((m) => m.OrderComponent)],
+            overrides: [{ service: OrderService, useValue: { getTotal: jest.fn().mockReturnValue(77) } }],
+        });
+    });
+
+    afterAll(() => app.close());
+
+    it('serves through real routing', async () => {
+        const res = await request(app.engine).get('/orders/o-1/total');
+        expect(res.body.data).toEqual({ total: 77 });
+    });
+});
+```
+
+Two details matter here:
+
+- **`components` takes a lazy loader, not a static import.** A top-of-file `import { OrderComponent } from './order.component'` runs `@Component` immediately, before `beforeAll` gets a chance to seed any mocks — the real `OrderService` would already be built and cached. `createTestingApp` seeds `overrides` into the registry first, *then* awaits your loader, so the import happens after the mocks are in place.
+- **`app.engine` is a real, already-listening server — not a bare Express app.** `createTestingApp` never calls `DolphFactory#start()`, so it never installs `start()`'s process-level `SIGTERM`/`uncaughtException`/`unhandledRejection` handlers meant for a long-running server; registering those once per spec file is exactly why a `.start()`-based suite needs `jest --forceExit --detectOpenHandles` to exit cleanly. But it does bind one real ephemeral port via `http.createServer(engine).listen(0)`, reused for every request in the spec and closed by `app.close()` — supertest binds a **fresh** ephemeral server on every single call when handed a bare Express app instead of one already listening, which gets expensive fast on anything but a one-or-two-request spec. `examples/` in this repo runs three full tiers, including a real e2e test with several requests, and exits on its own with neither Jest flag — see `npm run test:examples`.
+
+## Jest config gotcha
+
+Jest's default `testMatch` picks up `*.spec.ts` and `*.test.ts`, but **not** `*.e2e-spec.ts` — there's no dot before "spec" for the pattern to match. If you use the `*.e2e-spec.ts` convention above, add it explicitly:
+
+```js
+// jest.config.js
+module.exports = {
+    preset: 'ts-jest',
+    testMatch: ['**/*.spec.ts', '**/*.e2e-spec.ts'],
+};
+```
+
+At enterprise scale — hundreds of spec files — `ts-jest` type-checking every file on every run stops being free. Swap the transform for `@swc/jest` (or `esbuild-jest`) once compile time shows up in CI; the spec files themselves don't change.
+
+## API
+
+- **`TestingRegistry.override(ServiceClass, mock)`** — seed a mock directly, for cases `createTestingApp`'s `overrides` doesn't cover.
+- **`TestingRegistry.get(ServiceClass)` / `.has(...)`** — read the current registry state.
+- **`TestingRegistry.reset()`** — clear every cached service. Call between test files, never mid-file.
+- **`createTestingApp({ components, overrides?, middlewares? })`** — see above. Returns `{ engine, get, close }`; `close()` is async — it closes the ephemeral server before resolving, so `afterAll(() => app.close())` is enough (Jest awaits the returned promise).
+- **`createSqliteTestDataSource({ entities })`** — in-memory `better-sqlite3` TypeORM `DataSource`, entity classes passed directly (no glob strings, no `dolph_config.yaml`).
+- **`createSqliteTestSequelize()`** — in-memory `sqlite3` Sequelize instance; call `Model.init({...}, { sequelize })` against it yourself.
+- **`createMongoMemoryTestServer()`** — real ephemeral MongoDB via `mongodb-memory-server`; returns `{ uri, stop }`.
+
+The three DB helpers lazily `require()` their driver, so an app that only uses Mongoose never resolves `typeorm`/`sequelize`, and vice versa — install only what you use.
+
+## Development
+
+```
+npm install
+npm run typecheck      # against a locally-built @dolphjs/dolph (file:../dolph/dist)
+npm run test:examples   # runs examples/ — the three tiers, against the real framework
+npm run build
+```
+
+`@dolphjs/dolph` is linked via `file:../dolph/dist`, not `file:../dolph` — the repo root has no `main`/`types` in its `package.json`, so a link to the repo root falls through to raw `.ts` source instead of the compiled build. Run `npm run build` in `../dolph` first if `dist/` is stale.

package/dist/db/mongo-memory.d.ts

@@ -0,0 +1,12 @@
+export interface MongoMemoryTestServer {
+    uri: string;
+    stop: () => Promise<void>;
+}
+/**
+ * Spins up a real, ephemeral MongoDB instance in-process for tests — no
+ * mocked driver, no shared dev database. Pass `.uri` to `mongoose.connect()`
+ * (or `autoInitMongo({ url: uri })`) in your test setup, and `.stop()` in
+ * teardown. Requires `mongodb-memory-server` in the consuming app; lazily
+ * required so apps that don't use Mongoose never pay to resolve it.
+ */
+export declare function createMongoMemoryTestServer(): Promise<MongoMemoryTestServer>;

package/dist/db/mongo-memory.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMongoMemoryTestServer = createMongoMemoryTestServer;
+/**
+ * Spins up a real, ephemeral MongoDB instance in-process for tests — no
+ * mocked driver, no shared dev database. Pass `.uri` to `mongoose.connect()`
+ * (or `autoInitMongo({ url: uri })`) in your test setup, and `.stop()` in
+ * teardown. Requires `mongodb-memory-server` in the consuming app; lazily
+ * required so apps that don't use Mongoose never pay to resolve it.
+ */
+async function createMongoMemoryTestServer() {
+    let MongoMemoryServer;
+    try {
+        ({ MongoMemoryServer } = require('mongodb-memory-server'));
+    }
+    catch {
+        throw new Error('`mongodb-memory-server` is not installed. Run `npm i -D mongodb-memory-server` to use createMongoMemoryTestServer().');
+    }
+    const server = await MongoMemoryServer.create();
+    return {
+        uri: server.getUri(),
+        stop: () => server.stop(),
+    };
+}
+//# sourceMappingURL=mongo-memory.js.map

package/dist/db/mongo-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-memory.js","sourceRoot":"","sources":["../../src/db/mongo-memory.ts"],"names":[],"mappings":";;AAYA,kEAeC;AAtBD;;;;;;GAMG;AACI,KAAK,UAAU,2BAA2B;IAC7C,IAAI,iBAAiD,CAAC;IACtD,IAAI,CAAC;QACD,CAAC,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,IAAI,KAAK,CACX,sHAAsH,CACzH,CAAC;IACN,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,CAAC;IAChD,OAAO;QACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE;QACpB,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE;KAC5B,CAAC;AACN,CAAC"}

package/dist/db/sqlite-sequelize.d.ts

@@ -0,0 +1,12 @@
+import type { Sequelize } from 'sequelize';
+/**
+ * An in-memory `sqlite3`-backed Sequelize instance for tests.
+ *
+ * Hands back a bare, connected instance only — Sequelize models are bound to
+ * an instance at `Model.init({...}, { sequelize, ... })`, so re-attaching
+ * already-initialized models the way `autoInitSql` does for a real app isn't
+ * meaningful here. Call `Model.init` against the returned instance in your
+ * test setup. Requires `sequelize` and `sqlite3` in the consuming app;
+ * lazily required so apps that don't use Sequelize never pay to resolve them.
+ */
+export declare function createSqliteTestSequelize(): Promise<Sequelize>;

package/dist/db/sqlite-sequelize.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqliteTestSequelize = createSqliteTestSequelize;
+/**
+ * An in-memory `sqlite3`-backed Sequelize instance for tests.
+ *
+ * Hands back a bare, connected instance only — Sequelize models are bound to
+ * an instance at `Model.init({...}, { sequelize, ... })`, so re-attaching
+ * already-initialized models the way `autoInitSql` does for a real app isn't
+ * meaningful here. Call `Model.init` against the returned instance in your
+ * test setup. Requires `sequelize` and `sqlite3` in the consuming app;
+ * lazily required so apps that don't use Sequelize never pay to resolve them.
+ */
+async function createSqliteTestSequelize() {
+    let SequelizeCtor;
+    try {
+        ({ Sequelize: SequelizeCtor } = require('sequelize'));
+    }
+    catch {
+        throw new Error('`sequelize` is not installed. Run `npm i -D sequelize sqlite3` to use createSqliteTestSequelize().');
+    }
+    const sequelize = new SequelizeCtor({
+        dialect: 'sqlite',
+        storage: ':memory:',
+        logging: false,
+    });
+    await sequelize.authenticate();
+    return sequelize;
+}
+//# sourceMappingURL=sqlite-sequelize.js.map

package/dist/db/sqlite-sequelize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-sequelize.js","sourceRoot":"","sources":["../../src/db/sqlite-sequelize.ts"],"names":[],"mappings":";;AAYA,8DAkBC;AA5BD;;;;;;;;;GASG;AACI,KAAK,UAAU,yBAAyB;IAC3C,IAAI,aAA+B,CAAC;IACpC,IAAI,CAAC;QACD,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,IAAI,KAAK,CACX,oGAAoG,CACvG,CAAC;IACN,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC;QAChC,OAAO,EAAE,QAAQ;QACjB,OAAO,EAAE,UAAU;QACnB,OAAO,EAAE,KAAK;KACjB,CAAC,CAAC;IAEH,MAAM,SAAS,CAAC,YAAY,EAAE,CAAC;IAC/B,OAAO,SAAS,CAAC;AACrB,CAAC"}

package/dist/db/sqlite-typeorm.d.ts

@@ -0,0 +1,17 @@
+import type { DataSource } from 'typeorm';
+export interface SqliteTestDataSourceOptions {
+    /** Entity classes — passed straight to TypeORM, no glob strings or `dolph_config.yaml` involved. */
+    entities: Function[];
+    /** Defaults to `true`; the whole point of an in-memory DB is a fresh schema per run. */
+    synchronize?: boolean;
+}
+/**
+ * An in-memory, `better-sqlite3`-backed TypeORM `DataSource` for tests.
+ *
+ * Bypasses `autoInitTypeOrm`/`dolph_config.yaml` entirely — those exist to
+ * wire a real database at app boot, which is unnecessary ceremony (and a
+ * shared on-disk file mutation) for a test that just needs a throwaway
+ * schema. Requires `typeorm` and `better-sqlite3` in the consuming app;
+ * lazily required so apps that don't use TypeORM never pay to resolve them.
+ */
+export declare function createSqliteTestDataSource(options: SqliteTestDataSourceOptions): Promise<DataSource>;

package/dist/db/sqlite-typeorm.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqliteTestDataSource = createSqliteTestDataSource;
+/**
+ * An in-memory, `better-sqlite3`-backed TypeORM `DataSource` for tests.
+ *
+ * Bypasses `autoInitTypeOrm`/`dolph_config.yaml` entirely — those exist to
+ * wire a real database at app boot, which is unnecessary ceremony (and a
+ * shared on-disk file mutation) for a test that just needs a throwaway
+ * schema. Requires `typeorm` and `better-sqlite3` in the consuming app;
+ * lazily required so apps that don't use TypeORM never pay to resolve them.
+ */
+async function createSqliteTestDataSource(options) {
+    let DataSourceCtor;
+    try {
+        ({ DataSource: DataSourceCtor } = require('typeorm'));
+    }
+    catch {
+        throw new Error('`typeorm` is not installed. Run `npm i -D typeorm better-sqlite3` to use createSqliteTestDataSource().');
+    }
+    const dataSource = new DataSourceCtor({
+        type: 'better-sqlite3',
+        database: ':memory:',
+        dropSchema: true,
+        entities: options.entities,
+        synchronize: options.synchronize ?? true,
+        logging: false,
+    });
+    await dataSource.initialize();
+    return dataSource;
+}
+//# sourceMappingURL=sqlite-typeorm.js.map

package/dist/db/sqlite-typeorm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-typeorm.js","sourceRoot":"","sources":["../../src/db/sqlite-typeorm.ts"],"names":[],"mappings":";;AAkBA,gEAqBC;AA9BD;;;;;;;;GAQG;AACI,KAAK,UAAU,0BAA0B,CAAC,OAAoC;IACjF,IAAI,cAAiC,CAAC;IACtC,IAAI,CAAC;QACD,CAAC,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,IAAI,KAAK,CACX,wGAAwG,CAC3G,CAAC;IACN,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,cAAc,CAAC;QAClC,IAAI,EAAE,gBAAgB;QACtB,QAAQ,EAAE,UAAU;QACpB,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,OAAO,EAAE,KAAK;KACV,CAAC,CAAC;IAEV,MAAM,UAAU,CAAC,UAAU,EAAE,CAAC;IAC9B,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { TestingRegistry } from './testing-registry';
+export type { Ctor } from './testing-registry';
+export { createTestingApp } from './testing-app';
+export type { TestingApp, TestingAppOptions, ComponentRef, ServiceOverride } from './testing-app';
+export { createSqliteTestDataSource } from './db/sqlite-typeorm';
+export type { SqliteTestDataSourceOptions } from './db/sqlite-typeorm';
+export { createSqliteTestSequelize } from './db/sqlite-sequelize';
+export { createMongoMemoryTestServer } from './db/mongo-memory';
+export type { MongoMemoryTestServer } from './db/mongo-memory';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMongoMemoryTestServer = exports.createSqliteTestSequelize = exports.createSqliteTestDataSource = exports.createTestingApp = exports.TestingRegistry = void 0;
+var testing_registry_1 = require("./testing-registry");
+Object.defineProperty(exports, "TestingRegistry", { enumerable: true, get: function () { return testing_registry_1.TestingRegistry; } });
+var testing_app_1 = require("./testing-app");
+Object.defineProperty(exports, "createTestingApp", { enumerable: true, get: function () { return testing_app_1.createTestingApp; } });
+var sqlite_typeorm_1 = require("./db/sqlite-typeorm");
+Object.defineProperty(exports, "createSqliteTestDataSource", { enumerable: true, get: function () { return sqlite_typeorm_1.createSqliteTestDataSource; } });
+var sqlite_sequelize_1 = require("./db/sqlite-sequelize");
+Object.defineProperty(exports, "createSqliteTestSequelize", { enumerable: true, get: function () { return sqlite_sequelize_1.createSqliteTestSequelize; } });
+var mongo_memory_1 = require("./db/mongo-memory");
+Object.defineProperty(exports, "createMongoMemoryTestServer", { enumerable: true, get: function () { return mongo_memory_1.createMongoMemoryTestServer; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAA5C,mHAAA,eAAe,OAAA;AAGxB,6CAAiD;AAAxC,+GAAA,gBAAgB,OAAA;AAGzB,sDAAiE;AAAxD,4HAAA,0BAA0B,OAAA;AAGnC,0DAAkE;AAAzD,6HAAA,yBAAyB,OAAA;AAElC,kDAAgE;AAAvD,2HAAA,2BAA2B,OAAA"}

package/dist/testing-app.d.ts

@@ -0,0 +1,51 @@
+import 'reflect-metadata';
+import { Server } from 'http';
+import type { RequestHandler } from 'express';
+import type { Ctor } from './testing-registry';
+/**
+ * Either the component class itself (when no override is needed — the module
+ * is presumably already imported at the top of the spec file) or a lazy
+ * loader (`() => import('../src/components/user/user.component')`) whose
+ * import is deferred until after mocks are seeded, so `@Component` resolves
+ * against the mocks instead of building the real services first.
+ */
+export type ComponentRef = Ctor | (() => Promise<Ctor | {
+    default: Ctor;
+}>);
+export interface ServiceOverride<T = any> {
+    service: Ctor<T>;
+    useValue: T;
+}
+export interface TestingAppOptions {
+    components: ComponentRef[];
+    /** Mocks seeded into the registry before `components` are resolved. */
+    overrides?: ServiceOverride[];
+    /** Applied before route registration — same ordering as `DolphFactory`'s constructor. */
+    middlewares?: RequestHandler[];
+}
+export interface TestingApp {
+    /** A real, already-listening ephemeral server — hand it straight to supertest. */
+    engine: Server;
+    /** Reads a service instance (real or mocked) straight off the registry, for direct assertions. */
+    get<T>(serviceClass: Ctor<T>): T | undefined;
+    /** Closes the ephemeral server and clears the process-wide registry. Call in `afterAll`. */
+    close(): Promise<void>;
+}
+/**
+ * Builds an isolated Dolph app for tests, without ever calling `DolphFactory#start()`.
+ *
+ * `start()` installs process-level `SIGTERM`/`uncaughtException`/`unhandledRejection`
+ * handlers meant for a long-running server — registering those once per spec
+ * file leaks across every other file that runs in the same Jest worker,
+ * which is exactly why the framework's own suite used to need
+ * `--forceExit --detectOpenHandles`.
+ *
+ * That said, `engine` is a real, listening server, not a bare Express app —
+ * supertest binds a brand new ephemeral server on every single request when
+ * handed a plain app instead of one already listening, which gets expensive
+ * fast across a spec with more than a handful of requests. Binding one
+ * ephemeral port here, reused for every request and closed in `close()`,
+ * gets the same effect `start()` gives a real app without its process-level
+ * side effects.
+ */
+export declare function createTestingApp(options: TestingAppOptions): Promise<TestingApp>;

package/dist/testing-app.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestingApp = createTestingApp;
+require("reflect-metadata");
+const http_1 = require("http");
+const dolph_1 = require("@dolphjs/dolph");
+const isLoader = (ref) => typeof ref === 'function' && ref.prototype === undefined;
+/**
+ * Builds an isolated Dolph app for tests, without ever calling `DolphFactory#start()`.
+ *
+ * `start()` installs process-level `SIGTERM`/`uncaughtException`/`unhandledRejection`
+ * handlers meant for a long-running server — registering those once per spec
+ * file leaks across every other file that runs in the same Jest worker,
+ * which is exactly why the framework's own suite used to need
+ * `--forceExit --detectOpenHandles`.
+ *
+ * That said, `engine` is a real, listening server, not a bare Express app —
+ * supertest binds a brand new ephemeral server on every single request when
+ * handed a plain app instead of one already listening, which gets expensive
+ * fast across a spec with more than a handful of requests. Binding one
+ * ephemeral port here, reused for every request and closed in `close()`,
+ * gets the same effect `start()` gives a real app without its process-level
+ * side effects.
+ */
+async function createTestingApp(options) {
+    const { components, overrides = [], middlewares } = options;
+    // 1. Seed mocks first — see the module-level doc comment on why ordering matters.
+    for (const { service, useValue } of overrides) {
+        dolph_1.GlobalServiceRegistry.set(service, useValue);
+    }
+    // 2. Resolve components. Importing a loader here — for the first time in
+    //    this module registry — is what triggers `@Component`, by which point
+    //    the mocks above are already in place.
+    const resolved = [];
+    for (const ref of components) {
+        if (isLoader(ref)) {
+            const mod = await ref();
+            resolved.push('default' in mod ? mod.default : mod);
+        }
+        else {
+            resolved.push(ref);
+        }
+    }
+    const factory = new dolph_1.DolphFactory(resolved, middlewares);
+    const server = (0, http_1.createServer)(factory.engine()).listen(0);
+    return {
+        engine: server,
+        get: (serviceClass) => dolph_1.GlobalServiceRegistry.get(serviceClass),
+        close: () => new Promise((resolve) => {
+            dolph_1.GlobalServiceRegistry._reset();
+            server.close(() => resolve());
+        }),
+    };
+}
+//# sourceMappingURL=testing-app.js.map

package/dist/testing-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-app.js","sourceRoot":"","sources":["../src/testing-app.ts"],"names":[],"mappings":";;AAyDA,4CAiCC;AA1FD,4BAA0B;AAC1B,+BAA4C;AAC5C,0CAAqE;AAmCrE,MAAM,QAAQ,GAAG,CAAC,GAAiB,EAAkD,EAAE,CACnF,OAAO,GAAG,KAAK,UAAU,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,gBAAgB,CAAC,OAA0B;IAC7D,MAAM,EAAE,UAAU,EAAE,SAAS,GAAG,EAAE,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAE5D,kFAAkF;IAClF,KAAK,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,SAAS,EAAE,CAAC;QAC5C,6BAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,2CAA2C;IAC3C,MAAM,QAAQ,GAAW,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,MAAM,GAAG,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAE,GAAY,CAAC,CAAC;QAClE,CAAC;aAAM,CAAC;YACJ,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,oBAAY,CAAC,QAAe,EAAE,WAAW,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,IAAA,mBAAY,EAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAExD,OAAO;QACH,MAAM,EAAE,MAAM;QACd,GAAG,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,6BAAqB,CAAC,GAAG,CAAC,YAAY,CAAC;QAC9D,KAAK,EAAE,GAAG,EAAE,CACR,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC1B,6BAAqB,CAAC,MAAM,EAAE,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAClC,CAAC,CAAC;KACT,CAAC;AACN,CAAC"}

package/dist/testing-registry.d.ts

@@ -0,0 +1,25 @@
+export type Ctor<T = any> = new (...args: any[]) => T;
+/**
+ * Typed facade over Dolph's process-wide GlobalServiceRegistry.
+ *
+ * `@Component` resolves and caches every service the moment the module that
+ * declares it is first imported — not per-request, per-test-run, or lazily.
+ * A mock only wins if it is already sitting in the registry before that
+ * import happens; otherwise the real service has already been built and
+ * cached first. `createTestingApp` (see `testing-app.ts`) sequences this
+ * correctly for you — reach for `TestingRegistry` directly only when you
+ * need finer control (e.g. resetting between tests in the same file).
+ */
+export declare const TestingRegistry: {
+    /** Seeds a mock instance so the next `@Component` resolution picks it up instead of constructing the real service. */
+    override<T>(serviceClass: Ctor<T>, mockInstance: T): void;
+    /** Reads whatever is currently cached for this service class — the real instance or a mock. */
+    get<T>(serviceClass: Ctor<T>): T | undefined;
+    has(serviceClass: Ctor): boolean;
+    /**
+     * Clears every cached service, process-wide. Call between test files (or
+     * `describe` blocks that each build their own testing app) — never mid-file
+     * while another in-flight test still expects its services to be resolved.
+     */
+    reset(): void;
+};

package/dist/testing-registry.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestingRegistry = void 0;
+const dolph_1 = require("@dolphjs/dolph");
+/**
+ * Typed facade over Dolph's process-wide GlobalServiceRegistry.
+ *
+ * `@Component` resolves and caches every service the moment the module that
+ * declares it is first imported — not per-request, per-test-run, or lazily.
+ * A mock only wins if it is already sitting in the registry before that
+ * import happens; otherwise the real service has already been built and
+ * cached first. `createTestingApp` (see `testing-app.ts`) sequences this
+ * correctly for you — reach for `TestingRegistry` directly only when you
+ * need finer control (e.g. resetting between tests in the same file).
+ */
+exports.TestingRegistry = {
+    /** Seeds a mock instance so the next `@Component` resolution picks it up instead of constructing the real service. */
+    override(serviceClass, mockInstance) {
+        dolph_1.GlobalServiceRegistry.set(serviceClass, mockInstance);
+    },
+    /** Reads whatever is currently cached for this service class — the real instance or a mock. */
+    get(serviceClass) {
+        return dolph_1.GlobalServiceRegistry.get(serviceClass);
+    },
+    has(serviceClass) {
+        return dolph_1.GlobalServiceRegistry.has(serviceClass);
+    },
+    /**
+     * Clears every cached service, process-wide. Call between test files (or
+     * `describe` blocks that each build their own testing app) — never mid-file
+     * while another in-flight test still expects its services to be resolved.
+     */
+    reset() {
+        dolph_1.GlobalServiceRegistry._reset();
+    },
+};
+//# sourceMappingURL=testing-registry.js.map

package/dist/testing-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-registry.js","sourceRoot":"","sources":["../src/testing-registry.ts"],"names":[],"mappings":";;;AAAA,0CAAuD;AAIvD;;;;;;;;;;GAUG;AACU,QAAA,eAAe,GAAG;IAC3B,sHAAsH;IACtH,QAAQ,CAAI,YAAqB,EAAE,YAAe;QAC9C,6BAAqB,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAC1D,CAAC;IAED,+FAA+F;IAC/F,GAAG,CAAI,YAAqB;QACxB,OAAO,6BAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC;IAED,GAAG,CAAC,YAAkB;QAClB,OAAO,6BAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK;QACD,6BAAqB,CAAC,MAAM,EAAE,CAAC;IACnC,CAAC;CACJ,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@dolphjs/testing",
+    "version": "1.0.0",
+    "description": "Official testing utilities for DolphJS applications — fast, isolated unit tests and lightweight HTTP integration tests built for the framework's decoration-time DI model.",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "repository": "https://github.com/dolphjs/testing",
+    "bugs": "https://github.com/dolphjs/testing/issues",
+    "homepage": "https://github.com/dolphjs/testing#readme",
+    "author": "Utee Akaninyene",
+    "license": "MIT",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsc -b -v .",
+        "clean": "rimraf dist",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint \"src/**/*.ts\"",
+        "test:examples": "jest --config jest.examples.config.js"
+    },
+    "peerDependencies": {
+        "@dolphjs/dolph": ">=2.0.0",
+        "reflect-metadata": "^0.1.13 || ^0.2.0",
+        "mongodb-memory-server": ">=9.0.0",
+        "sequelize": ">=6.0.0",
+        "typeorm": ">=0.3.0"
+    },
+    "peerDependenciesMeta": {
+        "mongodb-memory-server": {
+            "optional": true
+        },
+        "sequelize": {
+            "optional": true
+        },
+        "typeorm": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@dolphjs/dolph": "file:../dolph/dist",
+        "@types/express": "^4.17.21",
+        "@types/jest": "^29.5.12",
+        "@types/node": "^20.14.0",
+        "@types/supertest": "^6.0.2",
+        "jest": "^29.7.0",
+        "mongodb-memory-server": "^9.2.0",
+        "reflect-metadata": "^0.2.2",
+        "rimraf": "^5.0.7",
+        "sequelize": "^6.37.3",
+        "supertest": "^7.0.0",
+        "ts-jest": "^29.2.3",
+        "typeorm": "^0.3.20",
+        "typescript": "^5.4.5"
+    }
+}