How to Capture network traffic in Selenium (2026)

TL;DR

Enable BiDi in browser options, create org.openqa.selenium.bidi.module.Network, register onBeforeRequestSent or onResponseCompleted before triggering traffic, and synchronize on the matching event. Use intercept commands only for control operations such as auth, failure injection, or request continuation.

Key Takeaways

• Enable BiDi when creating the browser session, before constructing Network.
• Register network listeners before the navigation or user action that emits traffic.
• Filter events by URL, method, context, and response data instead of assuming event order.
• Use thread-safe collections or CompletableFuture because callbacks are asynchronous.
• Add an intercept only when a request must be blocked or modified, then continue every unmatched blocked request.
• Close Network to unsubscribe listeners and always quit the WebDriver session.

selenium how to capture network traffic is the practical question this guide answers. The selenium BiDi network java API gives a Selenium test a live, bidirectional channel for browser network events and commands. Enable BiDi on the browser options, create org.openqa.selenium.bidi.module.Network, subscribe before triggering traffic, and synchronize on the request or response that matters.

This is different from scraping a performance log after the fact. WebDriver BiDi can emit typed before-request, response-started, response-completed, authentication, and fetch-error events while the session runs. It can also intercept requests, continue them, fail them, provide auth, and control cache behavior where the browser supports those commands.

TL;DR

FirefoxOptions options = new FirefoxOptions().enableBiDi();
WebDriver driver = new FirefoxDriver(options);

try (Network network = new Network(driver)) {
  CompletableFuture<BeforeRequestSent> future = new CompletableFuture<>();
  network.onBeforeRequestSent(future::complete);
  driver.get("https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html");
  BeforeRequestSent event = future.get(5, TimeUnit.SECONDS);
  System.out.println(event.getRequest().getUrl());
} finally {
  driver.quit();
}

1. Selenium BiDi Network Java: What It Is: selenium how to capture network traffic

Classic WebDriver is mostly request and response: the client sends a command such as find element or navigate, then waits for a result. WebDriver BiDi adds a persistent WebSocket connection so the browser can send events to the client and the client can issue BiDi commands during the session.

The Java Network module is a typed Selenium layer over the W3C WebDriver BiDi network domain. Its event callbacks receive BeforeRequestSent, ResponseDetails, or FetchError objects rather than unstructured log strings. RequestData exposes request ID, URL, method, headers, cookies, destination, and timing data. ResponseData exposes URL, status, status text, protocol, MIME type, cache information, headers, and sizes.

The module is useful when UI behavior depends on browser traffic: verify that clicking Save emitted the expected endpoint, confirm a critical resource returned 200, prove a response came from cache or did not, handle an authentication challenge, or inject a controlled network failure.

It does not replace API tests. A BiDi assertion proves what this browser session requested and received within a UI flow. Direct API tests remain better for broad contract, schema, authorization, and data-driven coverage. See API testing versus UI testing for a practical layer boundary.

2. Compare WebDriver BiDi, CDP, and Proxy Approaches: selenium how to capture network traffic

Selenium's long-term direction is standards-based WebDriver BiDi. CDP can still be appropriate for a Chromium-only capability not yet present in BiDi, but isolate that dependency so it does not spread across the framework. Do not label a CDP class as BiDi merely because both use a bidirectional connection.

A proxy remains useful for organization-wide traffic capture, certificate testing, or browsers without the required module. It adds infrastructure and can change connection behavior. Choose it because the requirement needs a proxy boundary, not because an old snippet is familiar.

For new cross-browser test code, start with the public BiDi module that provides the needed command or event. Check the Selenium and browser support matrix during upgrades because the Java class is marked beta and the standard continues to evolve.

3. Add Dependencies and Enable the BiDi Session

Pin a current Selenium Java release in Maven:

<dependencies>
  <dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.46.0</version>
  </dependency>
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.11.4</version>
    <scope>test</scope>
  </dependency>
</dependencies>

Enable BiDi as part of session creation. Both FirefoxOptions and Chromium options expose enableBiDi in the current Java API:

FirefoxOptions firefoxOptions = new FirefoxOptions().enableBiDi();
WebDriver firefox = new FirefoxDriver(firefoxOptions);

ChromeOptions chromeOptions = new ChromeOptions().enableBiDi();
WebDriver chrome = new ChromeDriver(chromeOptions);

Do not create a normal session and try to enable the capability afterward. Capabilities are negotiated at session start. For RemoteWebDriver, pass BiDi-enabled browser options to the Grid or vendor and confirm that the returned capabilities include the WebSocket URL needed for the connection.

Start with one browser whose current implementation supports the event or command you need, then add browsers based on product coverage. A session may support BiDi generally while a newer network command remains unavailable. Treat UnsupportedCommandException as capability evidence, not as a reason to silently skip assertions.

4. Observe a Request With a Runnable JUnit Test

This complete example uses the official Selenium test page. The listener is registered before navigation, and CompletableFuture gives the asynchronous callback a bounded synchronization point.

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.bidi.module.Network;
import org.openqa.selenium.bidi.network.BeforeRequestSent;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.firefox.FirefoxOptions;

class BidiNetworkRequestTest {
  private WebDriver driver;

  @BeforeEach
  void startBrowser() {
    driver = new FirefoxDriver(new FirefoxOptions().enableBiDi());
  }

  @AfterEach
  void stopBrowser() {
    if (driver != null) driver.quit();
  }

  @Test
  void observesTheNavigationRequest() throws Exception {
    String page =
        "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html";

    try (Network network = new Network(driver)) {
      CompletableFuture<BeforeRequestSent> match = new CompletableFuture<>();
      network.onBeforeRequestSent(event -> {
        if (event.getRequest().getUrl().equals(page)) {
          match.complete(event);
        }
      });

      driver.get(page);
      BeforeRequestSent event = match.get(5, TimeUnit.SECONDS);

      assertEquals("GET", event.getRequest().getMethod().toUpperCase());
      assertEquals(page, event.getRequest().getUrl());
      assertEquals(driver.getWindowHandle(), event.getBrowsingContextId());
      assertTrue(event.getRequest().getRequestId().length() > 0);
    }
  }
}

Filtering inside the callback prevents a favicon, redirect, or subresource from satisfying the future. complete is safe if another matching event appears because only the first completion wins. The five-second bound keeps a missing event from hanging the suite.

5. Assert Completed Responses, Status, MIME Type, and Cache

Use onResponseCompleted when the test cares about a response that finished. onResponseStarted arrives earlier and is useful when header or status availability is enough. Both callbacks receive ResponseDetails in the current Java module.

CopyOnWriteArrayList<ResponseDetails> completed =
    new CopyOnWriteArrayList<>();

try (Network network = new Network(driver)) {
  network.onResponseCompleted(event -> {
    if (event.getRequest().getUrl().contains("/api/orders")) {
      completed.add(event);
    }
  });

  driver.findElement(By.id("load-orders")).click();

  new WebDriverWait(driver, Duration.ofSeconds(8))
      .until(d -> !completed.isEmpty());

  ResponseData response = completed.get(0).getResponseData();
  assertEquals(200, response.getStatus());
  assertTrue(response.getMimeType().contains("json"));
  assertFalse(response.isFromCache());
}

CopyOnWriteArrayList is appropriate for a modest test event stream because the callback and test thread can access it safely. For a single expected event, CompletableFuture is simpler. Do not use ArrayList from both threads without synchronization.

Filter by endpoint, request method, browsing context, or a correlation value when the application can make parallel calls. Never assume completed.get(0) is the business request unless the listener added only matching events.

Status and MIME type are useful browser-integration assertions. Deep response body and schema validation belongs in direct API tests unless the body itself must be observed at this browser boundary.

6. Correlate Requests With the User Action That Caused Them

Register listeners immediately before the action under test, not in a global suite initializer that captures unrelated traffic forever. Establish page readiness first, create a narrow future or thread-safe event collector, trigger one action, and wait for the match.

URL alone may be insufficient. An application can call the same endpoint for initial load and manual refresh. Add method, query, context, or application correlation data to the filter. RequestData.getMethod and getUrl are stable starting points. Headers are available when the product supplies a correlation ID.

Redirects create multiple network events. ResponseDetails and BeforeRequestSent carry redirect count and navigation information through their base data. Decide whether the requirement concerns the initial URL, final response, or every hop. Assert that explicitly instead of relying on event arrival order.

For multiple expected calls, use a predicate over a thread-safe collection and wait until all required endpoint keys appear. Keep the predicate deterministic. If duplicates are allowed, represent expectations as counts or a multiset rather than a boolean per URL.

Do not put JUnit assertions directly inside the callback. An assertion failure on the listener thread may not fail the test in the expected way. Capture typed data or complete a future, then assert on the test thread.

7. Filter and Synchronize Selenium BiDi Network Java Events

Network callbacks are asynchronous. The browser may emit an event before the UI command returns, after it returns, or concurrently with another request. Thread safety and listener timing are therefore part of test correctness.

Choose one synchronization pattern:

• CompletableFuture for one matching event.
• CopyOnWriteArrayList for a small collection read frequently and written infrequently.
• BlockingQueue when the test consumes an ordered stream.
• ConcurrentHashMap when events are correlated by request ID or endpoint key.

Give every wait a timeout and a message describing the missing traffic. On failure, print the filtered URLs and methods that were observed, not the full headers and bodies. Full traffic logs can expose credentials and create noisy CI artifacts.

Construct Network for the driver to observe all subscribed browsing contexts, or use the constructor that takes a browsing context ID or set of IDs when scope matters. A new tab has a different top-level context. If the user action opens it, subscribe with an intentional scope rather than assuming the original window's listener semantics.

Clean synchronization code is what separates a useful network assertion from a race-prone callback demo.

8. Handle Authentication Challenges

Authentication control requires an intercept at the AUTH_REQUIRED phase. Register the handler before navigating to the protected resource:

try (Network network = new Network(driver)) {
  String interceptId = network.addIntercept(
      new AddInterceptParameters(InterceptPhase.AUTH_REQUIRED));

  network.onAuthRequired(details ->
      network.continueWithAuth(
          details.getRequest().getRequestId(),
          new UsernameAndPassword("test-user", "test-password")));

  driver.get("https://example.test/protected");
  assertTrue(driver.getPageSource().contains("Account overview"));

  network.removeIntercept(interceptId);
}

The methods shown are the current Java BiDi API, while the URL and credentials are placeholders for a controlled test environment. Store secrets in CI secret management, never in source code or traffic artifacts.

Other supported outcomes include continueWithAuthNoCredentials and cancelAuth. Test each only when it represents a product requirement. A negative authentication test can cancel or omit credentials and verify the application result.

An intercept blocks matching traffic at its phase. Always provide a command that resolves each blocked request. Leaving it blocked creates an apparent page hang that looks like a navigation timeout.

Close the Network scope after the protected journey so credentials and handlers cannot affect later tests.

9. Inject Failures and Control Browser Cache

Failure injection proves how the UI behaves when a dependency is unavailable. Add a BEFORE_REQUEST_SENT intercept, fail the targeted request, and continue every other blocked request:

try (Network network = new Network(driver)) {
  network.addIntercept(
      new AddInterceptParameters(InterceptPhase.BEFORE_REQUEST_SENT));

  network.onBeforeRequestSent(event -> {
    if (!event.isBlocked()) return;

    String requestId = event.getRequest().getRequestId();
    if (event.getRequest().getUrl().contains("/api/recommendations")) {
      network.failRequest(requestId);
    } else {
      network.continueRequest(new ContinueRequestParameters(requestId));
    }
  });

  driver.findElement(By.id("load-recommendations")).click();
  WebElement error = new WebDriverWait(driver, Duration.ofSeconds(8))
      .until(ExpectedConditions.visibilityOfElementLocated(
          By.cssSelector("[role='alert']")));
  assertEquals("Recommendations are temporarily unavailable", error.getText());
}

The page selectors are application examples, but every Selenium method is real. Scope the intercept with URL patterns when the target browser and current binding behavior meet the suite's needs. Broad interception is easier to demonstrate but creates more callback work and risk.

To test an uncached journey, call network.setCacheBehavior(CacheBehavior.BYPASS) before navigation. Restore CacheBehavior.DEFAULT or end the isolated session afterward. Cache control changes traffic volume, so document it as scenario setup and do not apply it globally without a reason.

10. Manage Listener and Session Lifecycle

Network implements AutoCloseable. A try-with-resources block closes its subscriptions even when assertions fail. Close Network before quitting the driver so it can unsubscribe while the connection exists. The outer test teardown should still quit the browser.

Avoid one static Network object shared across parallel tests. It couples callbacks, browser sessions, and event collections. Network state belongs to one driver session, and listeners should usually belong to one scenario or focused fixture.

When a test needs several event types, one Network instance inside the scenario can register them all. Keep the resulting collectors separate and correlate by request ID where necessary. Close only after the final event is consumed.

In a remote test, a dropped WebSocket can make the network observer fail even if classic WebDriver commands still return. Report the BiDi connection failure as test infrastructure evidence. Do not silently disable the network assertion, because that changes the test's purpose.

11. Design a Framework-Level Network Probe

Build a small domain-focused observer rather than exposing the entire Network object to every test. A probe can register a filtered CompletableFuture, return the typed event, and own timeout diagnostics. Keep intercept commands in separate helpers because observing and controlling traffic have different risk.

For example, an OrdersNetworkProbe might expose awaitCompletedCreateOrder(), which filters POST and the exact orders path, then returns ResponseDetails. The test triggers checkout and asserts status plus the UI confirmation. This reads better than a generic waitForUrlContains string helper.

Do not create one global traffic recorder that stores every request body. It consumes memory, slows analysis, and risks secrets. Capture only metadata required by the scenario. Redact Authorization, Cookie, Set-Cookie, tokens, and personal data in diagnostics.

Place broad API correctness in an API client test suite. BiDi probes should answer browser-boundary questions: Did the UI issue the call? Did this page receive an unsuccessful status? Was the response served from cache? Did the application display the right fallback after an injected failure?

The Selenium network interception guide covers additional framework boundaries and negative-path design.

12. Debug BiDi Network Tests on Grid and CI

When no event arrives, verify that BiDi was enabled in requested and returned capabilities, the remote end supports the required network feature, and the listener was registered before traffic. Confirm the user action actually ran and that the URL filter matches redirects and environment hosts.

When the page hangs, look for an intercept that blocked a request without continueRequest, failRequest, provideResponse, or an authentication resolution. Broad BEFORE_REQUEST_SENT interception is especially sensitive because it can stop navigation resources.

When events appear locally but not remotely, record Selenium client version, browser version, driver or Grid version, returned capabilities, and context ID. Keep the client and Grid reasonably aligned during upgrades. Use a minimal official test page to separate protocol support from application complexity.

When parallel tests leak events, remove shared static collectors and bind every Network instance to its driver. Use unique application correlation IDs so same-endpoint requests from different tests cannot satisfy the wrong wait.

The Selenium Grid troubleshooting checklist provides a broader session and capability diagnostic sequence.

13. Apply Security, Privacy, and Performance Guardrails

Network data can contain passwords, bearer tokens, session cookies, personal data, and internal URLs. Treat it as sensitive test data. Do not print all headers, cookies, request bodies, or response content to a public CI log. Redact at collection time and set artifact retention appropriately.

Use controlled test environments for auth and failure injection. Never direct a test with embedded credentials toward production. Do not fail analytics, payment, or security endpoints in a shared environment without an approved isolation strategy.

Subscribe narrowly. Capturing every event for a long journey increases memory and callback work. Filter immediately, complete the future, and close the Network scope when the requirement is satisfied.

Avoid fabricated performance thresholds from BiDi event timing alone. Browser network timing can help diagnose, but performance acceptance needs a defined environment, sampling method, and metric. This guide makes no universal latency claim because infrastructure and cache state vary.

14. Validate Compatibility Without Silent Test Downgrades

BiDi support has three moving parts: Selenium client API, browser or driver implementation, and Grid or cloud infrastructure. Pin and record all three. A method existing in the Java client does not prove that every remote browser implements the underlying command.

Create a small capability test that enables BiDi, subscribes to one known request, and observes one completed response. Run it early for each browser image. Add command-specific checks for features your suite uses, such as auth interception or cache bypass. This gives upgrade failures a focused home.

Do not catch UnsupportedCommandException and convert the network assertion into an unconditional pass. Either mark the browser combination as unsupported through explicit test configuration or fail the capability contract. Silent downgrade means a test named for network behavior no longer tests network behavior.

Review Selenium release notes and official API documentation when changing versions. Keep BiDi access behind a small framework boundary so a type or method adjustment has limited blast radius. Avoid reflection-based calls that compile while hiding whether the supported API changed.

15. Write Network Assertions That Explain User Risk

A useful BiDi check connects traffic to a user-visible risk. Verifying that Save sent POST /orders and received 201 can explain why the confirmation should appear. Verifying every image status on every page usually creates noise better handled by monitoring or a focused resource audit.

Phrase failures in domain language and include safe metadata: expected method and route, observed status, browser, and correlation ID after redaction. Avoid dumping the entire event object because its toString representation or nested data may expose secrets.

Separate transport assertions from UI assertions. First wait for and validate the matching response. Then wait for the confirmation, error alert, or retry control. When only one fails, the result distinguishes a backend or network problem from a rendering and state-management problem.

This two-boundary design is especially valuable for negative tests. After failRequest, assert both that the target request produced the intended failure path and that the UI offered the required recovery. A network fault without a product assertion is an infrastructure experiment, not a complete user scenario.

Interview Questions and Answers

Q: What is WebDriver BiDi?

It is a W3C bidirectional protocol that adds a persistent event and command channel to WebDriver. The browser can push events such as network activity while the client continues sending automation commands.

Q: How do you enable Selenium BiDi in Java?

Call enableBiDi on the browser options before creating the driver. Then construct org.openqa.selenium.bidi.module.Network with that driver and register listeners before traffic occurs.

Q: How do you assert a network response status?

Register onResponseCompleted, filter the callback to the required request, transfer the event through CompletableFuture or a thread-safe collection, and assert event.getResponseData().getStatus() on the test thread.

Q: Why should assertions not run inside the callback?

The callback can execute on a different thread, so a thrown assertion may not be reported by the test runner as expected. Capture the data, synchronize with the test thread, and assert there.

Q: What is the difference between observation and interception?

Observation subscribes to events without pausing traffic. Interception adds a blocking phase so the test can continue, modify, authenticate, fail, or provide a response. Every blocked request must be resolved.

Q: How is BiDi different from CDP?

BiDi is a cross-browser W3C standard integrated into WebDriver. CDP is Chromium-specific and exposes Chrome DevTools capabilities. Use BiDi for portable supported features and isolate CDP-only needs.

Q: How do you avoid race conditions in network tests?

Subscribe before the action, filter precisely, use CompletableFuture or thread-safe collections, and apply bounded waits. Correlate duplicate endpoints by method, context, request ID, or application metadata.

Q: When should network assertions remain out of a UI test?

Detailed schema, authorization matrices, and large data combinations belong in direct API tests. Add BiDi assertions when the browser's actual request or response is part of the UI integration requirement.

Common Mistakes

• Enabling BiDi after session creation: Capabilities must be negotiated at startup.
• Registering the listener after clicking: Fast traffic can be missed.
• Assuming the first event is the target: Filter by URL, method, context, or correlation data.
• Using ArrayList across callback and test threads: Choose a thread-safe handoff.
• Asserting inside a callback: Assert on the test thread after synchronization.
• Blocking all requests without continuing unmatched ones: The page will hang.
• Forgetting to close Network: Listeners can leak into later scenario work.
• Treating BiDi as a full API-test replacement: Keep broad contracts at the API layer.
• Logging secrets and cookies: Redact sensitive network metadata.
• Calling CDP code BiDi: They are different protocols and portability contracts.

Conclusion

The reliable selenium BiDi network java pattern is: enable BiDi at session creation, open a scoped Network resource, subscribe before traffic, filter typed events precisely, synchronize safely, and assert on the test thread. Add interception only when the scenario must control traffic, and resolve every blocked request.

Start with the runnable before-request JUnit test, then add one product-specific response assertion. Keep network checks focused on browser integration, close resources consistently, and preserve direct API tests for broad service validation.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Capture network traffic in Cypress (2026)
• How to Capture network traffic in Playwright (2026)
• How to Use Selenium DevTools in Selenium 4 in Java (2026)
• How to Debug a failing test in VS Code in Selenium (2026)
• How to Run tests in headed mode in Selenium (2026)
• How to Scroll to an element in Selenium (2026)