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()andfindRequests() - 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);
});
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:
- WireMock Official Documentation - Learn about WireMock’s powerful stubbing and matching capabilities
- Testcontainers for Node.js - Understand the underlying container framework
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 ConsultationCreated with precision by Hella Labs - where quality meets innovation.