Implementation:SeleniumHQ Selenium NetworkInterceptor Constructor

Knowledge Sources	Selenium
Domains	Browser_Automation, DevTools, Network
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for intercepting browser HTTP traffic using the CDP Fetch domain provided by the Selenium Java library.

Description

NetworkInterceptor wraps the CDP Fetch domain to provide request/response interception. It accepts three types of handlers:

• Filter: a composable middleware that receives a next handler for delegation. The filter can modify both the request (before calling next.execute(req)) and the response (after the call returns).
• HttpHandler: a simple request-to-response function. Internally wrapped as (Filter) next -> handler, meaning the next handler is completely ignored and only the provided handler executes.
• Routable: a pattern-matching handler. Matching requests are processed by the routable; non-matching requests pass through to next.execute(req).

The constructor verifies the driver implements HasDevTools, obtains the DevTools instance, creates a CDP session if needed (using createSessionIfThereIsNotOne() with the current window handle), then enables traffic interception via getDomains().network().interceptTrafficWith(filter).

The special constant PROCEED_WITH_REQUEST is an HttpResponse with the header "Selenium-Interceptor: Continue", which signals that a request should proceed to the actual server unmodified.

The interceptor implements AutoCloseable. On close(), it calls getDomains().network().resetNetworkFilter() to disable interception and restore normal network behavior.

Usage

Construct a NetworkInterceptor with the driver and a filter/handler/routable. The interception remains active until close() is called. Use try-with-resources for automatic cleanup.

Code Reference

Source Location

• Repository: Selenium
• File: java/src/org/openqa/selenium/devtools/NetworkInterceptor.java (L57-124)

Signature

public class NetworkInterceptor implements AutoCloseable {
    public static final HttpResponse PROCEED_WITH_REQUEST;

    public NetworkInterceptor(WebDriver driver, HttpHandler handler);
    public NetworkInterceptor(WebDriver driver, Routable routable);
    public NetworkInterceptor(WebDriver driver, Filter filter);

    @Override
    public void close();
}

Import

import org.openqa.selenium.devtools.NetworkInterceptor;
import org.openqa.selenium.remote.http.Filter;
import org.openqa.selenium.remote.http.HttpHandler;
import org.openqa.selenium.remote.http.HttpResponse;
import org.openqa.selenium.remote.http.Routable;
import org.openqa.selenium.remote.http.Route;
import org.openqa.selenium.remote.http.Contents;

I/O Contract

Inputs

Name	Type	Required	Description
driver	WebDriver	Yes	Must implement HasDevTools (ChromeDriver, EdgeDriver)
handler	HttpHandler	Yes (or filter/routable)	Simple request-to-response function (next handler ignored)
routable	Routable	Yes (or handler/filter)	Pattern-matching handler; non-matching requests pass through
filter	Filter	Yes (or handler/routable)	Composable HTTP filter middleware with access to next handler

Outputs

Name	Type	Description
interceptor	NetworkInterceptor	AutoCloseable interceptor; call close() to disable interception

Exceptions

Exception	Condition
IllegalArgumentException	WebDriver instance does not implement HasDevTools

Usage Examples

Mock API Response with Routable

import org.openqa.selenium.devtools.NetworkInterceptor;
import org.openqa.selenium.remote.http.HttpResponse;
import org.openqa.selenium.remote.http.Route;
import org.openqa.selenium.remote.http.Contents;

try (NetworkInterceptor interceptor = new NetworkInterceptor(
    driver,
    Route.matching(req -> req.getUri().contains("/api/users"))
        .to(() -> req -> new HttpResponse()
            .setStatus(200)
            .setContent(Contents.utf8String("{\"users\": []}"))))) {

    driver.get("https://example.com");
    // All /api/users requests return the mocked response
}

Pass Through with Logging (Filter)

try (NetworkInterceptor interceptor = new NetworkInterceptor(
    driver,
    (Filter) next -> req -> {
        System.out.println("Request: " + req.getUri());
        HttpResponse response = next.execute(req);
        System.out.println("Response: " + response.getStatus());
        return response;
    })) {

    driver.get("https://example.com");
}

Simple Handler (No Pass-Through)

try (NetworkInterceptor interceptor = new NetworkInterceptor(
    driver,
    (HttpHandler) req -> {
        if (req.getUri().endsWith("/blocked")) {
            return new HttpResponse().setStatus(403);
        }
        return NetworkInterceptor.PROCEED_WITH_REQUEST;
    })) {

    driver.get("https://example.com");
}

Related Pages

Implements Principle

• Principle:SeleniumHQ_Selenium_Network_Traffic_Interception