fix(selenium-devtools-py): anchor the document the drain reads

[vishnuv688]

What & why

Type of change

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Polish (an improvement to an existing feature)
• Breaking change (existing behavior changes for users)
• Documentation
• Internal (build, CI, dependencies, tooling)

Packages touched

• shared (types and contracts)
• core (framework-agnostic capture/reporting)
• elements (published element/snapshot API — @wdio/elements)
• service (WebdriverIO adapter)
• nightwatch-devtools (Nightwatch adapter)
• selenium-devtools (Selenium adapter)
• backend (server)
• app (UI)
• script (page-injected runtime)
• selenium-devtools-py

Notes for reviewers

Screenshots / recordings

[greptile-apps]

Greptile Summary

The PR makes Python Selenium collector drains synchronously anchor the current document before reading and resetting its trace buffer, preventing short-lived navigation destinations from disappearing from replay.

• Reuses one collector-readiness expression for both readiness probes and drains.
• Forces document anchoring on initial and recovery drains.
• Adds focused tests for ordering, idempotence, missing collectors, and recovery.
• Updates package documentation and repository implementation notes.

Confidence Score: 5/5

The PR appears safe to merge, with the anchor operation synchronously completing before the trace buffer is read and reset.

The changed Python drain mirrors the existing guarded JavaScript adapter sequence, the collector synchronously appends at most one document anchor, and the recovery path retries through the same atomic operation.

Important Files Changed

Filename	Overview
packages/selenium-devtools-py/src/selenium_devtools/snapshot.py	Introduces an atomic guarded anchor-and-drain expression and applies it to normal and recovery reads without an identified correctness regression.
packages/selenium-devtools-py/tests/test_snapshot.py	Adds focused fake-collector coverage for forced anchoring, single anchor emission, operation ordering, collector absence, and reinjection recovery.
packages/selenium-devtools-py/README.md	Updates the DOM snapshot capability description to document forced document anchoring during drains.
CLAUDE.md	Records the drain race, unconditional anchoring invariant, and collector idempotence rationale.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Python Selenium drain] --> B{Collector present?}
  B -- No --> C[Install collector]
  C --> D[Retry drain]
  B -- Yes --> E[Capture current document]
  D --> E
  E --> F[Read and reset trace buffer]
  F --> G[Normalize mutations]
  G --> H[Send DOM evidence]

Loading

_{Reviews (1): Last reviewed commit: "fix(selenium-devtools-py): anchor the do..." | Re-trigger Greptile}