@hellaweb3/wiremock-testcontainers-nodejs 0.2.1 → 0.4.0

package/src/index.ts

@@ -1,210 +0,0 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, join, posix, resolve } from "node:path";
-import {
-  AbstractStartedContainer,
-  GenericContainer,
-  type StartedTestContainer,
-  Wait,
-} from "testcontainers";
-import {
-  containerName,
-  fail,
-  inlineJson,
-  isRecord,
-  listFiles,
-  resolveFile,
-  stubIds,
-  stubIdsOf,
-  within,
-  type WiremockMappingSource,
-  type WiremockStaticFile,
-} from "./sources";
-
-export type {
-  WiremockFileSource,
-  WiremockMappingSource,
-  WiremockPath,
-  WiremockStaticFile,
-  WiremockStubMapping,
-} from "./sources";
-
-const MAPPINGS = "/home/wiremock/mappings";
-const FILES = "/home/wiremock/__files";
-const INLINE = "inline JSON";
-
-/** A file a registration places in the container. */
-interface Claim {
-  readonly target: string;
-  /** The absolute source path, or {@link INLINE}. */
-  readonly origin: string;
-  readonly ids?: readonly 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();
- * ```
- */
-export class WiremockContainer extends GenericContainer {
-  /** Container path → origin of every registered file. */
-  #origins = new Map<string, string>();
-  /** Stub id → container path declaring it: WireMock refuses to start with duplicates. */
-  #stubIds = new Map<string, string>();
-
-  /**
-   * 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: string = "wiremock/wiremock") {
-    super(image);
-    this.withExposedPorts(8080);
-    this.withWaitStrategy(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 `mappings/` and, optionally, `__files/`.
-   * @throws If `mappings/` is not a directory in `directory`, or a file would overwrite an earlier registration.
-   */
-  public withMappings(directory: string): this {
-    within("WiremockContainer.withMappings", () => {
-      const mappings = join(directory, "mappings");
-      if (!existsSync(mappings)) fail(`"${mappings}" does not exist`);
-      if (!statSync(mappings).isDirectory()) fail(`"${mappings}" is not a directory`);
-      // `__files/` is optional: mappings may define their response bodies inline.
-      const files = join(directory, "__files");
-      const dirs = [{ source: mappings, target: MAPPINGS }, ...(existsSync(files) ? [{ source: files, target: FILES }] : [])];
-      this.#claim(
-        dirs.flatMap(({ source, target }) =>
-          listFiles(source).map((name) => ({
-            target: posix.join(target, name),
-            origin: resolve(source, name),
-            ids: target === MAPPINGS ? stubIdsOf(join(source, name)) : [],
-          })),
-        ),
-      );
-      this.withCopyDirectoriesToContainer(dirs);
-    });
-    return 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.
-   */
-  public withMapping(name: string, source: WiremockMappingSource): this {
-    within(`WiremockContainer.withMapping("${name}")`, () => {
-      const file = containerName(name);
-      const target = 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) : readFileSync(origin);
-      const ids = within(origin, () => stubIds(content.toString()));
-      this.withCopyContentToContainer(this.#claim([{ target, origin, ids }]).map(() => ({ content, target })));
-    });
-    return 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.
-   */
-  public withFiles(...files: WiremockStaticFile[]): this {
-    within("WiremockContainer.withFiles", () => {
-      const claims = files.map((file) => {
-        const origin = resolveFile(file);
-        const name = isRecord(file) && file.name !== undefined ? containerName(file.name) : basename(origin);
-        return { target: posix.join(FILES, name), origin };
-      });
-      this.withCopyFilesToContainer(this.#claim(claims).map(({ origin, target }) => ({ source: origin, target })));
-    });
-    return this;
-  }
-
-  /**
-   * Starts the container and returns a {@link StartedWiremockContainer}.
-   * @returns A promise that resolves to the started container.
-   */
-  public override async start(): Promise<StartedWiremockContainer> {
-    const startedContainer = await super.start();
-    return new StartedWiremockContainer(
-      startedContainer,
-      `http://${startedContainer.getHost()}:${startedContainer.getMappedPort(8080)}`,
-    );
-  }
-
-  /**
-   * Records `claims` – all or nothing – unless one would overwrite a file from another origin or
-   * reuse a stub id. Returns the claims not already registered from the same file.
-   */
-  #claim<T extends Claim>(claims: readonly T[]): T[] {
-    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;
-  }
-}
-
-/**
- * A started Wiremock container with helper methods for interacting with the node.
- */
-export class StartedWiremockContainer extends AbstractStartedContainer {
-  readonly #rpcUrl: string;
-
-  /**
-   * Creates a new StartedWiremockContainer.
-   * @param startedTestContainer The underlying TestContainer.
-   * @param url The URL of the started container.
-   */
-  constructor(startedTestContainer: StartedTestContainer, url: string) {
-    super(startedTestContainer);
-    this.#rpcUrl = url;
-  }
-
-  /**
-   * Gets the URL of the Wiremock node.
-   */
-  get rpcUrl(): string {
-    return this.#rpcUrl;
-  }
-}

package/src/sources.ts

@@ -1,143 +0,0 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-
-/** A path (relative to the working directory) or a `file:` URL. */
-export 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 }`.
- */
-export type WiremockFileSource =
-  | WiremockPath
-  | { readonly file: WiremockPath }
-  | { readonly package: string; readonly file: string }
-  | { readonly module: WiremockPath; readonly file: string };
-
-/** A WireMock stub; fields besides `request` and `response` are passed through. */
-export interface WiremockStubMapping {
-  readonly request: object;
-  readonly response: object;
-  readonly [field: string]: unknown;
-}
-
-/** A file source, or inline JSON: a string, a stub or `{ mappings: [...] }`. */
-export type WiremockMappingSource =
-  | WiremockFileSource
-  | { readonly json: string | WiremockStubMapping | { readonly mappings: readonly WiremockStubMapping[] } };
-
-/** A file source; object forms may set `name`, the path below `__files/` (default: the base name). */
-export type WiremockStaticFile = WiremockPath | (Exclude<WiremockFileSource, WiremockPath> & { readonly name?: string });
-
-const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;
-
-export function fail(message: string): never {
-  throw new Error(message);
-}
-
-/** Runs `fn`, prefixing the message of any error it throws with `context`. */
-export function within<T>(context: string, fn: () => T): T {
-  try {
-    return fn();
-  } catch (error) {
-    throw new Error(`${context}: ${(error as Error).message}`, { cause: error });
-  }
-}
-
-export const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-const show = (value: unknown): string => (value instanceof URL ? value.href : (JSON.stringify(value) ?? String(value)));
-
-const text = (value: unknown, field: string): string =>
-  typeof value === "string" && value.trim() !== "" ? value : fail(`"${field}" must be a non-empty string, got ${show(value)}`);
-
-const toPath = (value: unknown, field: string): string => {
-  if (!(value instanceof URL) && !text(value, field).startsWith("file:")) return resolve(value as string);
-  try {
-    return fileURLToPath(value as WiremockPath);
-  } catch {
-    return fail(`"${field}" must be a path or a file: URL, got ${show(value)}`);
-  }
-};
-
-const existingFile = (path: string): string => {
-  const stats = statSync(path, { throwIfNoEntry: false });
-  return stats?.isFile() ? path : fail(`"${path}" ${stats ? "is not a file" : "does not exist"}`);
-};
-
-/** Finds an installed package the way `require()` would from the working directory. */
-const packageRoot = (name: string): string => {
-  if (!PACKAGE_NAME.test(name)) fail(`"${name}" is not a valid npm package name`);
-  const searchPaths = createRequire(join(process.cwd(), "noop.js")).resolve.paths(name) ?? [];
-  const root = searchPaths.map((dir) => join(dir, name)).find((dir) => existsSync(join(dir, "package.json")));
-  return root ?? fail(`package "${name}" is not installed (searched from "${process.cwd()}")`);
-};
-
-/** Resolves a {@link WiremockFileSource} to the absolute path of an existing file. */
-export function resolveFile(source: unknown): string {
-  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 !== undefined && module !== undefined) fail('a source may set "package" or "module", not both');
-  if (pkg !== undefined) {
-    const root = packageRoot(text(pkg, "package"));
-    const path = resolve(root, text(file, "file"));
-    return relative(root, path).split(sep)[0] === ".." ? fail(`"${String(file)}" must point to a file inside package "${pkg}"`) : existingFile(path);
-  }
-  if (module === undefined) return existingFile(toPath(file, "file"));
-  const anchor = toPath(module, "module");
-  return existingFile(resolve(statSync(anchor, { throwIfNoEntry: false })?.isDirectory() ? anchor : dirname(anchor), text(file, "file")));
-}
-
-/** Validates a `/`-separated relative container name (no empty, `.` or `..` segments). */
-export const containerName = (name: unknown): string => {
-  const value = text(name, "name");
-  const invalid = value.split("/").some((part) => ["", ".", ".."].includes(part) || /[\\\0]/u.test(part));
-  return invalid ? fail(`name "${value}" must be a relative path using "/" separators, without empty, "." or ".." segments`) : value;
-};
-
-/** Inline mapping JSON: strings verbatim, anything else pretty-printed. */
-export const inlineJson = (json: unknown): string =>
-  typeof json === "string" ? json : (JSON.stringify(json, null, 2) ?? fail('"json" must be a JSON string or an object'));
-
-const parseJson = (json: string): unknown => {
-  try {
-    return JSON.parse(json);
-  } catch (error) {
-    return fail(`invalid JSON (${(error as Error).message})`);
-  }
-};
-
-/** Validates a mapping file – one stub or `{ mappings: [...] }` – and returns its stub ids. */
-export function stubIds(json: string): string[] {
-  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: unknown, 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] : [];
-  });
-}
-
-/** {@link stubIds} of a file in a mounted directory; malformed files are left for WireMock to report. */
-export const stubIdsOf = (path: string): string[] => {
-  try {
-    return path.endsWith(".json") ? stubIds(readFileSync(path, "utf8")) : [];
-  } catch {
-    return [];
-  }
-};
-
-/** Files below `dir`, as `/`-separated relative paths. */
-export const listFiles = (dir: string): string[] =>
-  readdirSync(dir, { recursive: true, withFileTypes: true })
-    .filter((entry) => !entry.isDirectory())
-    .map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join("/"));