@dunx/testing 2.5.0 → 3.0.0

package/README.md

@@ -1,9 +1,17 @@
 # @dunx/testing
 
-The container an app already has, with named bindings **replaced in place**, plus a
-real `Bun.serve` on port 0. No mocking framework, no fake request object, no
-in-memory transport - Bun binds a socket in about a millisecond, so the thing under
-test is the thing that ships.
+The container an app already has, with named bindings **replaced in place**, plus
+a real `Bun.serve` on port 0. Bun binds a socket in about a millisecond, so the
+thing under test is the thing that ships: there is no mocking framework, no fake
+request object and no in-memory transport.
+
+## Install
+
+```bash
+bun add -d @dunx/testing
+```
+
+## Usage
 
 ```ts
 import { provide } from '@dunx/core';
@@ -27,140 +35,29 @@ const { status, body } = await server.json<User[]>('api/users');
 await server.close();
 ```
 
-## Overrides replace; they never append
-
-This is the whole design, and it follows from how `@dunx/core` applies an override:
-by **substitution into the binding that already exists**, never by appending a
-registration that has to out-rank the real one.
-
-A module is a scope, and `providers` are private to it. So a test override cannot be
-an extra module appended at the end that wins - an appended module's providers are
-invisible to every scope that does not import it, being the scope the
-code under test resolves from.
-
-`createTestApp` therefore builds the same scope graph the app would have and
-substitutes by token inside it. Three consequences worth relying on:
-
-- **An override replaces the binding in every scope that holds it.** A test stubbing
-  `Logger` does not have to know how many modules bind it, and does not have to name
-  a scope. Where two scopes genuinely bind one token differently and only one is
-  meant, resolve through the module you care about instead.
-- **An override naming a token nobody binds is an error** rather than a silent no-op. A
-  typo'd token would otherwise leave the suite asserting against the real provider
-  it thought it had swapped, the failure mode this package exists to
-  prevent.
-- **The discarded provider is never instantiated.** Its `useFactory` never runs and
-  its `onInit` never fires. Overriding the database does not open a connection to
-  the real database - that is the one guarantee here that a hand-rolled fixture
-  usually gets wrong, and `app.test.ts` proves it with a factory that throws if it
-  is ever called.
-
-`Logger` and `RequestContext` are overridable too, even though no module binds
-them: core offers a default for each after every module, and the substitution
-applies there as well.
-
-## API
-
-| Export                      | What it is                                                              |
-| --------------------------- | ----------------------------------------------------------------------- |
-| `createTestApp(options)`    | `Promise<App>` - the core container, overrides applied                  |
-| `createTestServer(options)` | `Promise<TestServer>` - the same, plus `Bun.serve` on port 0 and a client |
-| `testClient(url)`           | `TestClient` - the request helpers against any base URL                 |
-| `testRoot(modules)`         | The synthetic root module, for driving `HttpFactory` yourself           |
-| `RecordingLogger`           | A `Logger` that keeps entries instead of writing them                   |
-
-`modules` takes one module ref or several; several become the `imports` of one
-synthetic root, so no fixture module has to be written by hand. Anything a module
-ref can be works - a class, or a `DynamicModule` from a `forRoot`.
-
-`TestServer` is a `TestClient` plus `app` (the real `HttpApp`, for
-`app.get(...)`) and `close()`.
-
-`createTestServer` passes `HttpOptions` through, with two differences: `port`
-is always 0, and **`requestLogging` defaults to `false`** - it is on by default
-in production for good reasons, none of which apply to a suite that would
-otherwise print one JSON line per assertion. Pass `requestLogging: true` to
-test the logging itself.
-
-Everything else is **absent unless passed**, and `middleware` and `onError`
-decide what the application is: forget them and the fixture has no global
-guards and the default error mapper, and answers 200 where production answers
-401. Export one `httpOptions(config)` and spread it into both `main.ts` and
-every suite.
-
-Omitting `middleware` in a graph that declares a `Middleware` no `@UseGuards`
-attaches warns on `console.warn`; `middleware: []` says the omission is
-deliberate.
-
-### The client
-
-Two methods, because a third would be the start of an assertion DSL:
-
-```ts
-const { status, headers, body } = await server.json<Page>('notes?limit=10');
-await server.json('notes/7', { method: 'PATCH', json: { title: 'edited' } });
-const image = await server.request('avatars/7.png'); // the raw Response
-```
-
-`json` on the init object is serialized and sets `content-type: application/json`
-unless `headers` already carries one - one option for every verb, rather than a
-`post`/`put`/`patch` triple. `json()` reads the body as text before parsing, so a
-route that answered 204, HTML or a plain-text error fails with the status,
-content-type and body rather than with `JSON.parse`'s message.
+## What is here
 
-### RecordingLogger
+The [Testing guide](../../docs/guide/11-testing.md) is canonical.
 
-The `Logger` contract is seven levels of three overloads each, so every suite that
-wants a quiet app would otherwise hand-write the same thirty lines:
+| Export             | What it does                                                    |
+| ------------------ | ---------------------------------------------------------------- |
+| `createTestApp`    | The container, with overrides applied before anything resolves   |
+| `createTestServer` | The same, behind a real `Bun.serve` on port 0                    |
+| `testClient`       | The fetch-and-parse plumbing against a base url                  |
 
-```ts
-const logger = new RecordingLogger();
-await createTestApp({
-  modules: [PaymentsModule],
-  overrides: [provide(Logger, { useValue: logger })],
-});
-expect(logger.at(LogLevel.ERROR)).toEqual([]);
-```
-
-It records; it does not interpret. No level filtering, no error promotion, no
-merging of extras - those are `@arkv/logger`'s behaviour, and asserting against a
-reimplementation of them would prove nothing.
-
-## Not here
-
-- **A fluent assertion DSL** (`expect(res).toHaveStatus(200)`, supertest-style
-  chaining). `status` and a parsed `body` read fine through `expect` already, and a
-  matcher library would be a second vocabulary to learn for no new capability.
-- **Provider spies / partial mocks.** `provide(Token, { useValue })` with a class
-  the test wrote is smaller than any mocking API, and `bun test` already ships
-  `mock()` and `spyOn()` for a method on an instance the container handed back.
-- **A `providers` key on the options.** `{ modules, overrides }` is the shape, on
-  purpose: a suite tests the modules an app actually ships. A fixture class that
-  needs binding goes in a two-line `@Module`, which is also where it would live if
-  it were real.
-- **A fake HTTP dispatcher.** It could only exercise the parts of the request path
-  dunx wrote, and not the parts Bun owns - route matching, params, method
-  dispatch, upgrades. The real server is cheaper than the lie.
-- **Database fixtures, transactional rollback, seeding.** That is drizzle's
-  surface rather than this package's. `@dunx/infra/db` binds an in-memory `bun:sqlite`
-  with the same driver as production, which is a better fixture than a mock.
-- **A websocket client.** Bun implements `WebSocket` natively, and a gateway test
-  is `new WebSocket(server.url.replace('http', 'ws') + '/chat')`. Wrapping that
-  would add nothing.
+## Notes
 
-## Install it as a devDependency
-
-```bash
-bun add -d @dunx/testing
-```
+- An override replaces the binding in **every scope that holds it**, so a test
+  stubbing `Logger` need not know how many modules bind it. Naming a token
+  nobody binds is an error rather than a silent no-op.
+- The replacement happens before anything resolves, so the discarded provider is
+  never constructed: its `useFactory` never runs and its `onInit` never fires,
+  which makes overriding a database safe.
+- Request logging and boot logging are off unless asked for.
+- An `HttpOptions` field not passed is absent; nothing is inherited from
+  production. `middleware` and `onError` change what the application does, so
+  pass the same object `main.ts` passes.
 
-`@dunx/core` and `@dunx/http` are `dependencies`, at a **caret** range. What matters
-is that your app and this package resolve to **one copy of `@dunx/core`** - two
-copies means two `Logger` classes and two `RequestContext` classes, so tokens that
-match nothing and overrides that silently replace nothing. A caret range hoists to
-the copy your app already has.
+## License
 
-Peers would have expressed that better, and were tried first: `bun run --filter '*'`
-derives its build order from `dependencies` only, so a peer-only manifest cannot be
-built in this monorepo at all. The reasoning and the measurement are in
-[architecture/packaging.md](../../docs/architecture/packaging.md), "Test harness".
+MIT

package/dist/server.d.ts

@@ -18,11 +18,10 @@ export interface TestServer extends TestClient {
     close(): Promise<void>;
 }
 /**
- * A **real** `Bun.serve` on port 0, with the same override semantics as
- * {@link createTestApp}. Nothing is faked: `Bun.serve` binds in about a
- * millisecond, and a fake would only be able to prove the parts of the request
- * path dunx wrote rather than the parts Bun owns - routing, params, method
- * dispatch, upgrades.
+ * A real `Bun.serve` on port 0, with the same override semantics as
+ * {@link createTestApp}. `Bun.serve` binds in about a millisecond, and a fake
+ * could only prove the parts of the request path dunx wrote rather than the parts
+ * Bun owns - routing, params, method dispatch, upgrades.
  *
  * ```ts
  * const server = await createTestServer({ modules: [ApiModule], prefix: 'api' });
@@ -30,15 +29,11 @@ export interface TestServer extends TestClient {
  * await server.close();
  * ```
  *
- * Request logging and boot logging are both **off** unless asked for: they are on by
- * default in production for good reasons, none of which apply to a suite that would
- * print one JSON line per assertion and one route table per file.
+ * Request logging and boot logging are off unless asked for, since a suite would
+ * otherwise print one JSON line per assertion and one route table per file.
  *
- * **An `HttpOptions` field not passed is absent, not inherited from production.**
- * `middleware` (where global guards live) and `onError` are the two that change
- * what the application does, so pass the same object `main.ts` passes - one
- * exported `httpOptions(config)` spread into both. Omitting `middleware` in a graph
- * that declares a `Middleware` no `@UseGuards` attaches writes one line to
- * `console.warn`; `middleware: []` says the omission is deliberate.
+ * An `HttpOptions` field not passed is absent, not inherited from production.
+ * `middleware` and `onError` change what the application does, so pass the same
+ * object `main.ts` passes. `middleware: []` says the omission is deliberate.
  */
 export declare const createTestServer: (options: TestServerOptions) => Promise<TestServer>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/testing",
-  "version": "2.5.0",
+  "version": "3.0.0",
   "description": "Test harness for dunx apps: a container with providers replaced in place, and a real Bun.serve on port 0",
   "keywords": [
     "bun",
@@ -51,8 +51,8 @@
     "@dunx/http": "workspace:*"
   },
   "peerDependencies": {
-    "@dunx/core": "^2.5.0",
-    "@dunx/http": "^2.5.0",
+    "@dunx/core": "^3.0.0",
+    "@dunx/http": "^3.0.0",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {