Principle:Getgauge Taiko Request Handler Functions

Overview

Request Handler Functions is the technique for dynamically deciding how to handle intercepted HTTP requests using custom callback functions during automated testing with Taiko.

Description

Handler functions provide full programmatic control over intercepted requests. Unlike the simpler blocking, redirecting, or mocking approaches that apply a fixed action to every matching request, a handler function receives the complete request details and can dynamically decide how to process each individual request.

The handler function receives an object containing:

• request — The original request details (URL, method, headers, post data)
• continue — A function to forward the request to the network, optionally with modifications
• respond — A function to return a mock response without network activity

This enables sophisticated testing scenarios:

• Conditional mocking — Mock POST requests but allow GET requests to pass through
• Request inspection — Examine request headers or body content before deciding the action
• Dynamic responses — Generate different mock responses based on request parameters
• Selective modification — Modify only specific request headers while preserving others
• Request logging — Record request details for later assertion while allowing them to proceed
• Stateful interception — Maintain state across multiple requests (e.g., return different data on subsequent calls)

Usage

Handler functions are used when the testing scenario requires logic that cannot be expressed with a simple block, redirect, or mock. The handler is invoked for each matching request, and it must call either continue() or respond() to resolve the intercepted request. Failing to call either will leave the request permanently paused, which may cause the page to hang.

The continue() function accepts an optional override object to modify request properties before forwarding:

• url — Override the request URL
• method — Override the HTTP method
• postData — Override the request body
• headers — Override request headers

The respond() function accepts a mock response object with the same structure as the response mocking action.

Theoretical Basis

The handler function mechanism injects helper functions into the callback context:

intercept(url, handlerFunction) called with function action
        │
        ▼
Interceptor registered with action = handlerFunction
        │
        ▼
Matching request is paused by Fetch.requestPaused
        │
        ▼
handleInterceptor checks action → typeof function
        │
        ▼
Construct handler context object:
  {
    request: event.request,          ← original request details
    continue: (override) => {        ← injected helper
        Fetch.continueRequest(requestId, ...override)
    },
    respond: (mock) => {             ← injected helper
        mockResponse(mock) → Fetch.fulfillRequest(...)
    }
  }
        │
        ▼
handlerFunction(context) is invoked
        │
        ▼
Handler calls context.continue() or context.respond()
        │
        ▼
Request is forwarded or fulfilled based on handler decision

The continue and respond helper functions are created for each intercepted request and are bound to that specific request's ID. This ensures that the handler's action applies to the correct request even in asynchronous scenarios where multiple requests may be intercepted concurrently.

The continue helper wraps Fetch.continueRequest, allowing the handler to forward the request with optional modifications. If called with no arguments, the request proceeds unchanged.

The respond helper wraps the same mockResponse and Fetch.fulfillRequest pipeline used by object-based mocking, providing a consistent mock response format regardless of whether mocking is configured statically or dynamically.

Related Pages

Implemented By

• Implementation:Getgauge_Taiko_Intercept_Handler