Screenshots, Logs, Network Evidence, and Failure Diagnostics: Core Concepts and Mental Model

1. The practical problem: a screenshot is not a diagnosis

Chapters 06 and 15 already established two constraints: synchronization must describe a real condition, and a retry does not erase the first failure. Chapter 17 adds the operational consequence. A screenshot can show a button that appears disabled, but it cannot by itself tell you whether the AUT rejected a request, JavaScript crashed, a request never reached the server, WebDriver lost its session, or the test asserted the wrong state.

2. Mental model: one failure, correlated evidence layers

flowchart TD
  T[Test step + UTC timestamp + test_id] --> F[Assertion / exception]
  F --> V[Viewport screenshot]
  F --> D[URL + title + targeted DOM state]
  F --> B[Browser console / JS errors]
  F --> N[Network / server evidence]
  F --> W[WebDriver + session + capabilities]
  W --> G[Grid / node logs if remote]
  T --> C[CI job / attempt / shard metadata]
  V --> P[Privacy-aware evidence bundle]
  D --> P
  B --> P
  N --> P
  W --> P
  G --> P
  C --> P
  P --> R[Triage conclusion]

The test step creates the correlation anchor: a stable test ID, attempt number, and UTC timestamp. The assertion or exception is the primary symptom. Visual, DOM, browser, network, WebDriver/Grid, and CI evidence are separate observations. They become useful only when they refer to the same session and time window. The bundle then supports a conclusion; it does not replace engineering judgment.

3. Objects, state stores, and trust boundaries

The following table organizes the key choices and evidence for Objects, state stores, and trust boundaries. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

4. Read-only inspection before changing evidence settings

Prove what session you actually have. Do not assume a log type, browser version, or remote/local topology from the test name.

import selenium
from selenium import webdriver

browser = webdriver.Chrome()
try:
    browser.get("http://127.0.0.1:8781/?test_id=preflight")
    caps = browser.capabilities
    print("selenium", selenium.__version__)
    print("session_id", browser.session_id)
    print("browser", caps.get("browserName"), caps.get("browserVersion"))
    print("platform", caps.get("platformName"))
    print("url", browser.current_url)
    print("title", browser.title)
    print("log_types", browser.log_types)
finally:
    browser.quit()

driver.log_types is the discovery mechanism: if a browser does not expose a requested classic log type, the collector must record that limitation instead of manufacturing an empty “proof.” Returned capabilities are evidence of the negotiated session, not a copy of what the test hoped to request.

5. What each evidence type can actually prove

The following table organizes the key choices and evidence for What each evidence type can actually prove. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

6. Screenshots: evidence of pixels, not causality

driver.save_screenshot(path) stores a PNG of the current window. Capture it before navigation, teardown, retry, or browser closure can destroy the state. Use unique paths per test ID and attempt. For privacy-sensitive pages, a screenshot may need masking or may be prohibited entirely; that is a test-data and artifact-policy decision, not a Selenium limitation.

from pathlib import Path
from datetime import datetime, timezone

stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
root = Path("evidence") / "checkout-guest" / f"{stamp}-attempt-1"
root.mkdir(parents=True, exist_ok=False)
driver.save_screenshot(str(root / "viewport.png"))

7. Prefer targeted state over indiscriminate page-source dumps

Page source can be useful, but collecting it by default expands privacy and storage cost. A targeted evidence schema is usually easier to review and less likely to contain hidden form fields or embedded data.

import json
from selenium.webdriver.common.by import By

status = driver.find_element(By.CSS_SELECTOR, '[data-testid="status"]')
state = {
    "text": status.text,
    "data_state": status.get_attribute("data-state"),
    "url": driver.current_url,
    "title": driver.title,
}
(root / "dom.json").write_text(json.dumps(state, indent=2), encoding="utf-8")

8. Browser logs, BiDi events, and network evidence are different layers

Python 4.47 exposes log_types and get_log(type), but available classic logs are browser/driver dependent. WebDriver BiDi is the standards-based cross-browser direction for event streams such as console messages, JavaScript errors, and network events. Because Chapter 18 is dedicated to BiDi, this chapter uses classic logs only when explicitly available and introduces BiDi as a preview rather than making it a hidden prerequisite.

9. Correlation is an evidence schema, not a filename afterthought

A production bundle should be attributable to a unique scenario and attempt. Useful correlation fields are test_id, UTC capture time, attempt, browser session ID, browser name/version, platform, CI job/shard ID, and—when remote—the Grid session/node correlation available to operators. Never assume wall-clock time alone is unique under parallelism.

{
  "test_id": "checkout-guest",
  "attempt": 1,
  "captured_at": "2026-08-28T04:30:15.123456Z",
  "session_id": "<webdriver-session-id>",
  "browser": "chrome",
  "browser_version": "<returned capability>",
  "ci_job": "job-4312",
  "shard": "3-of-8"
}

10. Sensitivity, redaction, retention, and access

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

11. Local versus Grid/remote evidence ownership

Locally, the test runner, browser, fixture server, and artifact directory may share one machine. In Grid, the browser and driver may run on another node. A local path cannot be assumed to exist on the node; node logs may live outside the test workspace; and CI must preserve the runner-side bundle before the ephemeral job is destroyed. Correlate remote evidence by session ID rather than by “latest driver log.”

12. DevOps connection: make failure bundles triageable remotely

A useful pipeline does not simply upload a directory named screenshots. It uploads a structured bundle after a failed scenario, records its correlation metadata, preserves the first attempt even if a controlled rerun occurs, applies a retention policy, and links the artifact to the exact commit/job/shard. That turns an intermittent red CI job into an incident another engineer can analyze without recreating the runner.

13. Anti-patterns that destroy evidence

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

14. Summary and bridge

Evidence engineering is the disciplined correlation of independent observations around one failure. Lesson 2 builds a loopback fixture and a privacy-aware collector that captures screenshot, URL/title, selected DOM state, supported browser logs, resource timing, and synthetic server evidence before teardown.

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.