@hellaweb3/wiremock-testcontainers-nodejs 0.1.3 → 0.2.0

package/README.md

@@ -25,8 +25,10 @@
 a [WireMock](https://wiremock.org/)
 instance with [Testcontainers](https://node.testcontainers.org/). It provides a
 fluent API to configure and start WireMock
-containers, including support for loading mappings and files from recorded
-Wiremock sessions.
+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
 
@@ -34,35 +36,79 @@ Wiremock sessions.
 pnpm add -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).
+
+**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.
+
+**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.
+
 ## Usage
 
 ### Basic Example
 
-Assuming you placed your mappings in `test/__mocks__/wiremock`,
+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.
 
 ```typescript
-import { WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";
+import { afterAll, beforeAll, describe, expect, it } from "vitest"; // or jest
+import {
+  StartedWiremockContainer,
+  WiremockContainer,
+} from "@hellaweb3/wiremock-testcontainers-nodejs";
 
-describe("E2E Test", () => {
-  let container;
+describe("Cards API", () => {
+  let container: StartedWiremockContainer;
 
   beforeAll(async () => {
-    container = await new WiremockContainer()
-      .withMappings("./test/__mocks__/wiremock")
-      .start();
-  }, 60000);
+    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("should interact with WireMock", async () => {
-    const url = container.rpcUrl;
-    // Your test logic here
+  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);
   });
 });
 ```
 
+`WiremockContainer` extends Testcontainers' `GenericContainer`, so every
+builder method is available – for example to pin an image, name the container
+or pass WireMock CLI flags:
+
+```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();
+```
+
 ### With Mappings and Files
 
 WireMock uses a specific directory structure for mappings and static files. This
@@ -88,21 +134,139 @@ const container = await new WiremockContainer()
   .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"`:
+
+```json
+{ "request": { "method": "GET", "url": "/health" }, "response": { "status": 200, "jsonBody": { "status": "UP" } } }
+```
+
+#### Mapping sources
+
+**Local file** – a path relative to the working directory, or absolute:
+
+```typescript
+new WiremockContainer().withMapping("health", "./test/fixtures/health.json"); // → mappings/health.json
+```
+
+**`file:` URL** – e.g. relative to the current module:
+
+```typescript
+new WiremockContainer().withMapping("health", new URL("./fixtures/health.json", import.meta.url));
+```
+
+**`{ file }`** – a path or URL in object form:
+
+```typescript
+new WiremockContainer().withMapping("health", { file: "./test/fixtures/health.json" });
+```
+
+**`{ 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:
+
+```typescript
+new WiremockContainer().withMapping("cards/list", { package: "@acme/api-fixtures", file: "wiremock/cards.json" }); // → mappings/cards/list.json
+```
+
+**`{ module, file }`** – a file relative to a module, like a Java classpath
+resource:
+
+```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)
+```
+
+**`{ json }` (object)** – an inline stub, serialised as-is:
+
+```typescript
+new WiremockContainer().withMapping("ping", {
+  json: { request: { method: "GET", url: "/ping" }, response: { status: 200, body: "pong" } },
+});
+```
+
+**`{ json }` (string)** – inline JSON, copied verbatim:
+
+```typescript
+new WiremockContainer().withMapping("ping", { json: '{ "request": { "url": "/ping" }, "response": { "status": 200 } }' });
+```
+
+**Several stubs in one mapping** – any source may hold `{ "mappings": [...] }`:
+
+```typescript
+new WiremockContainer().withMapping("greetings", {
+  json: {
+    mappings: [
+      { request: { url: "/hello" }, response: { status: 200, body: "Hello" } },
+      { request: { url: "/bye" }, response: { status: 200, body: "Bye" } },
+    ],
+  },
+});
+```
+
+#### Static files
+
+`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`:
+
+```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
+);
+```
+
+#### 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();
+```
+
+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)`: Mounts `mappings` and `__files` from the
-  specified local directory to the container.
+- `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
 
@@ -111,11 +275,127 @@ const container = await new WiremockContainer()
 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., 5s in Jest). Always set a higher timeout for
+   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:
+
+```
+Could not find a working container runtime strategy
+```
+
+In that situation the Docker-free loop still covers build, types, lint and
+100 % of `src/`:
+
+```bash
+pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit --coverage
+```
+
+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/).

package/dist/index.cjs

@@ -1,76 +1,194 @@
-Object.defineProperty(exports, '__esModule', { value: true });
-
-var testcontainers = require('testcontainers');
-
-/**
- * A Testcontainer for Wiremock.
- *
- * @example
- * ```typescript
- * const container = await new WiremockContainer().start();
- * ```
- */ class WiremockContainer extends testcontainers.GenericContainer {
-    /**
-   * Creates a new WiremockContainer.
-   * @example
-   * ```typescript
-   * const container = await new WiremockContainer().start();
-   * ```
-   * @param image The docker image to use. Defaults to "wiremock/wiremock".
-   */ constructor(image = "wiremock/wiremock"){
-        super(image);
-        this.withExposedPorts(8080);
-        this.withWaitStrategy(testcontainers.Wait.forListeningPorts());
-    }
-    /**
-   * Adds mappings to the Wiremock container.
-   * @example
-   * ```typescript
-   * const container = await new WiremockContainer()
-   *   .withMappings("./test/__mocks__/wiremock")
-   *   .start();
-   * ```
-   * @param directory The directory containing the mappings and __files.
-   */ withMappings(directory) {
-        this.withCopyDirectoriesToContainer([
-            {
-                source: `${directory}/__files`,
-                target: "/home/wiremock/__files"
-            }
-        ]);
-        this.withCopyDirectoriesToContainer([
-            {
-                source: `${directory}/mappings`,
-                target: "/home/wiremock/mappings"
-            }
-        ]);
-        return this;
-    }
-    /**
-   * Starts the container and returns a {@link StartedWiremockContainer}.
-   * @returns A promise that resolves to the started container.
-   */ async start() {
-        const startedContainer = await super.start();
-        return new StartedWiremockContainer(startedContainer, `http://${startedContainer.getHost()}:${startedContainer.getMappedPort(8080)}`);
-    }
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let testcontainers = require("testcontainers");
+let node_module = require("node:module");
+let node_url = require("node:url");
+// src/sources.ts
+const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;
+function fail(message) {
+	throw new Error(message);
 }
-/**
- * A started Wiremock container with helper methods for interacting with the node.
- */ class StartedWiremockContainer extends testcontainers.AbstractStartedContainer {
-    /**
-   * Creates a new StartedWiremockContainer.
-   * @param startedTestContainer The underlying TestContainer.
-   * @param url The URL of the started container.
-   */ constructor(startedTestContainer, url){
-        super(startedTestContainer);
-        this._rpcUrl = url;
-    }
-    /**
-   * Gets the URL of the Wiremock node.
-   */ get rpcUrl() {
-        return this._rpcUrl;
-    }
+function within(context, fn) {
+	try {
+		return fn();
+	} catch (error) {
+		throw new Error(`${context}: ${error.message}`, { cause: error });
+	}
 }
-
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const show = (value) => value instanceof URL ? value.href : JSON.stringify(value) ?? String(value);
+const text = (value, field) => typeof value === "string" && value.trim() !== "" ? value : fail(`"${field}" must be a non-empty string, got ${show(value)}`);
+const toPath = (value, field) => {
+	if (!(value instanceof URL) && !text(value, field).startsWith("file:")) return (0, node_path.resolve)(value);
+	try {
+		return (0, node_url.fileURLToPath)(value);
+	} catch {
+		return fail(`"${field}" must be a path or a file: URL, got ${show(value)}`);
+	}
+};
+const existingFile = (path) => {
+	const stats = (0, node_fs.statSync)(path, { throwIfNoEntry: false });
+	return stats?.isFile() ? path : fail(`"${path}" ${stats ? "is not a file" : "does not exist"}`);
+};
+const packageRoot = (name) => {
+	if (!PACKAGE_NAME.test(name)) fail(`"${name}" is not a valid npm package name`);
+	return ((0, node_module.createRequire)((0, node_path.join)(process.cwd(), "noop.js")).resolve.paths(name) ?? []).map((dir) => (0, node_path.join)(dir, name)).find((dir) => (0, node_fs.existsSync)((0, node_path.join)(dir, "package.json"))) ?? fail(`package "${name}" is not installed (searched from "${process.cwd()}")`);
+};
+function resolveFile(source) {
+	if (typeof source === "string" || source instanceof URL) return existingFile(toPath(source, "source"));
+	if (!isRecord(source)) return fail(`unsupported source ${show(source)}; expected a path, a file: URL, { file }, { package, file } or { module, file }`);
+	const { file, package: pkg, module } = source;
+	if (pkg !== void 0 && module !== void 0) fail("a source may set \"package\" or \"module\", not both");
+	if (pkg !== void 0) {
+		const root = packageRoot(text(pkg, "package"));
+		const path = (0, node_path.resolve)(root, text(file, "file"));
+		return (0, node_path.relative)(root, path).split(node_path.sep)[0] === ".." ? fail(`"${String(file)}" must point to a file inside package "${pkg}"`) : existingFile(path);
+	}
+	if (module === void 0) return existingFile(toPath(file, "file"));
+	const anchor = toPath(module, "module");
+	return existingFile((0, node_path.resolve)((0, node_fs.statSync)(anchor, { throwIfNoEntry: false })?.isDirectory() ? anchor : (0, node_path.dirname)(anchor), text(file, "file")));
+}
+const containerName = (name) => {
+	const value = text(name, "name");
+	return value.split("/").some((part) => [
+		"",
+		".",
+		".."
+	].includes(part) || /[\\\0]/u.test(part)) ? fail(`name "${value}" must be a relative path using "/" separators, without empty, "." or ".." segments`) : value;
+};
+const inlineJson = (json) => typeof json === "string" ? json : JSON.stringify(json, null, 2) ?? fail("\"json\" must be a JSON string or an object");
+const parseJson = (json) => {
+	try {
+		return JSON.parse(json);
+	} catch (error) {
+		return fail(`invalid JSON (${error.message})`);
+	}
+};
+function stubIds(json) {
+	const value = parseJson(json);
+	const many = isRecord(value) && "mappings" in value;
+	const stubs = many ? value.mappings : [value];
+	if (!Array.isArray(stubs) || stubs.length === 0) fail("\"mappings\" must be a non-empty array of stub mappings");
+	return stubs.flatMap((stub, index) => {
+		if (!isRecord(stub) || !isRecord(stub.request) || !isRecord(stub.response)) fail(`${many ? `mappings[${index}]` : "the mapping"} is not a WireMock stub mapping ("request" and "response" objects are required)`);
+		const id = stub.id ?? stub.uuid;
+		return typeof id === "string" ? [id] : [];
+	});
+}
+const stubIdsOf = (path) => {
+	try {
+		return path.endsWith(".json") ? stubIds((0, node_fs.readFileSync)(path, "utf8")) : [];
+	} catch {
+		return [];
+	}
+};
+const listFiles = (dir) => (0, node_fs.readdirSync)(dir, {
+	recursive: true,
+	withFileTypes: true
+}).filter((entry) => !entry.isDirectory()).map((entry) => (0, node_path.relative)(dir, (0, node_path.join)(entry.parentPath, entry.name)).split(node_path.sep).join("/"));
+// src/index.ts
+const MAPPINGS = "/home/wiremock/mappings";
+const FILES = "/home/wiremock/__files";
+const INLINE = "inline JSON";
+var WiremockContainer = class extends testcontainers.GenericContainer {
+	#origins = /* @__PURE__ */ new Map();
+	#stubIds = /* @__PURE__ */ new Map();
+	constructor(image = "wiremock/wiremock") {
+		super(image);
+		this.withExposedPorts(8080);
+		this.withWaitStrategy(testcontainers.Wait.forListeningPorts());
+	}
+	withMappings(directory) {
+		within("WiremockContainer.withMappings", () => {
+			const mappings = (0, node_path.join)(directory, "mappings");
+			if (!(0, node_fs.existsSync)(mappings)) fail(`"${mappings}" does not exist`);
+			if (!(0, node_fs.statSync)(mappings).isDirectory()) fail(`"${mappings}" is not a directory`);
+			const files = (0, node_path.join)(directory, "__files");
+			const dirs = [{
+				source: mappings,
+				target: MAPPINGS
+			}, ...(0, node_fs.existsSync)(files) ? [{
+				source: files,
+				target: FILES
+			}] : []];
+			this.#claim(dirs.flatMap(({ source, target }) => listFiles(source).map((name) => ({
+				target: node_path.posix.join(target, name),
+				origin: (0, node_path.resolve)(source, name),
+				ids: target === MAPPINGS ? stubIdsOf((0, node_path.join)(source, name)) : []
+			}))));
+			this.withCopyDirectoriesToContainer(dirs);
+		});
+		return this;
+	}
+	withMapping(name, source) {
+		within(`WiremockContainer.withMapping("${name}")`, () => {
+			const file = containerName(name);
+			const target = node_path.posix.join(MAPPINGS, file.endsWith(".json") ? file : `${file}.json`);
+			const inline = isRecord(source) && "json" in source;
+			const origin = inline ? INLINE : resolveFile(source);
+			const content = inline ? inlineJson(source.json) : (0, node_fs.readFileSync)(origin);
+			const ids = within(origin, () => stubIds(content.toString()));
+			this.withCopyContentToContainer(this.#claim([{
+				target,
+				origin,
+				ids
+			}]).map(() => ({
+				content,
+				target
+			})));
+		});
+		return this;
+	}
+	withFiles(...files) {
+		within("WiremockContainer.withFiles", () => {
+			const claims = files.map((file) => {
+				const origin = resolveFile(file);
+				const name = isRecord(file) && file.name !== void 0 ? containerName(file.name) : (0, node_path.basename)(origin);
+				return {
+					target: node_path.posix.join(FILES, name),
+					origin
+				};
+			});
+			this.withCopyFilesToContainer(this.#claim(claims).map(({ origin, target }) => ({
+				source: origin,
+				target
+			})));
+		});
+		return this;
+	}
+	async start() {
+		const startedContainer = await super.start();
+		return new StartedWiremockContainer(startedContainer, `http://${startedContainer.getHost()}:${startedContainer.getMappedPort(8080)}`);
+	}
+	#claim(claims) {
+		const origins = new Map(this.#origins);
+		const owners = new Map(this.#stubIds);
+		const fresh = claims.filter(({ target, origin, ids = [] }) => {
+			const existing = origins.get(target);
+			if (existing === origin && origin !== INLINE) return false;
+			if (existing) fail(`"${target}" is already registered from ${existing}; registering ${origin} would overwrite it`);
+			for (const id of ids) {
+				const owner = owners.get(id);
+				if (owner) fail(`stub id "${id}" in ${origin} is already used by "${owner}"; WireMock refuses to start with duplicate stub ids`);
+				owners.set(id, target);
+			}
+			origins.set(target, origin);
+			return true;
+		});
+		[this.#origins, this.#stubIds] = [origins, owners];
+		return fresh;
+	}
+};
+var StartedWiremockContainer = class extends testcontainers.AbstractStartedContainer {
+	#rpcUrl;
+	constructor(startedTestContainer, url) {
+		super(startedTestContainer);
+		this.#rpcUrl = url;
+	}
+	get rpcUrl() {
+		return this.#rpcUrl;
+	}
+};
 exports.StartedWiremockContainer = StartedWiremockContainer;
 exports.WiremockContainer = WiremockContainer;