Screenshots, Logs, Network Evidence, and Failure Diagnostics: Configuration, Design Patterns, and Trade-Offs

1. Evidence is a policy surface

The capture API is the easy part. The hard part is deciding when, how much, and for how long. Evidence policy belongs in test infrastructure and CI governance, not scattered across page objects or hidden inside random assertions.

2. Capture-on-failure versus always capture

The following table organizes the key choices and evidence for Capture-on-failure versus always capture. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

3. Viewport, element, and full-page screenshots

The standard portable baseline is a current-window screenshot through save_screenshot(). Element screenshots can isolate a component. Some bindings/drivers expose browser-specific full-page screenshot functions, but do not make them a cross-browser contract unless the matrix verifies support. Full-page images also increase storage and privacy exposure.

from pathlib import Path
from selenium.webdriver.common.by import By

root = Path("evidence/case-17")
root.mkdir(parents=True, exist_ok=True)
driver.save_screenshot(str(root / "viewport.png"))
card = driver.find_element(By.CSS_SELECTOR, '[data-testid="status"]')
card.screenshot(str(root / "status-element.png"))

4. Targeted DOM snippets versus page source

The following table organizes the key choices and evidence for Targeted DOM snippets versus page source. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

5. Classic logs versus WebDriver BiDi

get_log() remains useful when the selected browser/driver exposes the needed type. It is easy to integrate into existing failure hooks, but log-type parity is not guaranteed. Current WebDriver BiDi provides event-oriented console and JavaScript-error handlers and is the standards-based cross-browser direction. That stream model is better when timing and subscription scope matter, but it introduces listener lifecycle and browser-support prerequisites.

6. HAR-like network evidence versus privacy/storage cost

Network evidence has a steep sensitivity curve. URL and status may be enough to explain a 503. Request headers can contain bearer tokens/cookies. Bodies can contain credentials, user content, and proprietary records. A “capture all HAR” default is therefore a security and storage decision, not merely a debugging convenience.

7. Retention and artifact classes

Classify artifacts by sensitivity and operational value. A synthetic screenshot from a training fixture can have a different retention period from an authenticated enterprise network trace. CI artifact expiration should be explicit, and incident preservation should be an auditable exception rather than “keep forever.”

8. Parallel-safe naming and immutable attempts

The following example makes the Parallel-safe naming and immutable attempts behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

from datetime import datetime, timezone
from pathlib import Path
import uuid

def artifact_root(test_id, attempt, shard):
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
    nonce = uuid.uuid4().hex[:8]
    return Path("evidence") / test_id / f"a{attempt}-{shard}-{stamp}-{nonce}"

root = artifact_root("cart-tax", 1, "s03")
root.mkdir(parents=True, exist_ok=False)

exist_ok=False turns a collision into a visible infrastructure error instead of silently merging two bundles.

9. Worked decision table

The following table organizes the key choices and evidence for Worked decision table. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

10. Keep configuration layers separate

Selenium browser options determine session capabilities such as BiDi enablement or browser-specific logging. The test framework decides failure hooks and assertion lifecycle. The AUT controls application logging/testability hooks. Grid controls remote routing/node logs. CI controls artifact upload/retention. A browser preference cannot fix a CI retention policy, and a test retry cannot fix a Grid node capacity problem.

11. Performance and capacity are causal

Evidence I/O adds real runtime: PNG encoding, filesystem writes, network trace processing, and CI upload consume CPU, disk, and bandwidth. On a large parallel Grid, “capture everything always” can itself extend test time and increase queue pressure. Measure artifact volume and upload duration separately from browser session startup and AUT latency.

12. Security/privacy design patterns

Use synthetic accounts for automated flows, prevent CI secrets from entering URLs, avoid personal browser profiles, and review screenshots/download directories before artifact upload. If an enterprise proxy or authenticated browser cloud is optional, describe its evidence access/retention separately from the free local path.

13. Summary and bridge

A mature evidence policy is proportional, correlated, immutable per attempt, and privacy-aware. Lesson 4 stress-tests that policy against realistic failures: late capture, retry overwrites, secret leakage, noisy consoles, missing network context, parallel collisions, and Grid logs detached from session identity.

Knowledge check

Official references and version notes

• Selenium 4.47 release notes — stable binding/Grid baseline pinned for this chapter.
• Selenium downloads — current stable clients and Selenium Server/Grid.
• Selenium Python 4.47 API — supported Python versions and WebDriver API surface.
• Chromium WebDriver API — get_log, log_types, screenshot APIs, and Chromium-specific capabilities.
• WebDriver BiDi — W3C bidirectional event direction and enablement.
• WebDriver BiDi logging — current console-message and JavaScript-error handlers.
• WebDriver BiDi network — current network handler concepts; Chapter 18 covers these APIs in depth.
• Selenium Grid — remote session and node boundary.
• Grid getting started — local/free Grid execution and version alignment.
• Docker Selenium — official containerized Grid distribution; optional in this chapter.