feat(selenium-devtools-py): per-test trace archives and tracePolicy

[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
• trace

Notes for reviewers

Screenshots / recordings

[greptile-apps]

Greptile Summary

The PR adds policy-controlled session and per-test trace archives for the Python Selenium adapter.

• Extends the shared worker/backend export contract with trace granularity and retention policy.
• Attributes pytest commands to tests and slices accumulated backend data into per-test archives.
• Adds configuration through Python arguments, pytest CLI/ini options, and trace-related environment fallbacks.
• Moves shared trace-retention logic into the trace package and expands tests and documentation.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/selenium-devtools-py/src/selenium_devtools/init.py	Resolves trace mode, retention policy, and granularity consistently while explicitly warning when ambient environment settings are ignored.
packages/selenium-devtools-py/src/selenium_devtools/pytest_plugin.py	Adds pytest CLI and ini configuration, opts in explicit policy or granularity settings, and attributes commands to the active test.
packages/backend/src/trace-export.ts	Applies shared retention decisions and exports retained per-test slices with collision-resistant filenames.
packages/backend/src/trace-slice.ts	Slices commands by test UID and timestamped evidence by each test’s execution window.
packages/shared/src/trace-export.ts	Extends the worker-to-backend trace export contract for retention policy, granularity, multiple paths, and policy declines.
packages/trace/src/trace-retention.ts	Centralizes retention-policy behavior for backend and in-process trace exporters.

Sequence Diagram

sequenceDiagram
  participant P as Pytest or Python script
  participant A as Python adapter
  participant B as Backend
  participant R as Retention logic
  participant Z as Trace writer
  P->>A: Configure trace mode, policy, granularity
  A->>B: Stream commands, test states, and evidence
  A->>B: Request trace export
  alt Per-test granularity
    B->>B: Slice accumulated run by test
    loop Each test slice
      B->>R: Evaluate retention policy
      R-->>B: Retain or decline
      B->>Z: Write retained slice
    end
  else Session granularity
    B->>R: Evaluate run retention policy
    R-->>B: Retain or decline
    B->>Z: Write retained run
  end
  B-->>A: Paths or policy decline

Loading

_{Reviews (3): Last reviewed commit: "docs(selenium-devtools-py): document gra..." | Re-trigger Greptile}