CI-First Network Interception Architecture #
Isolate network traffic at the browser or Node.js layer before it reaches the actual backend. Intercepting HTTP requests in CI prevents transient 5xx errors, rate limits, and third-party outages from corrupting test results. Implementing Playwright Route Mocking Strategies enables granular control over request matching, response delays, and fallback routing. Route interception should be configured at the test runner level, not hardcoded in individual specs, to maintain DRY principles and simplify CI cache warming.
Service Worker vs. Proxy Interception #
Service workers operate at the browser level, intercepting fetch and XHR calls transparently. They excel at unit and component tests but require explicit lifecycle management in headless environments. Proxy-based interception runs at the Node.js or network layer, offering broader protocol support and easier CI integration. Choose proxies for cross-domain requests and service workers for isolated frontend validation.
Request Matching & Regex Fallbacks #
Strict URL matching prevents accidental interception of unrelated endpoints. Use regex fallbacks for dynamic query parameters or UUID-based resource paths. Always anchor patterns to specific HTTP methods to avoid false positives. Overly broad matchers degrade performance and obscure routing logic.
CI Cache & Fixture Preloading #
Network mocks should be cached alongside test artifacts to eliminate cold-start latency. Preload fixture directories into CI runner volumes before test execution begins. This reduces I/O bottlenecks and ensures deterministic response times across parallel workers.
Deterministic Mock Data & Environment Parity #
Flaky tests often stem from non-deterministic payloads that drift between local and CI environments. Synchronizing fixture generation with backend schema versions guarantees Environment Parity & Mock Data Management across pipelines. Use factory functions with explicit seed values to generate repeatable JSON responses. Store versioned fixtures in a shared artifact repository and inject them via environment variables during CI execution to eliminate data drift.
Factory-Based Fixture Generation #
Replace static JSON files with programmatic factories that accept seed parameters. @faker-js/faker accepts a seed via faker.seed(number) to produce identical outputs across runs. This approach supports edge-case simulation without manual data curation.
Versioned JSON Artifact Storage #
Treat mock data as version-controlled dependencies. Tag fixtures alongside backend releases and store them in immutable artifact registries. Pinning fixture versions to specific API contracts prevents unexpected test failures during dependency upgrades.
CI Pipeline Injection Patterns #
Inject fixture paths via environment variables rather than hardcoding relative paths. Use CI matrix strategies to load environment-specific payloads dynamically. This decouples test logic from infrastructure topology and simplifies multi-environment validation.
Contract Validation & Schema Enforcement #
Mocking without validation creates false confidence. Integrate OpenAPI/GraphQL schema checks into your test lifecycle to catch breaking backend changes early. Implementing API Contract Validation in E2E Tests ensures mocked responses strictly adhere to production type definitions. Use runtime validators (e.g., Zod, Ajv) to assert response shapes during setup, preventing silent test passes when backend contracts evolve.
OpenAPI/GraphQL Schema Sync #
Automate schema downloads during CI initialization. Generate TypeScript types directly from the latest spec to enforce compile-time safety. Reject test runs if schema fetch fails, forcing explicit contract updates.
Runtime Type Assertion #
Apply validators at the mock boundary before responses reach the application layer. Fail fast if payload structures deviate from expected schemas. This catches serialization bugs and undocumented API changes before deployment.
Contract Drift Alerting #
Log schema mismatches to telemetry dashboards for immediate triage. Configure CI gates to block merges when drift exceeds defined thresholds. Maintain a historical record of contract violations to identify unstable backend services.
Real-Time & Stateful Protocol Simulation #
Modern applications rely heavily on persistent connections that traditional HTTP mocks cannot replicate. Simulating bidirectional communication requires intercepting upgrade requests and managing connection lifecycles. Mocking WebSockets involves capturing socket handshakes, injecting deterministic message streams, and handling reconnection logic. This eliminates race conditions caused by unpredictable server push timing in CI environments.
Socket Interception & Handshake Control #
Intercept WebSocket constructors at the browser or Node layer. Override the underlying transport to route traffic through a controlled mock server. Validate handshake headers and subprotocols to ensure compliance with production configurations.
Deterministic Event Streaming #
Replace asynchronous server pushes with scheduled message queues. Emit payloads at fixed intervals to simulate real-time updates without network jitter. This stabilizes UI rendering tests and prevents timing-dependent assertion failures.
Reconnection & Timeout Simulation #
Inject controlled disconnects to verify client-side recovery logic. Mock exponential backoff patterns and connection state transitions. Validate that the application gracefully handles degraded network conditions without crashing.
Recorded Traffic & Shared Handler Layers #
Hand-written fixtures and live calls are not the only two options, and treating them as such is why many suites end up with either brittle mocks or a dependency on someone else’s uptime. Two intermediate approaches carry most of the weight in mature suites.
Recording and replaying real traffic captures an actual exchange once and serves it from disk forever after. It buys fidelity that no hand-written fixture matches — including the fields nobody remembered to mock — and it introduces exactly one new failure mode: the recording ages silently while the API moves on, so the suite ends up testing a contract that no longer exists. That is manageable with a scheduled re-record and a structural diff, which is why Record & Replay HTTP Traffic treats the detection loop as part of the technique rather than an optional extra. The matching strategy is the decision that determines whether replay is deterministic: method and path alone collapse paginated and filtered variants onto whichever response was recorded first.
A shared handler layer attacks a different problem — the same API being described three times, once for the unit suite, once for Cypress and once for Playwright, with the three descriptions drifting apart until a component passes its unit test and breaks in the browser. Writing the handlers once and serving them through a Node interceptor or a service worker keeps every level honest against the same contract. The setting that turns this from a convenience into a guarantee is failing on unhandled requests: without it, any endpoint nobody wrote a handler for quietly reaches the real origin. MSW in JavaScript Test Suites covers the runtimes, the precedence rules and the strictness policy.
// Fail loudly on anything unmocked — the line that makes "fully mocked" a fact.
// Trade-off: strict mode fails on genuinely irrelevant traffic such as source
// maps; allowlist those explicitly rather than relaxing the policy.
server.listen({ onUnhandledRequest: 'error' });The three approaches are complements rather than competitors. Recordings supply realistic bodies, shared handlers supply the routing and the contract, and per-spec interception supplies the awkward cases — an aborted request, a hang, a sequence of responses — that belong visibly next to the assertion that depends on them.
Production Configuration Examples #
MSW Node/Worker Setup with CI Environment Detection #
// msw/setup.ts
import { setupWorker } from 'msw/browser';
import { setupServer } from 'msw/node';
import { handlers } from './handlers';
// Trade-off: Browser workers intercept real network calls in dev,
// while Node servers provide deterministic CI execution without browser overhead.
// setupWorker is browser-only; setupServer is Node-only.
export const startMocks = async () => {
if (process.env.CI) {
const server = setupServer(...handlers);
server.listen({ onUnhandledRequest: 'bypass' });
} else {
const worker = setupWorker(...handlers);
await worker.start({ onUnhandledRequest: 'warn' });
}
};Playwright Route Handler with Regex Matching & Latency Injection #
// tests/fixtures/api-mocks.ts
import { test as base } from '@playwright/test';
export const test = base.extend({
page: async ({ page }, use) => {
// Trade-off: Regex matching handles dynamic IDs but increases CPU overhead.
// Latency injection prevents race conditions but extends CI runtime.
await page.route(/\/api\/v\d+\/users\/.*/, async (route) => {
await route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({ id: 'test-user', role: 'admin' }),
// Note: route.fulfill() does not accept a `delay` option in Playwright.
// To simulate latency, use a setTimeout before calling fulfill:
});
});
await use(page);
}
});Cypress Intercept with Fixture Fallback & Schema Validation #
// cypress/support/commands.ts
import { z } from 'zod';
const UserSchema = z.object({ id: z.string(), role: z.enum(['admin', 'user']) });
Cypress.Commands.add('mockUserEndpoint', () => {
// Trade-off: Schema validation catches drift but requires strict fixture maintenance.
cy.intercept('GET', '/api/users', (req) => {
req.reply((res) => {
const payload = res.body;
const validation = UserSchema.safeParse(payload);
if (!validation.success) {
throw new Error(`Contract violation: ${JSON.stringify(validation.error.issues)}`);
}
res.send(payload);
});
});
});GitHub Actions Step for Pre-warming Mock Artifacts #
# .github/workflows/ci.yml
- name: Pre-warm Mock Artifacts
run: |
# Trade-off: Pre-downloading fixtures eliminates cold-start latency
# but increases runner storage requirements and pipeline complexity.
mkdir -p ./test/fixtures
curl -sL "${{ secrets.FIXTURE_REGISTRY_URL }}/v${{ env.API_VERSION }}.tar.gz" \
| tar -xz -C ./test/fixtures
echo "MOCK_CACHE_WARMED=true" >> "$GITHUB_ENV"Deciding what to mock #
Mocking is a trade of realism for determinism, and the trade is worth making in different amounts for different dependencies. Four questions settle most cases.
Does the test’s assertion depend on this dependency’s behaviour? If the test verifies that a table renders twenty-five rows, the API is a data source and should be mocked. If it verifies that the checkout flow reaches the payment provider, the provider is the subject and mocking it removes the coverage.
Do you control the dependency? An internal service run by a neighbouring team can be exercised in a staging environment and can participate in contract verification. A third-party vendor can do neither, which makes mocking the default and a small scheduled live check the only realistic verification.
How variable is its latency? A dependency whose 99th-percentile response time is several seconds turns every test that touches it into a timing gamble. Mocking removes the variance; where the latency itself matters, model it deliberately with a runner-level throttle rather than by waiting out the real thing.
What does a wrong answer cost? A mocked dependency that drifts from reality produces green tests and a broken product, which is worse than a flaky test. The higher that cost, the more the mock needs an external reference — a schema, a recorded sample, a contract the provider verifies — rather than someone’s memory of the payload shape.
A useful default falls out of those questions: mock everything the test does not assert on, exercise the real thing in exactly one place per integration, and put a drift detector between the two so the mocked majority cannot quietly diverge.
The failure mode mocking introduces #
Every technique on this page trades one risk for another, and it is worth stating the new one plainly. An unmocked suite is unreliable in an obvious way — it fails when a vendor is down, and everyone can see why. A mocked suite is unreliable in a silent way: it keeps passing after the API it imitates has changed, and nothing in the test run notices.
That asymmetry is why the mocking topics here spend as much attention on detection as on interception. Validating fixtures against a published schema on every build catches structural drift for free. A scheduled comparison against a live environment catches undocumented change. A handful of live assertions on the semantics you depend on — units, enum meanings, identifier formats — catches the changes that keep the same shape. None of the three is expensive; skipping all three is what turns a fast, deterministic suite into a confidently wrong one.
The practical test of whether a suite has this right is a question rather than a metric: if the API changed a field name last month, how would you know? A team that can answer with a mechanism has mocked well. A team that answers “the tests would fail” has usually not checked whether that is true.
Mocks as shared state #
A mock layer is state, and state that outlives a test is the isolation problem in a different costume. Three shapes account for nearly all of it.
A handler registered inside a test persists until something resets it, so a scenario set up for one test answers the next one’s requests. The remedy is a reset in shared setup rather than in each file, which is the same argument made for spy restoration: configuration protects the spec somebody writes next quarter, while a per-file hook protects only the file that remembered it.
A counter or queue inside a mock factory is module-scope state by construction. It is the natural way to express “fail twice, then succeed”, and it leaks into the following test unless the counter is declared inside the test body or the sequence is expressed with single-use handlers.
An accumulating mock server — one that records requests, or holds an in-memory store so tests can exercise create-read-update flows — is the most tempting and the most order-dependent. Where such a store is genuinely useful, its lifetime should be a single test, created by a factory and installed per test, so it cannot outlive the scenario that made it.
The diagnostic is the same one used everywhere else in this catalogue: if a test passes alone and fails in the suite, something it depends on was left behind, and the mock layer is a strong first suspect when the network is involved. Test Isolation & State Leakage covers the bisection that names the writer.
Common Pitfalls #
- Over-mocking internal service calls, masking integration failures
- Hardcoding absolute URLs that break across staging/CI environments
- Ignoring network latency simulation, leading to race conditions in production
- Failing to version mock fixtures alongside backend schema changes
- Using global interceptors without cleanup, causing cross-test pollution
Where interception happens, and what each layer cannot see #
Three interception layers are in common use, and a great deal of confusion comes from expecting one of them to catch traffic that structurally belongs to another.
Browser-level route interception — page.route in Playwright, cy.intercept in Cypress — replaces the network layer of the page. It sees requests initiated by page scripts and nothing else, which makes it the right tool for anything the application fetches at runtime and useless for requests made by a server-rendering process or by test setup code running in Node.
A service worker sits inside the page as well, but as a real worker rather than as automation machinery, so it behaves closer to production and brings a registration lifecycle with it. The practical consequence is an ordering requirement: the worker must be active before the application’s first request, or that request escapes. An unawaited start is the single most common cause of “the mock did not apply” flakiness in browser suites.
Node-level interception replaces the HTTP machinery of the test process, so it covers server-side fetches, provider SDKs and anything else going through the runtime’s request stack. It cannot see browser traffic at all. Its distinctive failure is silent non-application: when a client uses a stack the interceptor does not patch, the request quietly reaches the real host and the test passes for the wrong reason — which is why disabling outbound connections entirely, so an unmocked call fails loudly, matters more than any individual mock.
A full-stack test frequently needs two of these at once, and assuming that mocking one covers the other is a blind spot worth checking explicitly: make an unmocked request on purpose and confirm it fails.
Frequently Asked Questions #
Should I mock all network requests in CI? No. Mock external dependencies and unstable endpoints, but keep critical integration paths live to catch real contract drift. Use a hybrid approach with fallback interceptors.
How does network mocking impact CI build times? Properly cached mocks reduce build times by eliminating network round-trips and retry logic. The exact reduction depends on the number of external calls your suite makes; suites with heavy third-party traffic commonly see 30–60% faster runs.
How do I prevent mock data from becoming stale? Automate fixture generation from OpenAPI/GraphQL schemas in your CI pipeline. Run contract validation on every PR to flag drift before merging.
Fixture data as a distribution, not a sample #
Most fixtures are a single observation: someone copied a response from a network panel, trimmed it, and committed it. That captures one draw from a distribution the application has to handle in full — one status value, non-null everywhere, arrays of length one — and the branches it never exercises are exactly where production breaks.
Two axes drift independently. The schema moves as the product grows: fields appear, optionality loosens, enums gain values, nested structures get flattened. The population moves too, invisibly to any schema check: the share of records with a null description rises, arrays that were always short start containing hundreds of items, a status that was theoretical becomes common. A fixture can satisfy the schema perfectly and still be unrepresentative of what users have.
The fix is to generate rather than to copy. A fixture generated from the schema is structurally correct by construction and fails loudly when the schema changes; a factory with per-test overrides lets each test state only the two fields its assertion depends on, which also makes the tests easier to read. On top of that base, keep one deliberate fixture per risky field — a null-heavy variant, one per rendering-relevant enum value, a large-collection variant sized from what the real data actually contains. Keeping Fixtures in Sync with Staging Data Shapes covers profiling the real population and turning that profile into coverage.
One rule has no exceptions: fixtures are never sampled from production. A payload taken from a live system carries personal data into the repository, onto every developer’s machine and into CI logs, and no test-reliability benefit offsets that. Where production-like variety is genuinely needed, generate it from the profile — the distribution is the useful part, and it can be reproduced without reproducing anyone’s data.
Reliability Metrics #
- Flakiness Rate Reduction: Target <0.5% false-negative rate per 1000 runs
- CI Execution Time Delta: Measure % reduction in network-bound test duration
- Mock Cache Hit Rate: Track fixture reuse vs. regeneration in CI runners
- Contract Drift Detection: Count of schema mismatches caught pre-merge
- Interception Coverage: % of external dependencies successfully isolated in test suite
Modelling network behaviour, not just responses #
There is a category that mocking libraries describe poorly and that causes a disproportionate share of production incidents: how the network behaves rather than what it returns.
“Offline” is really four distinct code paths. A refused connection rejects immediately and runs the error branch fast. A black-holed route leaves the request pending until something times it out — the branch that produces an eternal spinner, and the one an application without a client-side deadline fails completely. A connection dropped mid-response delivers a truncated body that fails to parse. A captive portal or proxy returns a perfectly valid HTTP response containing the wrong content entirely, which passes a status check and fails everything downstream.
Most suites test only the first. Route-level interception makes the other three cheap: abort with a specific error code, take a route and never fulfil it, fulfil with a truncated body, fulfil with HTML and a 200. Each is a few lines, and each exercises a branch that otherwise runs for the first time during an incident. The hang test in particular pays for itself, because it either proves a client deadline exists or finds the spinner that never ends.
Recovery deserves equal attention and receives almost none. Failing the first attempt and letting the retry succeed — with a counter in the handler, declared inside the test so it cannot leak — verifies that the interface returns to a working state without a reload, which is the behaviour users actually notice. Testing Offline and Connection Loss States covers all five scenarios and the contract each should assert.