Add Python examples for W3C BiDi network intercept commands

[ajithrao2509]

Closes #2638

Thanks for contributing to the Selenium site and documentation!

Description

Adds Python test examples for the W3C BiDi Network intercept commands.

Two files changed:

• examples/python/tests/bidi/test_network_commands.py — new Python test file with 4 tests
• website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md — Python tab added to each section

Motivation and Context

The W3C BiDi Network documentation page had Java and JavaScript examples
only. Python examples were completely absent — not even a badge-code
placeholder. This PR adds Python equivalents for the commands we have
tests for, and honest badge-code placeholders for the ones we don't.

Types of changes

• Code example added
• Code example added to all translated languages (not done — Python tabs added to en only, translations to follow separately)
• Change to the site
• Improved translation

Checklist

• Follows existing file and naming conventions
• Each test has an assertion
• License header included
• @pytest.mark.driver_type("bidi") marker on every test
• gh-codeblock references use verified line numbers
• badge-code placeholder used honestly where no test exists
• Issue [🚀 Feature]: Add Python examples for W3C BiDi network intercept commands #2638 raised before this PR

[netlify]

👷 Deploy request for selenium-dev pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	dcfd84b

[CLAassistant]

All committers have signed the CLA.

[qodo-code-review]

Review Summary by Qodo

Add Python examples for W3C BiDi network intercept commands

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Add 4 Python test examples for W3C BiDi network commands
• Integrate Python code references into network documentation
• Include badge-code placeholders for unimplemented features
• Support network intercept, request handlers, and event operations

Diagram

flowchart LR
  A["Python Test File"] -->|"4 test functions"| B["Network Commands"]
  B -->|"add_intercept"| C["Add Intercept"]
  B -->|"remove_intercept"| D["Remove Intercept"]
  B -->|"request_handler"| E["Request Handler"]
  B -->|"fail_request"| F["Fail Request"]
  G["Documentation File"] -->|"references"| A
  G -->|"Python tabs"| H["Commands Section"]
  G -->|"Python tabs"| I["Events Section"]

Loading

File Changes

1. examples/python/tests/bidi/test_network_commands.py 🧪 Tests +65/-0

Python BiDi network command test implementations

• New Python test file with 4 BiDi network command tests
• Tests cover add_intercept, remove_intercept, fail_request operations
• Tests cover add_request_handler and remove_request_handler operations
• All tests marked with @pytest.mark.driver_type("bidi") decorator

examples/python/tests/bidi/test_network_commands.py

---

2. website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md 📝 Documentation +37/-5

Integrate Python examples into network documentation

• Add Python tab with code references to 3 command examples (add_intercept, remove_intercept,
 fail_request)
• Add Python tab with code reference to 1 event example (add_request_handler)
• Add badge-code placeholders for 5 unimplemented Python features
• Minor whitespace cleanup (trailing spaces and final newline)

website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. test_fail_request never fails ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

test_fail_request does not actually invoke any BiDi “fail request” capability and contains no
assertion, and it also broadly swallows exceptions, so it can pass without verifying behavior and
misrepresents the intended command example. This breaks parity with the Java example and makes the
Python “Fail request” documentation snippet unreliable and unable to catch regressions.

Code

examples/python/tests/bidi/test_network_commands.py[R35-50]

+def test_fail_request(driver):
+    import time
+    from selenium.webdriver.common.bidi.network import Request
+
+    failed = []
+
+    def on_request(request: Request):
+        failed.append(request)
+
+    driver.network.add_request_handler("before_request", on_request)
+    try:
+        driver.get("https://www.selenium.dev/selenium/web/blank.html")
+    except Exception:
+        pass
+    time.sleep(1)
+    driver.network.clear_request_handlers()

Evidence

The cited Python test registers a before_request handler and performs navigation, but only appends
to a list, sleeps, and clears handlers; it never calls any fail/abort/cancel API and never asserts
an expected outcome, while also catching exceptions in a way that can let the test pass even if
navigation fails for unrelated reasons. The documentation embeds this region as the “Fail request”
Python snippet, yet the corresponding Java example demonstrates the intended pattern—intercept,
explicitly fail the request (e.g., failRequest(...)), and assert the resulting
timeout/failure—showing the current Python example is not meeting the scoped “fail request” intent
or parity requirements.

Include scoped Python tests for specified BiDi network commands
Align Python examples with existing Java tests and Python BiDi patterns
examples/python/tests/bidi/test_network_commands.py[35-50]
examples/java/src/test/java/dev/selenium/bidirectional/webdriver_bidi/NetworkCommandsTest.java[96-105]
examples/python/tests/bidi/test_network_commands.py[34-51]
website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md[125-145]
examples/python/tests/bidi/test_bidi_logging.py[7-16]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`test_fail_request` is used as the Python example for the BiDi “Fail request” command, but it currently only registers a request handler, does not actually fail/abort the request via any BiDi API, and contains no assertion; it also catches broad exceptions and ignores them, allowing the test to pass without validating behavior.

## Issue Context
The docs embed this exact test region as the Python snippet for “Fail request”, so it must demonstrate the real fail/abort capability and verify the expected outcome. Compliance also expects parity with the existing Java intent (intercept + explicit fail + assert timeout/failure), and the current Python test’s `time.sleep(1)` and non-guaranteed cleanup further weaken determinism and reliability.

## Fix Focus Areas
- examples/python/tests/bidi/test_network_commands.py[34-51]
- website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md[125-145]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Request handler removal unverified ✓ Resolved 📎 Requirement gap ☼ Reliability

Description

test_add_and_remove_request_handler removes the handler but never triggers any request/navigation
or asserts the handler was invoked (or stopped being invoked), diverging from established Python
BiDi example patterns and making the “Before Request Sent” docs snippet potentially misleading. As
written, the test can pass even if the event subscription/handler mechanism is broken.

Code

examples/python/tests/bidi/test_network_commands.py[R54-65]

+def test_add_and_remove_request_handler(driver):
+    from selenium.webdriver.common.bidi.network import Request
+
+    requests = []
+
+    def callback(request: Request):
+        requests.append(request)
+
+    callback_id = driver.network.add_request_handler("before_request", callback)
+    assert callback_id is not None
+
+    driver.network.remove_request_handler("before_request", callback_id)

Evidence

Rule 3 points to matching the Python BiDi example pattern used in test_bidi_logging.py, where
handler removal is validated by triggering the relevant event and asserting no additional entries
were collected; in contrast, the network request-handler example only checks for a non-null handler
id and never drives a network request nor uses/asserts on the collected list to prove the “Before
Request Sent” event was observed. Additionally, the docs embed this Python snippet as the “Before
Request Sent” example, while the existing JavaScript example shows the expected flow (subscribe,
navigate to trigger traffic, and assert an event was captured), highlighting the missing trigger and
assertions in the Python version.

Align Python examples with existing Java tests and Python BiDi patterns
examples/python/tests/bidi/test_network_commands.py[54-65]
examples/python/tests/bidi/test_bidi_logging.py[18-28]
examples/python/tests/bidi/test_network_commands.py[53-65]
website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md[151-172]
examples/javascript/test/bidirectional/network_events.spec.js[22-34]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Python “Before Request Sent” example/test registers and removes a request handler but never triggers a network request/navigation and never asserts that the callback fires (or stops firing after removal), so it doesn’t actually demonstrate the event and can pass even if the subscription is broken.

## Issue Context
This test block is embedded in the docs as the Python example for the “Before Request Sent” event, so it should follow the established BiDi example pattern seen in other Python examples (e.g., logging) and the structure of the existing JS example: trigger a deterministic request, wait for the event, assert at least one event was captured, and optionally trigger a second request after handler removal to verify the handler no longer fires.

## Fix Focus Areas
- examples/python/tests/bidi/test_network_commands.py[53-65]
- website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md[151-172]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Private intercept APIs documented ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The Python intercept examples use underscored methods (_add_intercept/_remove_intercept), which
are private by convention and may change without notice. Publishing these in docs encourages
reliance on non-public APIs and makes the documentation/tests brittle.

Code

examples/python/tests/bidi/test_network_commands.py[R22-31]

+def test_add_intercept(driver):
+    intercept = driver.network._add_intercept()
+    assert intercept is not None
+
+
+@pytest.mark.driver_type("bidi")
+def test_remove_intercept(driver):
+    intercept = driver.network._add_intercept()
+    driver.network._remove_intercept(intercept["intercept"])
+    assert driver.network.intercepts == []

Evidence

The new Python tests call underscored methods and are embedded directly into the docs; existing
Python BiDi examples use non-underscored, public-style methods, showing a different (more stable)
pattern for documentation snippets.

examples/python/tests/bidi/test_network_commands.py[21-32]
website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md[13-57]
examples/python/tests/bidi/test_bidi_logging.py[6-16]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Python intercept examples rely on private-by-convention methods (leading underscore). If these are the only available APIs today, they should not be presented as the primary user-facing documentation snippet without a stable wrapper.

## Issue Context
These snippets are embedded into the public docs page under “Add network intercept” and “Remove network intercept”. Other Python BiDi examples in this repo use public APIs without leading underscores.

## Fix Focus Areas
- examples/python/tests/bidi/test_network_commands.py[21-32]
- website_and_docs/content/documentation/webdriver/bidi/w3c/network.en.md[13-57]

## Implementation notes
- Prefer switching examples to the supported public API (if available) for adding/removing intercepts.
- If there is no public API yet, consider:
 - adding/using a documented public wrapper in the examples, or
 - replacing the Python tab with an honest placeholder (`badge-code`) until the API is public/stable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---