Heuristic:Getgauge Taiko Network Interception Gotchas
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Debugging |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Edge cases and pitfalls when using Taiko's network request interception APIs including interceptor ordering, CORS preflight limitations, and silent failure handling.
Description
Taiko's `intercept()` API allows blocking, redirecting, mocking, or modifying HTTP requests via the CDP Fetch domain. However, several non-obvious behaviors can cause unexpected test results: multiple interceptors for the same URL follow last-wins semantics, CORS OPTIONS preflight requests cannot be intercepted, intercept failures are silently caught (only warned), and response header casing is normalized.
Usage
Apply this heuristic when debugging network interception issues: mocked responses not applying, wrong interceptor firing, CORS errors in tests, or intercept callbacks not being called. Also useful when designing a test strategy that relies heavily on network mocking.
The Insight (Rule of Thumb)
- Last Interceptor Wins: When multiple interceptors match the same URL, the last registered interceptor is applied. Earlier interceptors are ignored with a console warning.
- CORS Limitation: Browser-sent OPTIONS preflight requests cannot be intercepted. Workaround: use `--disable-web-security` flag (security risk, only for testing).
- Silent Failures: If an intercept callback throws an error, it is caught silently and a warning is printed. The request continues normally. Tests will not fail on broken interceptors.
- Response Mock Details:
- Body is auto-stringified if passed as an object
- Content-Length is auto-calculated if not provided
- Response headers are converted to lowercase
- Status defaults to 200
Reasoning
The last-wins behavior is intentional: it allows test setup code to register a default interceptor and individual tests to override it. The `matches.pop()` call in the filtering function always returns the last match.
Silent failure handling prevents broken interceptors from crashing test suites. This is a deliberate trade-off: reliability of the test harness over strict error reporting. However, it means incorrect mock setups may go unnoticed, causing subtle test failures.
The CORS limitation exists because OPTIONS requests are generated by the browser networking stack before CDP has a chance to intercept them.
Code Evidence
Last-wins interceptor ordering from `lib/handlers/fetchHandler.js:57-71`:
const filterInterceptorsAndWarnIfNeeded = (requestUrl) => {
const matches = interceptors.filter((interceptor) =>
getMatchingInterceptor(interceptor, requestUrl),
);
const matchesLen = matches.length;
if (matchesLen > 1) {
const matchesURL = matches.map((e) => `"${e.requestUrl}"`).join(",");
console.warn(
`WARNING: More than one intercept [${matchesURL}] found for request "${requestUrl}".
Applying: intercept("${matches[matchesLen - 1].requestUrl}", "${matches[matchesLen - 1].action}")`,
);
}
return matches.pop();
};
Silent failure handling from `lib/handlers/fetchHandler.js:73-75`:
const warnInterceptFailed = (p) => {
console.warn(`WARNING: Could not intercept request ${p.request.url}`);
};