Mocks and stubs are two common methods for simulating APIs during testing, but they serve distinct purposes. Understanding the difference helps you write faster, more reliable tests.
Overview
What is an API Mock?
An API mock simulates the behavior of a real API, including dynamic responses, validations, and error handling. It’s useful when the actual service is unavailable or still in development.
What is an API Stub?
An API stub is a minimal version of an API that returns hardcoded responses. It’s best suited for isolating units of code without worrying about the API’s full behavior.
API Mock vs Stub: Quick Comparison
| Aspect | Mock | Stub |
|---|---|---|
| Purpose | Simulates full API behavior | Returns fixed responses |
| Complexity | More dynamic and configurable | Simple and static |
| Best For | Integration or system-level testing | Unit testing or isolated components |
| Validates Behavior | Can check how the API is called | Usually doesn’t perform validations |
| Failure Simulation | Can simulate delays, timeouts, and error codes | Limited or no support for failures |
This article explains how API mocks and stubs work, when to use each in your testing workflow, and how to choose the right one for unit, integration, or end-to-end tests.
What is API Mocking?
API mocking is the practice of simulating an API’s behavior using a controlled, test-friendly environment. It replicates the responses, logic, and edge cases of a real API without requiring the actual backend to be available.
Developers and testers use mocks to test how their systems interact with APIs under different conditions. This makes it easier to build and verify applications even when external services are unstable, unavailable, or still under development.
Benefits of API Mocking
Mocking helps teams improve speed, stability, and test coverage while reducing dependencies on backend services.
- Independent frontend testing: Teams can build and test frontend features without needing the actual API to be functional or stable. This allows UI development to begin even if backend contracts are still evolving.
- Controlled test environments: Mocks eliminate unpredictable factors, such as server outages, rate limits, or changing data. This ensures test results are consistent across multiple runs and easier to debug.
- Comprehensive failure coverage: Testers can simulate API failures, such as 500 errors, unauthorized access, or invalid payloads. This ensures the application handles negative scenarios gracefully.
- Faster integration feedback: Mocked APIs respond instantly, reducing delays in test execution. Developers get quicker feedback on integration issues without waiting for remote services.
- Complete control over data: You can configure responses with specific status codes, payloads, or conditions. This allows testing for rare edge cases that are difficult to reproduce using live data.
- Zero dependency on third parties: External APIs may be slow, unstable, or paid. Mocking removes the need to rely on those services during development or automated testing.
What is API Stubbing?
API stubbing is the technique of creating minimal, fixed-response versions of APIs to isolate and test specific components. It returns hardcoded responses based on predefined request patterns and is typically used in unit or component tests where the goal is to remove external dependencies and focus on internal logic.
Stubs are simple to implement and maintain. They are often defined within the test code itself using test frameworks or libraries. Because they return consistent outputs, they help verify that the component under test behaves correctly when it receives known inputs from an external API.
Benefits of API Stubbing
Stubbing gives developers full control over the inputs and outputs of external dependencies while keeping the test setup lightweight. Here are some key benefits of API stubbing.
- Isolated unit testing: Stubs allow you to test individual units of code without relying on external services. This ensures that failures are caused by the code under test and not by outside systems.
- Faster test execution: Stubs are lightweight and run locally. This makes test suites faster and more suitable for frequent or continuous runs in CI pipelines.
- Simplified test setup: Setting up a stub requires minimal configuration. Testers can define input-output behavior directly in the test file without managing separate services or tools.
- Deterministic test results: Stubs always return the same response for the same input. This removes variability and helps ensure that tests are consistent and repeatable.
- Quick validation of logic: With known inputs and outputs, testers can focus on verifying how the system processes API responses instead of worrying about how the API itself behaves.
- Reduced test flakiness: Since stubs do not depend on network calls or external state, they eliminate common causes of flaky or intermittent failures.
Mock vs Stub: What’s the Difference?
While mocks and stubs both act as stand-ins for real APIs, they solve very different problems in a testing pipeline. This table highlights the technical and practical differences to help you decide which one fits your test scenario, project phase, and complexity level.
| Aspect | Stub | Mock |
|---|---|---|
| Primary Use | Isolates code from external dependencies in unit tests or basic tests | Simulates full API behavior for integration testing, contract testing, or end-to-end testing |
| Response Type | Always fixed based on a static request signature | Dynamic responses based on input, sequence, or simulated state |
| Request Awareness | Matches on path and method; usually ignores body or headers | Matches on full request, including method, headers, query, and body |
| Logic / Behavior | Stateless and static; no internal logic | Supports logic, sequencing, error injection, and conditional flows |
| Setup Complexity | Minimal, quick to implement | Moderate to high, depending on the behavior modeled |
| Test Verification | Only checks if a response is returned | Tracks call count, order, timing, and can enforce contract rules |
| Adaptability to API Changes | Requires manual updates for each change | Easier to update or extend for new behaviors or flows |
| Best Fit | Unit tests, health checks, component isolation | Integration, workflow, edge case, and contract testing |
| Failure Simulation | Rarely supported | Fully configurable: timeouts, errors, malformed data, etc. |
| Stateful Behavior | Not supported | Supported: can simulate context, sequences, and state transitions |
| Protocol Support | REST and limited GraphQL or custom | REST, GraphQL, WebSocket, TCP, and more |
| Tooling Support | Built into most test frameworks and libraries | Requires external mocking tools or platforms |
| Maintenance Overhead | Low unless API changes frequently or many stubs exist | Higher for evolving APIs or mocks with complex behavior |
Mock vs Stub: When to Use Each
Stubs and mocks both replace real APIs during testing, but they serve different goals. Choosing the right one depends on the depth of behavior you need and the stage of development you’re in.
Use Mocks when:
- You need varied behavior: Different inputs, states, or calls must produce different responses in the test.
- You want to verify API interaction: The test should track whether the API was called, how often, and with what data.
- You’re simulating full workflows: The system expects the API to behave realistically, including delays, failures, or dynamic outputs.
Use Stubs when:
- You only need a response: The test just needs something to come back from the API, without caring about its content or structure.
- You want isolated unit tests: The goal is to test logic in a small, self-contained module without external dependencies.
- You don’t need API realism: The actual data shape, status codes, or business rules are not important for the test.
Tools for API Mocking and Stubbing
Choose a tool that matches your tech stack, test depth needed, and team workflow. Below are thorough but direct summaries for leading solutions.
1. Requestly by BrowserStack
Requestly is a popular tool for live HTTP(s) request interception and modification, available as both a browser extension and a desktop app. It lets testers simulate incomplete or changing APIs by adjusting requests or injecting custom responses without any backend changes.
Key Features of Requestly
- Modify Response: Instantly customize API responses with your own data and status codes.
- Override GraphQL API: Intercept GraphQL POST requests and customize query results, enabling response overrides for specific operations like REST APIs.
- Redirect Requests: Change endpoints to local, stage, or prod without code edits.
- Session Capture: Record, save, and replay complex testing flows for teammates.
- Modify HTTP Headers: Alter request/response headers to simulate different browser or network scenarios.
Why Use Requestly?
- No-code mock setup: You can define mock responses using a GUI, without writing backend code or setting up servers.
- Real-time request interception: Requestly can intercept outgoing requests in real time and apply stubs or mocks on the fly.
- Supports both static and dynamic mocks: Whether you want a simple stub that always returns the same response or a dynamic mock that changes based on headers or query params, Requestly supports both.
- Failure and edge simulation: You can simulate error codes, delays, or malformed responses to test how your app behaves under unreliable network or server conditions.
- Rule versioning and sharing: Teams can create, version, and share mock rules, making test environments reproducible and collaboration smoother between QA and development.
Requestly Pricing:
- Free: $0/month
- Lite: $8/month
- Basic: $15/member/month
- Professional: $23/member/month, adds unlimited rules, mocks, and team features
2. WireMock
WireMock is a widely used open-source mock server, especially in Java-heavy teams and CI pipelines. You can run it as a server, library, or Docker image. WireMock allows you to stub or mock HTTP endpoints with rich matching rules and simulate not just basic replies but also latency and error conditions.
Pros and Cons of Wiremock:
| Pros | Cons |
|---|---|
| Fine-grained matching and verification | Can be slow as a process in heavy pipelines |
| Traffic Capture: Record and replay live calls | Maintenance is needed as API schemas change |
| Open Source, broad library support | GUI is limited—most features are code or config |
| Supports advanced fault scenarios | The setup is complex for multi-protocol or chained mocks |
3. MockServer
MockServer provides dynamic, programmable mocks for HTTP or WebSocket APIs. It works well for teams needing stateful, conditional responses or advanced request matching. Can run as a process, Docker container, or part of your automated tests.
Pros and Cons of MockServer
| Pros | Cons |
|---|---|
| Supports stateful and complex workflows | Steeper learning curve for new users |
| Protocol Support: HTTP(s) and WebSocket | Limited GUI, mostly config/code-based setup |
| Integrates with Docker, cloud, and CI tools | Needs regular updates for dependency management |
4. Hoverfly
Hoverfly is an open-source API virtualization tool preferred for its lightweight, easy-to-use approach. It can intercept and replay API calls, supporting several simulation modes like recording, simulating, or modifying traffic. It plugs smoothly into CI tools and Docker containers.
Pros and Cons of Hoverfly:
| Pros | Cons |
|---|---|
| Quick to set up in CI/CD and Docker flows | May lack features for very complex test scenarios |
| Recording and Replay speeds up large test coverage | No commercial-grade support available |
| Permits custom rules using Java DSL | Only supports HTTP and HTTPS protocols |
5. Mountebank
Mountebank offers multi-protocol API mocking, not just HTTP but also TCP, SMTP, and more. Useful for test environments that need to simulate services at different layers, from web APIs to message queues. Runs as a standalone process or Docker image and supports advanced predicate logic for matching requests.
Pros and Cons of Mountebank:
| Pros | Cons |
|---|---|
| Multi-protocol: HTTP(S), TCP, SMTP support | Limited real-time analytics or monitoring |
| Custom imposters for advanced matching | GUI and ecosystem are more limited than other tools |
| Community-driven and scriptable | No support for the WebSocket protocol |
Common Problems When Using Mocks and Stubs
While mocks and stubs can greatly improve test coverage and speed, misusing them can lead to fragile tests, missed bugs, or misleading results. Here are the most common issues testers and developers run into:
- Over-mocking or over-stubbing: Relying too heavily on test doubles can result in tests that no longer reflect real behavior. Critical bugs may go unnoticed because the test environment is too detached from production conditions.
- Stale or outdated responses: Hardcoded stubs and mocks may become outdated as the real API evolves. If they aren’t updated regularly, tests may pass even though the app would break against the actual API.
- Lack of contract validation: Mocks that don’t validate request structure or data types can miss issues related to incorrect payloads, missing headers, or breaking schema changes.
- Missing failure scenarios: Many teams only mock successful cases. This leaves gaps in test coverage for timeouts, 4xx/5xx errors, or malformed responses that could affect real users.
- Unclear test intent: When mocks and stubs are too complex or generic, it becomes hard to tell what the test is actually verifying. This reduces readability and trust in test outcomes.
- Tight coupling to test doubles: If your application logic is designed around mock behaviors rather than actual API design, changes to the real API may break production but not your tests.
Best Practices for API Mocking and Stubbing
Mocks and stubs are powerful tools, but misusing them can lead to brittle tests or gaps in coverage. Following these best practices ensures your test doubles support long-term quality and stay aligned with real API behavior.
- Define clear goals for each test: Decide whether you are testing business logic (use stubs) or API interactions (use mocks). Mixing both in the same test often leads to confusion and overlapping concerns.
- Mock or stub only what you control: Avoid mocking third-party services you do not own unless absolutely necessary. It is better to use a sandbox or test environment when dealing with external APIs.
- Validate contract alignment: Regularly check that mocks and stubs reflect the actual API contract. Tools like Requestly schemas can help keep your test doubles in sync with the real service.
- Cover both success and failure paths: Don’t just test 200 OK. Simulate timeouts, 500 errors, and invalid data to check how resilient your application is under adverse conditions.
- Use dynamic mocks sparingly: Complex mocks with internal logic or state can be powerful, but they are harder to maintain. Use them only when simple static responses are not enough.
- Keep test doubles visible and versioned: Store mocks and stubs alongside your test code or config, under version control. This makes it easier to track changes when APIs evolve.
- Name your mocks and rules descriptively: Use clear identifiers like GET_userList_success.json or POST_login_unauthorized.js to make it obvious what each mock or stub is doing.
- Avoid over-mocking: Relying too much on mocks can disconnect tests from real user flows. Use real APIs in staging or contract tests to validate integration before production.
Conclusion
API mocking helps simulate real-world behavior, handle dynamic responses, and test how systems interact with external services under different conditions. On the other hand, API stubbing allows you to isolate components, return fixed outputs, and keep tests fast and focused.
Requestly supports both API mocking and stubbing and lets testers intercept, modify, or simulate API calls directly in real environments. It’s especially useful for testing edge cases, failure scenarios, and workflows without depending on backend readiness.
Featured Article
