Description

wiremock-testcontainers-nodejs is a Typescript nodejs library that spins up
a WireMock
instance with Testcontainers. It provides a
fluent API to configure and start WireMock
containers, including support for loading mappings and files from recorded
Wiremock sessions.

Installation

``bash
pnpm add -D @hellaweb3/wiremock-testcontainers-nodejs testcontainers
`

Usage

$3

Assuming you placed your mappings in test/__mocks__/wiremock,

`typescript
import { WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";

describe("E2E Test", () => {
let container;

beforeAll(async () => {
container = await new WiremockContainer()
.withMappings("./test/__mocks__/wiremock")
.start();
}, 60000);

afterAll(async () => {
await container.stop();
});

it("should interact with WireMock", async () => {
const url = container.rpcUrl;
// Your test logic here
});
});
`

$3

WireMock uses a specific directory structure for mappings and static files. This
library makes it easy to mount these into the container.

Project structure:

`
test/
└── __mocks__/
└── wiremock/
├── mappings/
│ └── my-mapping.json
└── __files/
└── some-data.json
`

`typescript
import { WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";

const container = await new WiremockContainer()
.withMappings("./test/__mocks__/wiremock")
.start();
`

API

$3

- 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.
- start(): Starts the container and returns a StartedWiremockContainer.

$3

- rpcUrl: Returns the base URL of the running WireMock instance (e.g.,
http://localhost:32768).
- stop(): Stops the container (inherited from Testcontainers).

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., 5s in Jest). 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.

Maintainers

Maintained by Hella Labs.

License

MIT