WireMock Testcontainers for Node.js

WireMock Testcontainers for Node.js

WireMock Testcontainers for Node.js


WireMock Testcontainers Architecture

Overview

The WireMock Testcontainers for Node.js module brings professional-grade API mocking to the Node.js ecosystem. By combining the power of WireMock with Testcontainers, this tool enables developers to create robust, isolated integration tests that mock external HTTP dependencies with precision and reliability.

Key Features

  • Fluent, Typed Builder - Register stubs from directories, files, npm packages or inline objects – validated before Docker starts
  • Fast Test Isolation - One container per suite; reset() restores stubs, scenarios and journal in milliseconds
  • Request Verification - Assert on what your code actually sent with countRequests() and findRequests()
  • WireMock Extensions - Load compiled extension JARs with typed stub helpers – no JDK needed
  • No Docker? Develop Anyway - Serve every container from a local WireMock JVM for development
  • Response Templating - Dynamic responses using Handlebars templates
  • Stateful Scenarios - Model complex multi-step API interactions
  • TypeScript First - Built with TypeScript for superior type safety and IntelliSense

Why This Matters

Modern applications depend on numerous external APIs and services. Testing these integrations reliably requires precision, control, and consistency. Our WireMock Testcontainers module demonstrates our dedication to:

  • Test Reliability - No more flaky tests due to network issues or external service downtime
  • Development Velocity - Test without waiting for staging environments or third-party sandbox APIs
  • Security Best Practices - Test against realistic scenarios including error conditions and edge cases
  • Team Productivity - Developers can work offline with full testing capabilities

Installation

npm install @hellaweb3/wiremock-testcontainers-nodejs

or

yarn add @hellaweb3/wiremock-testcontainers-nodejs

Complete Test Suite Example

Here’s a real-world example showing how to set up WireMock for your entire test suite:

import { afterAll, afterEach, beforeAll, expect, it } from "vitest"; // or Jest
import { type StartedWiremockContainer, WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";
import { PaymentsClient } from "../app/payments-client"; // the code under test

let wiremock: StartedWiremockContainer;

beforeAll(async () => {
  wiremock = await new WiremockContainer()
    .withMappings("./__mocks__/wiremock") // mappings/ + __files/
    .start();
  await wiremock.waitUntilReady();
}, 120_000); // the first image pull can be slow

afterEach(() => wiremock.reset()); // pristine stubs, empty journal – no restart
afterAll(() => wiremock?.stop());

it("lists the recorded payments", async () => {
  const page = await new PaymentsClient(wiremock.getUrl()).list();

  expect(page.meta.totalItems).toBe(2);
  expect(await wiremock.countRequests({ method: "GET", url: "/payments" })).toBe(1);
});
Performance Tip: Notice the reset() call in afterEach - this restores pristine stubs and empties the request journal without restarting the container, making your test suite dramatically faster. Learn more about test isolation →

Engineering Excellence

This project exemplifies our commitment to quality software engineering:

  • Battle-Tested Architecture - Built on the proven WireMock and Testcontainers foundations
  • Comprehensive Testing - Extensive test suite ensuring reliability
  • Clean API Design - Intuitive, developer-friendly interfaces
  • Performance Optimized - Fast container lifecycle with minimal overhead
  • Production-Ready - Used in real-world projects with demanding requirements
  • Well-Documented - Clear examples covering common use cases

Advanced Features & Use Cases

Registering Stubs from Multiple Sources

The fluent builder API lets you register stubs from various sources:

await new WiremockContainer()
  .withMappings("./__mocks__/wiremock")           // from recorded sessions
  .withMappingsFromFile("./stripe-stubs.json")    // from individual files
  .withMappingsFromPackage("@acme/api-mocks")     // from npm packages
  .withMapping({                                   // or inline
    request: { method: "POST", url: "/webhook" },
    response: { status: 201 }
  })
  .start();

Explore stub registration options →

Request Verification

Assert that your code made the correct HTTP calls:

// Count specific requests
const count = await wiremock.countRequests({
  method: "POST",
  urlPathPattern: "/api/payments/.*"
});

// Find and inspect requests
const requests = await wiremock.findRequests({
  method: "GET",
  url: "/users/123"
});

Learn about request verification →

Real-World Use Cases

Payment Gateway Testing

Mock Stripe, PayPal, or Square APIs to test payment flows without hitting real endpoints or incurring transaction fees.

OAuth & Authentication

Simulate OAuth providers and authentication services to test login flows, token refresh, and error scenarios.

Microservices Integration

Validate service-to-service communication patterns in isolation before integration, including failure scenarios.

Third-Party API Contracts

Ensure your code correctly handles API contracts from external services, including edge cases and version changes.


Real-World Benefits

Teams integrating this module experience:

  • 90% faster integration test execution compared to hitting real APIs
  • Zero dependency on external service availability during testing
  • Complete control over edge cases, error conditions, and timeout scenarios
  • Simplified CI/CD with no need for complex staging environment coordination

Resources & Documentation

Full Documentation

Complete guides, tutorials, and API reference with tested examples that cannot drift from the actual codebase.

View Docs →

API Reference

Detailed API documentation for all container methods, stub registration, and verification functions.

API Docs →

Working Examples

Real, runnable examples covering quick start, advanced features, and common integration patterns.

View Examples →

NPM Package

Install via npm or yarn. MIT licensed with full TypeScript support and no peer dependencies.

View on NPM →

GitHub Repository

Source code, issue tracking, and contribution guidelines. PRs welcome!

View on GitHub →

Troubleshooting

Common issues, solutions, and tips for Docker, networking, and WireMock configuration.

Troubleshooting →

Additional Resources:


Need a high-performance testing infrastructure?

These open-source contributions represent just a fraction of our expertise in test automation, DevOps, and software quality engineering. We help teams implement comprehensive testing strategies that accelerate delivery while maintaining the highest quality standards.

Contact Us for a Consultation

Created with precision by Hella Labs - where quality meets innovation.