Merge pull request #247 from webdriverio/vv/trace-mode-parity

Vv/trace mode parity

Author: vishnuv688

.changeset/trace-mode-parity.md

@@ -0,0 +1,17 @@
+---
+"@wdio/devtools-service": minor
+"@wdio/selenium-devtools": minor
+"@wdio/nightwatch-devtools": minor
+"@wdio/devtools-backend": minor
+"@wdio/devtools-app": minor
+"@wdio/devtools-script": minor
+---
+
+Trace mode: a portable `trace.zip` artifact and first-party `show-trace` player, at parity across WebdriverIO, Selenium, and Nightwatch.
+
+- **Trace mode** (`mode: 'trace'`) writes a portable artifact under `test-results/` with no dashboard window — `traceFormat` (`zip` | `ndjson-directory`), `traceGranularity` (`session` | `spec` | `test`), and retry-aware `tracePolicy` retention.
+- **Trace player** (`show-trace`): DOM time-travel replayed from the mutation stream, an A11y tab and pick-locator element overlay, a Transcript tab with Copy-for-LLM, Errors/Console/Network/Source panels, and a scrubbable filmstrip timeline.
+- **Per-test artifacts**: `screenshot` and `video` at `traceGranularity: 'test'`, a dense `filmstrip` into the trace, an `emitArtifactsManifest` index for CI, and inline Allure attachment (WebdriverIO + Selenium).
+- **Assertion capture** (`captureAssertions`, on by default): `node:assert` and framework matchers render as trace action rows.
+
+The trace format and player are identical across all three adapters; capture completeness varies per adapter (see the cross-framework support docs).

.gitignore

@@ -39,8 +39,22 @@ packages/nightwatch-devtools/nightwatch-video-*.webm
 trace-*.zip
 examples/**/trace-*/
 
+# test results
+examples/**/test-results*/
+
 # vitest --coverage output
 coverage/
 
 # pnpm state, cache, logs, and debug files
 /packages/**/*.mjs
+
+.claude
+
+# Local Allure exploration / trace-parity comparison (throwaway — not committed)
+examples/**/allure-results*/
+examples/**/allure-report*/
+packages/**/allure-results*/
+packages/**/allure-report*/
+examples/playwright-allure/
+examples/wdio/cucumber/wdio.allure.conf.ts
+

ARCHITECTURE.md

@@ -140,11 +140,17 @@ Contains: DOM mutation observers, page-side trace collection, a small logger. It
 
 The execution environment is the browser, not Node, so this package cannot import from `core` (Node-only) or from non-browser-safe parts of `shared`.
 
+### `packages/elements`
+
+Element-detection scripts (`@wdio/elements`). Produces the per-action data that feeds the snapshot pipeline: `getSnapshot`, the depth-indented accessibility-tree serializer, and the interactable-element list, plus locator generation.
+
+Consumed by `core` (the element-snapshot builder) and by the adapters' per-action capture (`captureActionSnapshot`). The DOM-walking scripts run in the page via `browser.execute`, so — like `script` — they avoid Node-only APIs.
+
 ### `examples/`
 
 Per-framework demo projects used for manual verification.
 
-- `examples/wdio/` — WebdriverIO with Mocha (default). Run via `pnpm demo:wdio`.
+- `examples/wdio/` — WebdriverIO, split into `cucumber/` and `mocha/` (shared page objects in `pageobjects/`). Run via `pnpm demo:wdio` (Cucumber) or `pnpm demo:wdio:mocha`.
 - `examples/nightwatch/` — Nightwatch (both vanilla and Cucumber). Run via `pnpm demo:nightwatch`.
 - `examples/selenium/` — Selenium with subdirs for `mocha-test/`, `jest-test/`, `cucumber-test/`, `jasmine-test/`, `vitest-test/`. `pnpm demo:selenium` runs mocha; `pnpm --filter @wdio/selenium-devtools example:<runner>` runs the others.
 
@@ -227,7 +233,7 @@ The architecture above is the actual state of the repo. Where it diverges from t
 Notable in-place pieces worth knowing about:
 
 - `replaceCommand` has two semantics across adapters — Selenium mutates the existing entry in place (preserves `_id`/`id` continuity for chained calls); Nightwatch splices and reissues with a new `_id`. Both call the same `core/suite-helpers` factories; the storage strategy stays adapter-specific because the runner integrations differ.
-- `patchNodeAssert` is wired only in `selenium-devtools` (Selenium's primary assertion style is `node:assert`). The shared helper lives in `core/assert-patcher`; Service and Nightwatch can opt in via a one-line call when they need to, but it's not auto-enabled because both communities lean on chai/expect.
+- `patchNodeAssert` (via `core/assert-patcher`) is wired in all three adapters, default-on behind each adapter's `captureAssertions` option (opt out with `captureAssertions: false`), so `node:assert` — and, where the framework exposes assertion hooks, `expect` matchers — surface as trace action rows. Framework matcher libraries differ (Service taps expect-webdriverio's hooks; Nightwatch native `assert`/`verify` and Selenium's `node:assert` surface via their reconcile/patch paths), so the remaining gap is Selenium's jest-style `expect()`.
 - BiDi is auto-attached in Service and Selenium. Nightwatch is opt-in via `bidi: true` and requires `webSocketUrl: true` in capabilities — historically Nightwatch users haven't all enabled BiDi by default.
 - Performance API capture (`CAPTURE_PERFORMANCE_SCRIPT`) is identical across all three adapters; each wires it into its own afterCommand-equivalent path.
 - Output directory for screencast videos and trace files is resolved through `core/resolveAdapterOutputDir` — adapters feed `userConfiguredDir` (WDIO honors `wdio.conf.ts`'s `outputDir`/`rootDir`), `testFilePath` (Selenium/Nightwatch), and `configPath` (Nightwatch), and the helper picks the first writable, non-`node_modules/` candidate.