@hellaweb3/wiremock-testcontainers-nodejs 0.2.1 → 0.4.0

package/README.md

@@ -1,405 +1,206 @@
-<!--suppress HtmlDeprecatedAttribute -->
-<div align="center">
+# WireMock Testcontainers for Node.js
 
-<h1>WireMock Testcontainers Node.js Typescript</h1>
+[![Build](https://github.com/hella-web3/wiremock-testcontainers-nodejs/actions/workflows/main.yml/badge.svg)](https://github.com/hella-web3/wiremock-testcontainers-nodejs/actions/workflows/main.yml)
+[![npm](https://img.shields.io/npm/v/%40hellaweb3%2Fwiremock-testcontainers-nodejs)](https://www.npmjs.com/package/@hellaweb3/wiremock-testcontainers-nodejs)
+[![downloads](https://img.shields.io/npm/dm/%40hellaweb3%2Fwiremock-testcontainers-nodejs)](https://www.npmjs.com/package/@hellaweb3/wiremock-testcontainers-nodejs)
 
-<p>A library for easily using WireMock with Testcontainers in Node.js applications.</p>
+Run [WireMock](https://wiremock.org/) in [Testcontainers](https://node.testcontainers.org/) with a
+fluent TypeScript API modelled on the official
+[Java module](https://github.com/wiremock/wiremock-testcontainers-java): load stubs from
+directories, files, npm packages or inline JSON; reset state between tests without restarting;
+verify calls through WireMock's request journal.
 
-<a href="https://github.com/hella-web3/wiremock-testcontainers-nodejs/actions/workflows/main.yml ">
-    <img alt="Build Status" src="https://github.com/hella-web3/wiremock-testcontainers-nodejs/actions/workflows/main.yml/badge.svg" />
-</a>
-
-<a href="https://www.npmjs.com/package/@hellaweb3/wiremock-testcontainers-nodejs">
-<img alt="npm version" src="https://img.shields.io/npm/v/%40hellaweb3%2Fwiremock-testcontainers-nodejs" />
-</a>
-
-<a href="https://www.npmjs.com/package/@hellaweb3/wiremock-testcontainers-nodejs">
-<img alt="npm downloads" src="https://img.shields.io/npm/dm/%40hellaweb3%2Fwiremock-testcontainers-nodejs" />
-</a>
-
-</div>
-
-## Description
-
-`wiremock-testcontainers-nodejs` is a Typescript nodejs library that spins up
-a [WireMock](https://wiremock.org/)
-instance with [Testcontainers](https://node.testcontainers.org/). It provides a
-fluent API to configure and start WireMock
-containers from recorded WireMock directories, individual named mappings
-(local files, npm packages, module-relative files or inline JSON) and static
-files – an API modelled on the official
-[Java module](https://github.com/wiremock/wiremock-testcontainers-java).
-
-## Installation
+## Install
 
 ```bash
-pnpm add -D @hellaweb3/wiremock-testcontainers-nodejs testcontainers
+npm i -D @hellaweb3/wiremock-testcontainers-nodejs testcontainers
 ```
 
-Requires Node.js >= 22.22 and a reachable Docker daemon (anything
-[Testcontainers](https://node.testcontainers.org/supported-container-runtimes/)
-supports).
+Node.js >= 22.22 and a [container runtime](https://node.testcontainers.org/supported-container-runtimes/).
+ESM and CJS, fully typed, `testcontainers` is the only dependency. pnpm >= 10 may report
+`Ignored build scripts: ssh2, …` – optional native bindings of `testcontainers`, safe to ignore.
 
-**What you get:** a ~17 kB package – dual ESM (`dist/index.js`) and CJS
-(`dist/index.cjs`) builds with matching declarations, `sideEffects: false`
-for tree-shaking, `testcontainers` as the single runtime dependency (never
-bundled), and the TypeScript source for go-to-definition.
+## Quick start
 
-**pnpm users:** pnpm >= 10 may report `Ignored build scripts: ssh2, protobufjs,
-cpu-features`. These are transitive dependencies of `testcontainers`; the
-scripts only build an *optional* native crypto binding for `ssh2`, which falls
-back to pure JavaScript. It is safe to leave them ignored.
+```typescript
+import { afterAll, afterEach, beforeAll, expect, it } from "vitest"; // or Jest
+import { type StartedWiremockContainer, WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";
 
-## Usage
+let wiremock: StartedWiremockContainer;
 
-### Basic Example
+beforeAll(async () => {
+  wiremock = await new WiremockContainer()
+    .withMappings("./test/__mocks__/wiremock") // mappings/ + __files/
+    .start();
+  await wiremock.waitUntilReady();
+}, 60_000); // the first image pull can be slow
 
-1. Record or hand-write your stubs in the standard WireMock layout, e.g.
-   `test/__mocks__/wiremock/mappings/*.json` and
-   `test/__mocks__/wiremock/__files/*.json`.
-2. Start a `WiremockContainer` once per suite, point it at that directory and
-   use `rpcUrl` as the base URL of the API under test.
-3. Stop the container when the suite finishes.
+afterEach(() => wiremock.reset()); // pristine stubs, empty journal – no restart
+afterAll(() => wiremock.stop());
 
-```typescript
-import { afterAll, beforeAll, describe, expect, it } from "vitest"; // or jest
-import {
-  StartedWiremockContainer,
-  WiremockContainer,
-} from "@hellaweb3/wiremock-testcontainers-nodejs";
-
-describe("Cards API", () => {
-  let container: StartedWiremockContainer;
-
-  beforeAll(async () => {
-    container = await new WiremockContainer()        // wiremock/wiremock:latest
-      .withMappings("./test/__mocks__/wiremock")      // mappings/ + __files/
-      .start();                                       // waits for port 8080
-  }, 60_000);                                         // image pull can be slow
-
-  afterAll(async () => {
-    await container.stop();
-  });
-
-  it("serves the recorded GET /cards stub", async () => {
-    const response = await fetch(`${container.rpcUrl}/cards`);
-    expect(response.status).toBe(200);
-
-    const body = await response.json();
-    expect(body.items).toHaveLength(6);
-  });
-
-  it("exposes the WireMock admin API", async () => {
-    const response = await fetch(`${container.rpcUrl}/__admin/mappings`);
-    const { meta } = await response.json();
-    expect(meta.total).toBe(2);
-  });
+it("serves GET /cards", async () => {
+  const response = await fetch(wiremock.getUrl("/cards"));
+
+  expect(response.status).toBe(200);
+  expect(await wiremock.countRequests({ method: "GET", url: "/cards" })).toBe(1);
 });
 ```
 
-`WiremockContainer` extends Testcontainers' `GenericContainer`, so every
-builder method is available – for example to pin an image, name the container
-or pass WireMock CLI flags:
+## Registering stubs
 
 ```typescript
-const container = await new WiremockContainer("wiremock/wiremock:3.13.0")
-  .withName("wiremock-cards-api")
-  .withCommand(["--verbose", "--global-response-templating"])
-  .withMappings("./test/__mocks__/wiremock")
-  .start();
+new WiremockContainer("wiremock/wiremock:3.13.0") // default: wiremock/wiremock
+  .withMappings("./test/__mocks__/wiremock")     // a recorded directory
+  .withMapping("health", "./fixtures/health.json")
+  .withMapping("ping", { json: { request: { url: "/ping" }, response: { status: 200, body: "pong" } } })
+  .withFiles("./fixtures/body.json", { file: "./logo.png", name: "img/logo.png" })
+  .withCommand(["--global-response-templating"]); // any Testcontainers builder method
 ```
 
-### With Mappings and Files
+- **`withMappings(dir)`** copies `dir/mappings/` (required) and `dir/__files/` (optional).
+- **`withMapping(name, source)`** registers one stub at `mappings/<name>.json`; `name` may
+  contain `/`. The file may hold one stub or `{ "mappings": [...] }`.
+- **`withFiles(...sources)`** registers response bodies at `__files/<name>`, the base name unless
+  `name` is given. All or nothing.
 
-WireMock uses a specific directory structure for mappings and static files. This
-library makes it easy to mount these into the container.
+| Source                             | Example                                                        |
+|------------------------------------|----------------------------------------------------------------|
+| Path (relative to cwd) or `file:` URL | `"./fixtures/a.json"`, `new URL("./a.json", import.meta.url)` |
+| `{ file }`                         | `{ file: "./fixtures/a.json" }`                                 |
+| `{ package, file }` – any file of an installed package | `{ package: "@acme/fixtures", file: "wiremock/a.json" }` |
+| `{ module, file }` – next to a module | `{ module: import.meta.url, file: "./a.json" }` (CJS: `__dirname`) |
+| `{ json }` – mappings only         | an object (serialised) or a string (copied verbatim)            |
 
-**Project structure:**
+Registrations are validated before any image is pulled: sources must exist, mappings must be
+WireMock stubs, and nothing may overwrite another registration or reuse a stub `id`.
 
-```
-test/
-└── __mocks__/
-    └── wiremock/
-        ├── mappings/
-        │   └── my-mapping.json
-        └── __files/
-            └── some-data.json
-```
+## Extensions
 
-```typescript
-import { WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";
-
-const container = await new WiremockContainer()
-  .withMappings("./test/__mocks__/wiremock")
-  .start();
-```
-
-### Individual mappings and files
-
-`withMapping(name, source)` registers one stub at `mappings/<name>.json` and
-`withFiles(...files)` registers response bodies in `__files/` – no recorded
-directory required. A mapping file holds one WireMock stub, or several under
-`"mappings"`:
+Load [WireMock extensions](https://wiremock.org/docs/extending-wiremock/) from compiled JARs – no JDK needed:
 
-```json
-{ "request": { "method": "GET", "url": "/health" }, "response": { "status": 200, "jsonBody": { "status": "UP" } } }
+```typescript
+new WiremockContainer()
+  .withExtensionJar("./wiremock/acme.jar")        // onto WireMock's class path
+  .withExtension("com.acme.UppercaseTransformer") // --extensions com.acme.UppercaseTransformer
+  .withMapping("shout", { json: { request: { url: "/shout" }, response: { body: "hi", transformers: ["uppercase"] } } });
 ```
 
-#### Mapping sources
+| Method                                                 | Registers                                                                 |
+|--------------------------------------------------------|---------------------------------------------------------------------------|
+| `withExtension(ext)`, `withExtensions([...])`          | A fully qualified class name, or a [TypeScript extension](#typescript-extensions) |
+| `withExtensionJar(jar)`, `withExtensionJars([...])`    | A JAR, or every `*.jar` of a directory – any source above; `{ file, name }` renames |
+| `withExtensionOptions({ scanning, verifyClassNames })` | `scanning: false` ignores JARs' `META-INF/services`; `verifyClassNames: false` skips the class check |
 
-**Local file** – a path relative to the working directory, or absolute:
+- Class names share one `--extensions` flag, in registration order, without repeats.
+- Validated before start: JARs must be readable `*.jar`s; each class must be in a registered JAR
+  or WireMock itself (else: *did you mean …?*); `withCommand()` must not repeat `--extensions` or
+  an extension's option – WireMock crashes on repeats. Start-up failures name the extensions.
+- WireMock 3 runs on Java 11+, so JARs must target Java 11. Custom images must keep the official
+  `/var/wiremock/extensions` class path.
 
-```typescript
-new WiremockContainer().withMapping("health", "./test/fixtures/health.json"); // → mappings/health.json
-```
+### TypeScript extensions
 
-**`file:` URL** – e.g. relative to the current module:
+Bundle class names, JARs and options; register the class or an instance:
 
 ```typescript
-new WiremockContainer().withMapping("health", new URL("./fixtures/health.json", import.meta.url));
-```
-
-**`{ file }`** – a path or URL in object form:
+import type { WireMockExtension } from "@hellaweb3/wiremock-testcontainers-nodejs";
 
-```typescript
-new WiremockContainer().withMapping("health", { file: "./test/fixtures/health.json" });
+class Uppercase implements WireMockExtension {
+  getName() { return "uppercase"; } // identifies it; implement at least one method below
+  getClassNames() { return ["com.acme.UppercaseTransformer"]; }
+  getJars() { return [{ module: import.meta.url, file: "./acme.jar" }]; }
+  getOptions() { return ["--global-response-templating"]; } // "--flag" or "--option=value"
+}
+new WiremockContainer().withExtension(Uppercase);
 ```
 
-**`{ package, file }`** – a file inside an installed npm package, e.g. shared
-fixtures. Resolved like `require()` from the working directory; the file does
-not need to be exported and may not leave the package:
+The [guide for extension authors](./examples/extensions/README.md) has recipes, tests and publishing.
 
-```typescript
-new WiremockContainer().withMapping("cards/list", { package: "@acme/api-fixtures", file: "wiremock/cards.json" }); // → mappings/cards/list.json
-```
+## Test utilities
 
-**`{ module, file }`** – a file relative to a module, like a Java classpath
-resource:
+`start()` resolves to a `StartedWiremockContainer`:
 
-```typescript
-new WiremockContainer().withMapping("balance", { module: import.meta.url, file: "./__mocks__/balance.json" }); // ESM
-new WiremockContainer().withMapping("balance", { module: __dirname, file: "./__mocks__/balance.json" });       // CJS (or __filename)
-```
+| Member                                    | Purpose                                                                 |
+|-------------------------------------------|-------------------------------------------------------------------------|
+| `rpcUrl`                                  | Base URL, e.g. `http://localhost:32768`                                 |
+| `getUrl(path?)`                           | `getUrl("cards?page=1")` → `<rpcUrl>/cards?page=1`                       |
+| `getAdminUrl()` / `getMappingUrl()`       | `<rpcUrl>/__admin` / `<rpcUrl>/__admin/mappings` (runtime stubs)        |
+| `isRunning()`                             | `true` if WireMock is healthy; never throws                             |
+| `waitUntilReady({ timeout?, interval? })` | Polls until healthy (defaults: 30 s, every 250 ms)                      |
+| `reset()`                                 | Restore registered stubs and scenarios, clear the journal – no restart  |
+| `resetRequests()`                         | Clear the journal only                                                  |
+| `countRequests(criteria)`                 | Number of matching requests since the last reset                        |
+| `findRequests(criteria)`                  | The matching `RecordedRequest`s (url, method, headers, body, …)          |
+| `stop()`, `await using`                   | Stop the container                                                      |
 
-**`{ json }` (object)** – an inline stub, serialised as-is:
+`criteria` (`WiremockRequestCriteria`) uses WireMock's [request matching](https://wiremock.org/docs/request-matching/):
 
 ```typescript
-new WiremockContainer().withMapping("ping", {
-  json: { request: { method: "GET", url: "/ping" }, response: { status: 200, body: "pong" } },
+const [request] = await wiremock.findRequests({
+  method: "POST",
+  urlPath: "/cards",
+  headers: { "Content-Type": { equalTo: "application/json" } },
 });
+expect(JSON.parse(request.body ?? "")).toMatchObject({ cardType: "virtual" });
 ```
 
-**`{ json }` (string)** – inline JSON, copied verbatim:
+Also exported: `WaitUntilReadyOptions`, the source types `WiremockMappingSource`,
+`WiremockStaticFile`, `WiremockFileSource`, `WiremockPath` and `WiremockStubMapping`, and the
+extension types `WireMockExtension`, `ExtensionConstructor`, `ExtensionInput`,
+`WiremockExtensionJar` and `WiremockExtensionOptions`.
 
-```typescript
-new WiremockContainer().withMapping("ping", { json: '{ "request": { "url": "/ping" }, "response": { "status": 200 } }' });
-```
-
-**Several stubs in one mapping** – any source may hold `{ "mappings": [...] }`:
+**Tips:** start one container per suite and `reset()` between tests, which is far faster than
+restarting; raise the `beforeAll` timeout for the first image pull; assert with
+`countRequests()`/`findRequests()` – they verify what actually went over the wire.
 
-```typescript
-new WiremockContainer().withMapping("greetings", {
-  json: {
-    mappings: [
-      { request: { url: "/hello" }, response: { status: 200, body: "Hello" } },
-      { request: { url: "/bye" }, response: { status: 200, body: "Bye" } },
-    ],
-  },
-});
-```
+## Without Docker (local development only)
 
-#### Static files
+No container runtime? With Java 11+, `@hellaweb3/wiremock-testcontainers-nodejs/no-docker`
+serves every `WiremockContainer` from a local WireMock JVM. Tests stay unchanged: stubs, files,
+extensions and `withCommand()` flags apply as in the container.
 
-`withFiles()` takes the same file sources (not `{ json }`). A file keeps its
-base name unless an object source sets `name`; mappings reference it as
-`bodyFileName`:
+> [!WARNING]
+> Never the default, never for CI/CD: it refuses to run when CI is detected (`CI`,
+> `GITHUB_ACTIONS`, …) and warns on every start. Results can differ from the Docker image; run
+> with Docker before merging.
 
-```typescript
-new WiremockContainer().withFiles(
-  "./test/fixtures/body-cards.json",                                     // → __files/body-cards.json
-  { file: "./test/fixtures/logo.png", name: "images/logo.png" },        // → __files/images/logo.png
-  { package: "@acme/api-fixtures", file: "wiremock/__files/user.json" }, // → __files/user.json
-);
+```bash
+npm i -D wiremock # bundles the WireMock JAR (optional peer dependency)
 ```
 
-#### Combining them
-
-All three methods chain with each other and with every Testcontainers builder:
-
 ```typescript
-const container = await new WiremockContainer()
-  .withMappings("./test/__mocks__/wiremock")
-  .withMapping("health", "./test/fixtures/health.json")
-  .withMapping("cards/list", { package: "@acme/api-fixtures", file: "wiremock/cards.json" })
-  .withFiles({ file: "./test/fixtures/cards.json", name: "cards/body.json" })
-  .start();
+// test/no-docker.setup.ts
+import { installNoDockerRuntime } from "@hellaweb3/wiremock-testcontainers-nodejs/no-docker";
+installNoDockerRuntime();
+
+// vitest.config.ts – opt-in only
+setupFiles: process.env.WIREMOCK_NO_DOCKER === "1" ? ["./test/no-docker.setup.ts"] : [],
 ```
 
-Registrations are validated immediately, before any image is pulled: sources
-must exist, mappings must be WireMock stubs, and no registration may overwrite a
-file of another or reuse a stub `id` (WireMock would refuse to start).
-Registering the same file at the same path again is a no-op. Sources are only
-read – mappings are copied byte-for-byte as of registration.
-
-## API
-
-### `WiremockContainer`
-
-- `constructor(image?: string)`: Create a new container. Defaults to
-  `wiremock/wiremock`.
-- `withMappings(directory: string)`: Copies `mappings/` (required) and
-  `__files/` (optional) from the specified local directory into the container.
-  Throws immediately if `mappings/` does not exist, so a typo fails before any
-  image is pulled.
-- `withMapping(name: string, source: WiremockMappingSource)`: Registers one stub
-  at `mappings/<name>.json` (`name` may contain `/`; `.json` is optional).
-- `withFiles(...files: WiremockStaticFile[])`: Registers files at
-  `__files/<name>` – the base name unless an object source sets `name`. A call
-  registers all files or none.
-- `start()`: Starts the container and returns a `StartedWiremockContainer`.
-  Runtime failures (no daemon, image pull denied, start-up timeout, name or
-  port conflicts) are propagated unchanged.
-
-### `StartedWiremockContainer`
-
-- `rpcUrl`: Returns the base URL of the running WireMock instance (e.g.,
-  `http://localhost:32768`).
-- `stop()`: Stops the container (inherited from Testcontainers).
-- `[Symbol.asyncDispose]`: `await using container = await new WiremockContainer().start();`
-  stops the container automatically when the scope exits (TypeScript 5.2+).
-
-## Best Practices
-
-1. **Test Isolation**: Start a new container for each test suite (or even each
-   test if performance allows) to ensure a clean state.
-2. **Mapping Organization**: Keep your mappings organized in a dedicated
-   directory structure that mirrors your API endpoints.
-3. **Timeouts**: Docker container startup can sometimes exceed the default test
-   runner timeout (e.g. 5 s in Jest, 10 s in Vitest). Always set a higher timeout for
-   `beforeAll` hooks that start containers.
-4. **Resource Management**: Always ensure `container.stop()` is called in an
-   `afterAll` or `afterEach` block to prevent orphaned containers.
-
-## Development
-
-Tooling: [Vitest](https://vitest.dev/) (tests + v8 coverage),
-[oxlint](https://oxc.rs/docs/guide/usage/linter) (lint), `tsc` (typecheck)
-and [tsdown](https://tsdown.dev/) (build – rolldown + oxc, emitting
-declarations natively via `isolatedDeclarations` in `tsconfig.build.json`).
-Node version: see `.nvmrc`.
-
-### Scripts
-
-| Command              | What it does                                                             | Needs Docker |
-|----------------------|--------------------------------------------------------------------------|--------------|
-| `pnpm build`         | ESM + CJS + declarations into `dist/`, then `publint` + `attw` checks    | No           |
-| `pnpm typecheck`     | `tsc --noEmit` over `src/` and `test/`                                   | No           |
-| `pnpm lint`          | `oxlint --deny-warnings` with the rules in `.oxlintrc.json`              | No           |
-| `pnpm test:unit`     | `test/unit/**` – container wrapper logic, registration API and fixture integrity checks | No |
-| `pnpm test:e2e`      | `test/index.test.ts` – a real WireMock container serving the fixtures    | **Yes**      |
-| `pnpm test`          | Both suites, no coverage (fast local loop)                               | **Yes**      |
-| `pnpm test:coverage` | Both suites with coverage of `src/`, thresholds enforced                 | **Yes**      |
-| `pnpm check`         | `build` + `typecheck` + `lint` + `test:coverage` – the full CI gate      | **Yes**      |
-
-Append `--coverage` to any test script to collect coverage for that run, e.g.
-`pnpm test:unit --coverage`. Coverage thresholds are **95 %** for statements,
-branches, functions and lines; the unit suite alone currently reaches 100 %
-and completes in well under two seconds of test time.
-
-### Running the E2E suite in containerised environments
-
-The E2E suite starts a real container through Testcontainers, so the test
-process needs a container runtime it can talk to. Without one, `pnpm test:e2e`,
-`pnpm test` and `pnpm check` fail in the E2E suite with:
+Set `WIREMOCK_NO_DOCKER=1` from a `--no-docker` script flag – see
+[`examples/scripts/test-e2e.mjs`](./examples/scripts/test-e2e.mjs), which supports
+`npm test --no-docker`.
 
-```
-Could not find a working container runtime strategy
-```
+| Option (`installNoDockerRuntime`) | Environment                  | Default                            |
+|-----------------------------------|------------------------------|------------------------------------|
+| `jar`                             | `WIREMOCK_JAR`               | the `wiremock` package's JAR       |
+| `java`                            | `WIREMOCK_JAVA`, `JAVA_HOME` | `java`                             |
+| `startupTimeout`                  | –                            | `60_000` ms                        |
+| `cacheDir` (`false` disables)     | –                            | `<tmpdir>/wiremock-testcontainers` |
+| `log`                             | –                            | `process.emitWarning`              |
+| `env` – for the CI check and defaults | –                        | `process.env`                      |
 
-In that situation the Docker-free loop still covers build, types, lint and
-100 % of `src/`:
+- **Speed:** a C1-only JIT and a class-data archive per JAR and Java in `cacheDir`. The first run
+  records it (a slower `stop()`); later runs boot ~2× faster and stop instantly. `JAVA_OPTS`
+  override the JVM flags.
+- **Differences:** WireMock listens on `127.0.0.1`; extension JARs join its class path;
+  `exec()`, networks and copying after start throw; leftover JVMs are killed on exit.
+- **Also exported** (from `…/no-docker` and the package root): `detectCI(env?)` – the CI variable
+  set, if any; `isNoDockerRequested(env?)` – whether `NO_DOCKER_ENV` (`WIREMOCK_NO_DOCKER`) is `1` or `true`.
 
-```bash
-pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit --coverage
-```
+## More
+
+- [`examples/`](./examples) – a standalone project using the package via `npm link`.
+- [CONTRIBUTING.md](./CONTRIBUTING.md) – scripts, CI and tests.
 
-Testcontainers resolves a runtime in this order; pick whichever your
-environment can provide:
-
-| Environment                                   | How to enable E2E                                                                                                                                   |
-|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
-| GitHub Codespaces / VS Code Dev Containers    | Use the provided `.devcontainer/devcontainer.json` – it adds the `docker-in-docker` feature, so a daemon runs inside the dev container.             |
-| Dev container with the host socket mounted    | Add the `docker-outside-of-docker` feature (or mount `/var/run/docker.sock`). Set `TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal` if port lookups fail. |
-| Remote or rootless daemon                     | `DOCKER_HOST=tcp://host:2375` (or `unix:///path/to/docker.sock`).                                                                                    |
-| Podman                                        | `DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock` and `TESTCONTAINERS_RYUK_DISABLED=true` (or run Ryuk privileged).                             |
-| No runtime can be installed (locked-down sandbox) | [Testcontainers Cloud](https://testcontainers.com/cloud/): run the agent and export `TC_CLOUD_TOKEN`; containers start remotely, tests run locally. |
-
-Sandboxes that have **no runtime binary and no socket at all** (as is the case
-for some hosted dev VMs) cannot run the E2E suite; the suite states this in its
-header comment and `pnpm test:unit` is the supported loop there.
-
-CI (`.github/workflows/main.yml`) runs build, typecheck, lint, unit tests
-(with coverage) and E2E tests as separate steps on `ubuntu-latest`, which
-ships with Docker, for every active Node LTS line.
-
-### Supply-chain controls
-
-- `pnpm install --frozen-lockfile` everywhere; the lockfile is the source of truth.
-- `pnpm-workspace.yaml` allow-lists the only packages permitted to run install
-  scripts (`ssh2`, `cpu-features`, `protobufjs` – all transitive via
-  `testcontainers`) and sets `minimumReleaseAge: 1440` so a version must be at
-  least 24 h old before it can be resolved.
-- CI runs `pnpm audit --prod --audit-level=high` on every push and PR;
-  Dependabot (`.github/dependabot.yml`) proposes weekly updates with a 3-day
-  cooldown, grouping dev tooling and leaving `testcontainers` bumps individual.
-- `pnpm build` runs [publint](https://publint.dev/) and
-  [Are the types wrong?](https://arethetypeswrong.github.io/) against the
-  emitted package; `size.yml` fails a PR if the tarball exceeds 25 kB.
-- Releases publish with npm provenance (`--provenance`, OIDC) after a
-  Docker-free verify step.
-
-### Fixtures and schema-based assertions
-
-The recorded WireMock session lives in `test/__mocks__/wiremock`:
-
-- `mappings/*.json` – one stub per endpoint (`request.url`, `response.status`,
-  `response.headers`, `response.bodyFileName`).
-- `__files/*.json` – the response bodies referenced by the mappings.
-
-`test/helpers/fixtures.ts` loads these from disk and declares the TypeScript
-shapes of every JSON payload. `test/helpers/assertions.ts` declares a
-`Schema<T>` per payload – stub mappings, the admin API response and each
-recorded body. The compiler requires a schema to cover **every** field of
-`T`; `expectObject` then asserts each field's shape, its recorded value and
-the exact key set (`partialOf` relaxes the key set for third-party shapes).
-
-The E2E suite runs a mapping-driven contract test for every file in
-`mappings/` (status, headers and full JSON body), so adding a new recorded
-mapping automatically puts it under test. Endpoint-specific suites add
-schema assertions, which the unit suite also runs against the fixture files
-themselves to catch drift early.
-
-Negative cases are hand-written stubs alongside the recorded ones:
-
-- `mapping-cards-bad-request-400.json` – `GET /cards?page=0` → 400 with a
-  validation error envelope.
-- `mapping-account-balance-server-error-500.json` – `GET /account/balance`
-  → 500 **only** when the request carries `X-Mock-Scenario: server-error`.
-  It sets `"priority": 1` so it wins over the recorded 200 stub for the same
-  URL; without the header the 200 stub is still served. This is the standard
-  WireMock pattern for simulating outages on demand.
-
-Unmatched requests (unknown path, wrong method) get WireMock's default 404.
-
-`test/__mocks__/standalone` holds loose fixtures for `withMapping()` and
-`withFiles()`. Their unit tests need no Docker: `test/helpers/container.ts`
-reads the tar archive Testcontainers would upload and asserts exactly which
-files land where.
-
-## Maintainers
-
-Maintained by [Hella Labs](https://hellaweb3.com/).
-
-## License
-
-MIT
+Maintained by [Hella Labs](https://hellaweb3.com/). [MIT](./LICENSE) licensed.