@hellaweb3/wiremock-testcontainers-nodejs 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1,194 +1 @@
-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);
-}
-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;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const require_runtime=require("./runtime-6blQsklJ.cjs");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");const PACKAGE_NAME=/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;function fail(message){throw new Error(message)}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(`/`));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 runtime=require_runtime.t();const startedContainer=runtime?await runtime.start(this.#startRequest()):await super.start();return new StartedWiremockContainer(startedContainer,`http://${startedContainer.getHost()}:${startedContainer.getMappedPort(8080)}`)}#startRequest(){return{image:this.imageName.string,name:this.createOpts.name,command:[...this.createOpts.Cmd??[]],environment:{...this.environment},directories:this.directoriesToCopy.map(({source,target})=>({source,target})),files:this.filesToCopy.map(({source,target})=>({source,target})),contents:this.contentsToCopy.map(({content,target})=>({content,target}))}}#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}};const ADMIN_PATH=`/__admin`;var StartedWiremockContainer=class extends testcontainers.AbstractStartedContainer{#rpcUrl;constructor(startedTestContainer,url){super(startedTestContainer);this.#rpcUrl=url}get rpcUrl(){return this.#rpcUrl}getUrl(path=``){if(path===``)return this.#rpcUrl;const suffix=path.startsWith(`/`)||path.startsWith(`?`)?path:`/${path}`;return`${this.#rpcUrl}${suffix}`}getAdminUrl(){return`${this.#rpcUrl}${ADMIN_PATH}`}getMappingUrl(){return`${this.getAdminUrl()}/mappings`}async isRunning(){try{const health=await fetch(`${this.getAdminUrl()}/health`);if(health.status!==404)return health.ok;return(await fetch(this.getMappingUrl())).ok}catch{return false}}async waitUntilReady(options={}){const{timeout=3e4,interval=250}=options;const deadline=Date.now()+timeout;const poll=async()=>{if(await this.isRunning())return;if(Date.now()>=deadline)throw new Error(`WireMock at ${this.#rpcUrl} was not ready within ${timeout}ms`);await new Promise(_resolve=>setTimeout(_resolve,interval));return poll()};await poll()}async reset(){await this.#admin(`POST`,`/reset`)}async resetRequests(){await this.#admin(`DELETE`,`/requests`)}async countRequests(request){const{count}=await(await this.#admin(`POST`,`/requests/count`,request)).json();return count}async findRequests(request){const{requests}=await(await this.#admin(`POST`,`/requests/find`,request)).json();return requests??[]}async#admin(method,path,body){const response=await fetch(`${this.getAdminUrl()}${path}`,{method,...body===void 0?{}:{headers:{"Content-Type":`application/json`},body:JSON.stringify(body)}});if(!response.ok){const detail=await response.text().catch(()=>``);throw new Error(`WireMock admin request ${method} ${ADMIN_PATH}${path} failed with ${response.status} ${response.statusText}${detail?`: ${detail}`:``}`)}return response}};exports.StartedWiremockContainer=StartedWiremockContainer;exports.WiremockContainer=WiremockContainer;

package/dist/index.d.cts

@@ -1,11 +1,7 @@
 import { AbstractStartedContainer, GenericContainer, StartedTestContainer } from "testcontainers";
 /** A path (relative to the working directory) or a `file:` URL. */
 type WiremockPath = string | URL;
-/**
- * A fixture file: a local path or `file:` URL, `{ file }`, a file inside an installed npm
- * package `{ package, file }` (its `exports` are ignored), or a file next to a module
- * `{ module: import.meta.url | __filename | __dirname, file }`.
- */
+/** A path or `file:` URL, `{ file }`, a file of an installed package `{ package, file }`, or one next to a module `{ module, file }`. */
 type WiremockFileSource = WiremockPath | {
   readonly file: WiremockPath;
 } | {
@@ -27,87 +23,102 @@ type WiremockMappingSource = WiremockFileSource | {
     readonly mappings: readonly WiremockStubMapping[];
   };
 };
-/** A file source; object forms may set `name`, the path below `__files/` (default: the base name). */
+/** A file source; object forms may set `name`, the path below `__files/`. */
 type WiremockStaticFile = WiremockPath | (Exclude<WiremockFileSource, WiremockPath> & {
   readonly name?: string;
 });
-/**
- * A Testcontainer for Wiremock. Stubs are registered with {@link withMappings} (a directory),
- * {@link withMapping} (one named stub) and {@link withFiles} (response bodies), in any
- * combination. Registrations are validated immediately and may not overwrite one another.
- *
- * @example
- * ```typescript
- * const container = await new WiremockContainer().start();
- * ```
- */
+/** A WireMock Testcontainer. Registrations are validated at once and may not overwrite one another. */
 export declare class WiremockContainer extends GenericContainer {
   #private;
-  /**
-   * Creates a new WiremockContainer.
-   * @example
-   * ```typescript
-   * const container = await new WiremockContainer().start();
-   * ```
-   * @param image The docker image to use. Defaults to "wiremock/wiremock".
-   */
+  /** @param image Docker image, default `wiremock/wiremock`. */
   constructor(image?: string);
   /**
-   * Adds mappings to the Wiremock container.
-   * @example
-   * ```typescript
-   * const container = await new WiremockContainer()
-   *   .withMappings("./test/__mocks__/wiremock")
-   *   .start();
-   * ```
-   * @param directory The directory containing `mappings/` and, optionally, `__files/`.
-   * @throws If `mappings/` is not a directory in `directory`, or a file would overwrite an earlier registration.
+   * Copies `directory/mappings/` (required) and `directory/__files/` (optional) into the container.
+   * @throws If `mappings/` is missing or a file would overwrite an earlier registration.
    */
   withMappings(directory: string): this;
   /**
-   * Registers one stub at `mappings/<name>.json`, validated and copied byte-for-byte.
-   * @example
-   * ```typescript
-   * new WiremockContainer()
-   *   .withMapping("cards", "./test/fixtures/cards.json")
-   *   .withMapping("user", { package: "@acme/fixtures", file: "wiremock/user.json" })
-   *   .withMapping("balance", { module: import.meta.url, file: "./balance.json" })
-   *   .withMapping("ping", { json: { request: { url: "/ping" }, response: { status: 200 } } });
-   * ```
-   * @param name File name below `mappings/`, may contain `/`; `.json` is appended unless present.
-   * @throws If the name or source is invalid, the source is not a WireMock mapping, or it would overwrite an earlier registration.
+   * Registers one stub at `mappings/<name>.json` (`name` may contain `/`).
+   * @example .withMapping("ping", { json: { request: { url: "/ping" }, response: { status: 200 } } })
+   * @throws If the source is invalid, not a WireMock stub, or would overwrite an earlier registration.
    */
   withMapping(name: string, source: WiremockMappingSource): this;
   /**
-   * Registers response bodies at `__files/<name>` (default: the base name), copied as-is.
-   * @example
-   * ```typescript
-   * new WiremockContainer().withFiles("./test/fixtures/body.json", { file: "./logo.png", name: "img/logo.png" });
-   * ```
-   * @throws If a source or name is invalid, or a file would overwrite an earlier registration; nothing is registered then.
+   * Registers response bodies at `__files/<name>` (default: the base name). All or nothing.
+   * @throws If a source or name is invalid or a file would overwrite an earlier registration.
    */
   withFiles(...files: WiremockStaticFile[]): this;
-  /**
-   * Starts the container and returns a {@link StartedWiremockContainer}.
-   * @returns A promise that resolves to the started container.
-   */
+  /** Starts WireMock – in Docker, or locally once `./no-docker` is installed. */
   override start(): Promise<StartedWiremockContainer>;
 }
-/**
- * A started Wiremock container with helper methods for interacting with the node.
- */
+/** WireMock [request-matching](https://wiremock.org/docs/request-matching/) criteria; unknown fields pass through. */
+export interface WiremockRequestCriteria {
+  /** E.g. `"GET"`; `"ANY"` matches every method. */
+  readonly method?: string;
+  /** Exact path and query string. */
+  readonly url?: string;
+  /** Exact path, any query string. */
+  readonly urlPath?: string;
+  /** Regex for the path. */
+  readonly urlPathPattern?: string;
+  /** Regex for path and query string. */
+  readonly urlPattern?: string;
+  /** E.g. `{ "Content-Type": { equalTo: "application/json" } }`. */
+  readonly headers?: Readonly<Record<string, unknown>>;
+  /** E.g. `{ page: { equalTo: "1" } }`. */
+  readonly queryParameters?: Readonly<Record<string, unknown>>;
+  /** E.g. `[{ equalToJson: { id: 1 } }]`. */
+  readonly bodyPatterns?: readonly object[];
+  readonly [field: string]: unknown;
+}
+/** A request from WireMock's journal; fields not modelled here are kept as-is. */
+export interface RecordedRequest {
+  readonly id?: string;
+  /** Path and query string, e.g. `"/cards?page=1"`. */
+  readonly url: string;
+  readonly absoluteUrl?: string;
+  readonly method: string;
+  readonly headers?: Readonly<Record<string, unknown>>;
+  readonly queryParams?: Readonly<Record<string, unknown>>;
+  readonly body?: string;
+  /** Epoch milliseconds. */
+  readonly loggedDate?: number;
+  readonly [field: string]: unknown;
+}
+/** Options for {@link StartedWiremockContainer.waitUntilReady}. */
+export interface WaitUntilReadyOptions {
+  /** Milliseconds before giving up. Default `30_000`. */
+  readonly timeout?: number;
+  /** Milliseconds between probes. Default `250`. */
+  readonly interval?: number;
+}
+/** A started WireMock container with URL, health, reset and verification helpers. */
 export declare class StartedWiremockContainer extends AbstractStartedContainer {
   #private;
-  /**
-   * Creates a new StartedWiremockContainer.
-   * @param startedTestContainer The underlying TestContainer.
-   * @param url The URL of the started container.
-   */
+  /** Created by {@link WiremockContainer.start}; `url` is WireMock's base URL. */
   constructor(startedTestContainer: StartedTestContainer, url: string);
+  /** Base URL, e.g. `http://localhost:32768`. */
+  get rpcUrl(): string;
+  /** Absolute URL for `path`, e.g. `getUrl("cards?page=1")`; no argument → {@link rpcUrl}. */
+  getUrl(path?: string): string;
+  /** Admin API base URL: `<rpcUrl>/__admin`. */
+  getAdminUrl(): string;
+  /** Stub mappings endpoint: `<rpcUrl>/__admin/mappings`. */
+  getMappingUrl(): string;
+  /** Whether WireMock responds healthily. Never throws. */
+  isRunning(): Promise<boolean>;
   /**
-   * Gets the URL of the Wiremock node.
+   * Polls {@link isRunning} until healthy.
+   * @throws If not healthy within `options.timeout`.
    */
-  get rpcUrl(): string;
+  waitUntilReady(options?: WaitUntilReadyOptions): Promise<void>;
+  /** Restores registered stubs and scenarios and clears the journal – no restart. */
+  reset(): Promise<void>;
+  /** Clears the request journal; stubs are kept. */
+  resetRequests(): Promise<void>;
+  /** Number of journal entries matching `request` since the last reset. */
+  countRequests(request: WiremockRequestCriteria): Promise<number>;
+  /** Journal entries matching `request` since the last reset. */
+  findRequests(request: WiremockRequestCriteria): Promise<RecordedRequest[]>;
 }
-export type { WiremockFileSource, WiremockMappingSource, WiremockPath, WiremockStaticFile, WiremockStubMapping };
-//# sourceMappingURL=index.d.cts.map
+export type { WiremockFileSource, WiremockMappingSource, WiremockPath, WiremockStaticFile, WiremockStubMapping };

package/dist/index.d.ts

@@ -1,11 +1,7 @@
 import { AbstractStartedContainer, GenericContainer, StartedTestContainer } from "testcontainers";
 /** A path (relative to the working directory) or a `file:` URL. */
 type WiremockPath = string | URL;
-/**
- * A fixture file: a local path or `file:` URL, `{ file }`, a file inside an installed npm
- * package `{ package, file }` (its `exports` are ignored), or a file next to a module
- * `{ module: import.meta.url | __filename | __dirname, file }`.
- */
+/** A path or `file:` URL, `{ file }`, a file of an installed package `{ package, file }`, or one next to a module `{ module, file }`. */
 type WiremockFileSource = WiremockPath | {
   readonly file: WiremockPath;
 } | {
@@ -27,87 +23,102 @@ type WiremockMappingSource = WiremockFileSource | {
     readonly mappings: readonly WiremockStubMapping[];
   };
 };
-/** A file source; object forms may set `name`, the path below `__files/` (default: the base name). */
+/** A file source; object forms may set `name`, the path below `__files/`. */
 type WiremockStaticFile = WiremockPath | (Exclude<WiremockFileSource, WiremockPath> & {
   readonly name?: string;
 });
-/**
- * A Testcontainer for Wiremock. Stubs are registered with {@link withMappings} (a directory),
- * {@link withMapping} (one named stub) and {@link withFiles} (response bodies), in any
- * combination. Registrations are validated immediately and may not overwrite one another.
- *
- * @example
- * ```typescript
- * const container = await new WiremockContainer().start();
- * ```
- */
+/** A WireMock Testcontainer. Registrations are validated at once and may not overwrite one another. */
 export declare class WiremockContainer extends GenericContainer {
   #private;
-  /**
-   * Creates a new WiremockContainer.
-   * @example
-   * ```typescript
-   * const container = await new WiremockContainer().start();
-   * ```
-   * @param image The docker image to use. Defaults to "wiremock/wiremock".
-   */
+  /** @param image Docker image, default `wiremock/wiremock`. */
   constructor(image?: string);
   /**
-   * Adds mappings to the Wiremock container.
-   * @example
-   * ```typescript
-   * const container = await new WiremockContainer()
-   *   .withMappings("./test/__mocks__/wiremock")
-   *   .start();
-   * ```
-   * @param directory The directory containing `mappings/` and, optionally, `__files/`.
-   * @throws If `mappings/` is not a directory in `directory`, or a file would overwrite an earlier registration.
+   * Copies `directory/mappings/` (required) and `directory/__files/` (optional) into the container.
+   * @throws If `mappings/` is missing or a file would overwrite an earlier registration.
    */
   withMappings(directory: string): this;
   /**
-   * Registers one stub at `mappings/<name>.json`, validated and copied byte-for-byte.
-   * @example
-   * ```typescript
-   * new WiremockContainer()
-   *   .withMapping("cards", "./test/fixtures/cards.json")
-   *   .withMapping("user", { package: "@acme/fixtures", file: "wiremock/user.json" })
-   *   .withMapping("balance", { module: import.meta.url, file: "./balance.json" })
-   *   .withMapping("ping", { json: { request: { url: "/ping" }, response: { status: 200 } } });
-   * ```
-   * @param name File name below `mappings/`, may contain `/`; `.json` is appended unless present.
-   * @throws If the name or source is invalid, the source is not a WireMock mapping, or it would overwrite an earlier registration.
+   * Registers one stub at `mappings/<name>.json` (`name` may contain `/`).
+   * @example .withMapping("ping", { json: { request: { url: "/ping" }, response: { status: 200 } } })
+   * @throws If the source is invalid, not a WireMock stub, or would overwrite an earlier registration.
    */
   withMapping(name: string, source: WiremockMappingSource): this;
   /**
-   * Registers response bodies at `__files/<name>` (default: the base name), copied as-is.
-   * @example
-   * ```typescript
-   * new WiremockContainer().withFiles("./test/fixtures/body.json", { file: "./logo.png", name: "img/logo.png" });
-   * ```
-   * @throws If a source or name is invalid, or a file would overwrite an earlier registration; nothing is registered then.
+   * Registers response bodies at `__files/<name>` (default: the base name). All or nothing.
+   * @throws If a source or name is invalid or a file would overwrite an earlier registration.
    */
   withFiles(...files: WiremockStaticFile[]): this;
-  /**
-   * Starts the container and returns a {@link StartedWiremockContainer}.
-   * @returns A promise that resolves to the started container.
-   */
+  /** Starts WireMock – in Docker, or locally once `./no-docker` is installed. */
   override start(): Promise<StartedWiremockContainer>;
 }
-/**
- * A started Wiremock container with helper methods for interacting with the node.
- */
+/** WireMock [request-matching](https://wiremock.org/docs/request-matching/) criteria; unknown fields pass through. */
+export interface WiremockRequestCriteria {
+  /** E.g. `"GET"`; `"ANY"` matches every method. */
+  readonly method?: string;
+  /** Exact path and query string. */
+  readonly url?: string;
+  /** Exact path, any query string. */
+  readonly urlPath?: string;
+  /** Regex for the path. */
+  readonly urlPathPattern?: string;
+  /** Regex for path and query string. */
+  readonly urlPattern?: string;
+  /** E.g. `{ "Content-Type": { equalTo: "application/json" } }`. */
+  readonly headers?: Readonly<Record<string, unknown>>;
+  /** E.g. `{ page: { equalTo: "1" } }`. */
+  readonly queryParameters?: Readonly<Record<string, unknown>>;
+  /** E.g. `[{ equalToJson: { id: 1 } }]`. */
+  readonly bodyPatterns?: readonly object[];
+  readonly [field: string]: unknown;
+}
+/** A request from WireMock's journal; fields not modelled here are kept as-is. */
+export interface RecordedRequest {
+  readonly id?: string;
+  /** Path and query string, e.g. `"/cards?page=1"`. */
+  readonly url: string;
+  readonly absoluteUrl?: string;
+  readonly method: string;
+  readonly headers?: Readonly<Record<string, unknown>>;
+  readonly queryParams?: Readonly<Record<string, unknown>>;
+  readonly body?: string;
+  /** Epoch milliseconds. */
+  readonly loggedDate?: number;
+  readonly [field: string]: unknown;
+}
+/** Options for {@link StartedWiremockContainer.waitUntilReady}. */
+export interface WaitUntilReadyOptions {
+  /** Milliseconds before giving up. Default `30_000`. */
+  readonly timeout?: number;
+  /** Milliseconds between probes. Default `250`. */
+  readonly interval?: number;
+}
+/** A started WireMock container with URL, health, reset and verification helpers. */
 export declare class StartedWiremockContainer extends AbstractStartedContainer {
   #private;
-  /**
-   * Creates a new StartedWiremockContainer.
-   * @param startedTestContainer The underlying TestContainer.
-   * @param url The URL of the started container.
-   */
+  /** Created by {@link WiremockContainer.start}; `url` is WireMock's base URL. */
   constructor(startedTestContainer: StartedTestContainer, url: string);
+  /** Base URL, e.g. `http://localhost:32768`. */
+  get rpcUrl(): string;
+  /** Absolute URL for `path`, e.g. `getUrl("cards?page=1")`; no argument → {@link rpcUrl}. */
+  getUrl(path?: string): string;
+  /** Admin API base URL: `<rpcUrl>/__admin`. */
+  getAdminUrl(): string;
+  /** Stub mappings endpoint: `<rpcUrl>/__admin/mappings`. */
+  getMappingUrl(): string;
+  /** Whether WireMock responds healthily. Never throws. */
+  isRunning(): Promise<boolean>;
   /**
-   * Gets the URL of the Wiremock node.
+   * Polls {@link isRunning} until healthy.
+   * @throws If not healthy within `options.timeout`.
    */
-  get rpcUrl(): string;
+  waitUntilReady(options?: WaitUntilReadyOptions): Promise<void>;
+  /** Restores registered stubs and scenarios and clears the journal – no restart. */
+  reset(): Promise<void>;
+  /** Clears the request journal; stubs are kept. */
+  resetRequests(): Promise<void>;
+  /** Number of journal entries matching `request` since the last reset. */
+  countRequests(request: WiremockRequestCriteria): Promise<number>;
+  /** Journal entries matching `request` since the last reset. */
+  findRequests(request: WiremockRequestCriteria): Promise<RecordedRequest[]>;
 }
-export type { WiremockFileSource, WiremockMappingSource, WiremockPath, WiremockStaticFile, WiremockStubMapping };
-//# sourceMappingURL=index.d.ts.map
+export type { WiremockFileSource, WiremockMappingSource, WiremockPath, WiremockStaticFile, WiremockStubMapping };