Selenium and Nightwatch Trace Parity

README.md

@@ -136,8 +136,8 @@ The trace artifact contains:
 - `trace.trace` — NDJSON `context-options` + `before`/`after` action events. When test hooks are available (Mocha's `it()` / Cucumber's `Scenario()`), each test becomes a `Tracing.tracingGroup` span — an open/close `before`/`after` pair with `method: "tracingGroup"` and `params.name` set to the test title. Child actions inside the group carry `parentId` pointing back to the group's `callId`, so timeline viewers render tests as labelled spans wrapping their commands.
 - `trace.network` — HAR-style network entries derived from the existing capture
 - `resources/page@<id>-<ts>.jpeg` — screenshot per user-facing action
-- `resources/elements-page@<id>-<ts>.json` — flat interactable element list extracted by the page-injected scripts in `@wdio/devtools-core/element-scripts`
-- `resources/snapshot-page@<id>-<ts>.txt` — depth-indented accessibility-tree snapshot (AI-friendly)
+- `resources/page@<id>-<ts>-elements.json` — flat interactable element list extracted by the page-injected scripts in `@wdio/devtools-core/element-scripts`
+- `resources/page@<id>-<ts>-snapshot.txt` — depth-indented accessibility-tree snapshot (AI-friendly)
 - `transcript.md` — human/LLM-readable Markdown transcript of the captured actions, with timing, selectors, and value annotations
 
 What counts as a user-facing action is filtered through an allow-list in `@wdio/devtools-core/action-mapping.ts` (`url`, `click`, `setValue`, `sendKeys`, `get`, etc.). Internal commands like `findElement`/`waitUntil`/`executeScript` don't produce trace entries.
@@ -158,7 +158,7 @@ npx show-trace path/to/trace.zip      # in a project that installs an adapter
 The player exposes everything captured in the archive:
 
 - **DOM time-travel** — the browser pane replays the page from the captured DOM **mutation stream**, so scrubbing the playhead reconstructs the live DOM at any point, not just a screenshot.
-- **A11y tab** — the accessibility tree (roles + accessible names) captured for the selected command; hover a row to outline the element in the snapshot, click to copy its locator.
+- **A11y tab** — the accessibility tree (roles + accessible names) captured for the selected command; hover a row to outline the element in the snapshot, click to copy its locator. Locators are generated in the recording runner's own dialect — an element identified by its text is `a*=Logout` under WebdriverIO and `//a[contains(., "Logout")]` under Selenium/Nightwatch, where the panel also names the strategy that resolves it (`By.xpath()`, `useXpath()` / `locateStrategy: 'xpath'`). Every other locator is portable CSS.
 - **Errors tab** — every failing `expect`/assertion and step failure collected in one place, each with a jump-to-source link to the command that threw.
 - **Element overlay (pick-locator)** — labelled, click-to-copy boxes drawn over every element the test interacted with, cross-linked to the A11y rows.
 - **Transcript tab + Copy-for-LLM** — the run's Markdown transcript with a one-click "copy prompt" that bundles it with any failing-command errors, paste-ready for an LLM.

examples/nightwatch/cucumber/features/login.feature

@@ -1,15 +1,19 @@
-Feature: Example site smoke test
+Feature: the-internet login flow
 
-  Mirrors the Nightwatch BDD smoke-test: open a site, wait for the body to be
-  visible, and assert the page title. Runs as a Cucumber scenario so the
-  cross-adapter harness has a nightwatch-cucumber trace fixture.
+  Mirrors the Selenium cucumber example's feature so the cross-adapter harness
+  has a nightwatch-cucumber trace fixture over the same flow. Cucumber exposes
+  per-scenario hooks, so each scenario below is captured as its own test unit.
 
-  Scenario Outline: I can open a site and read its title
-    Given I navigate to "<url>"
-    When the page body becomes visible
-    Then the page title contains "<title>"
+  Scenario: logs in with valid credentials and lands on /secure
+    Given I am on the login page
+    When I enter username "tomsmith" and password "SuperSecretPassword!"
+    And I submit the login form
+    Then I should be on the secure page
+    And I should see a flash message matching "You logged into a secure area"
 
-    Examples:
-      | url                    | title   |
-      | https://example.com    | Example |
-      | https://example.org    | Example |
+  Scenario: rejects invalid username with an error flash
+    Given I am on the login page
+    When I enter username "foobar" and password "barfoo"
+    And I submit the login form
+    Then I should see a flash message matching "Your username is invalid"
+    And I should still be on the login page

examples/nightwatch/cucumber/features/step_definitions/login.steps.js

@@ -1,18 +1,42 @@
-// Step definitions for the example-site smoke scenario.
+// Step definitions for the the-internet login scenarios.
 //
 // Nightwatch's Cucumber integration injects the Nightwatch `browser` onto the
 // World, so steps reach it via `this.browser` — hence regular (non-arrow)
 // functions so `this` binds to the World.
 const { Given, When, Then } = require('@cucumber/cucumber')
 
-Given(/^I navigate to "([^"]*)"$/, async function (url) {
-  await this.browser.url(url)
+const LOGIN_URL = 'https://the-internet.herokuapp.com/login'
+
+Given(/^I am on the login page$/, async function () {
+  await this.browser.url(LOGIN_URL)
+  await this.browser.waitForElementVisible('#username', 5000)
 })
 
-When(/^the page body becomes visible$/, async function () {
-  await this.browser.waitForElementVisible('body', 5000)
+When(
+  /^I enter username "([^"]*)" and password "([^"]*)"$/,
+  async function (username, password) {
+    await this.browser.setValue('#username', username)
+    await this.browser.setValue('#password', password)
+  }
+)
+
+When(/^I submit the login form$/, async function () {
+  await this.browser.click('button[type="submit"]')
 })
 
-Then(/^the page title contains "([^"]*)"$/, async function (title) {
-  await this.browser.assert.titleContains(title)
+Then(/^I should be on the secure page$/, async function () {
+  await this.browser.waitForElementVisible('#flash', 5000)
+  await this.browser.assert.urlContains('/secure')
+})
+
+Then(
+  /^I should see a flash message matching "([^"]*)"$/,
+  async function (text) {
+    await this.browser.waitForElementVisible('#flash', 5000)
+    await this.browser.assert.textContains('#flash', text)
+  }
+)
+
+Then(/^I should still be on the login page$/, async function () {
+  await this.browser.assert.urlContains('/login')
 })

examples/nightwatch/tests/smoke-test.js

@@ -1,10 +1,13 @@
 /**
  * Example + config-sweep harness for @wdio/nightwatch-devtools.
  *
- * Walk the live/trace ladder by editing ONLY the mode/traceGranularity/
- * tracePolicy block in ../nightwatch.conf.cjs. The suite carries a passing
- * pair, an always-failing test (retain-on-failure target), and a flaky
- * fail-then-pass test (on-first-retry / attempt-capture target).
+ * Exercises the same the-internet login flow the WDIO and Selenium examples
+ * use, so a trace captured here is comparable across adapters. Walk the
+ * live/trace ladder by editing ONLY the mode/traceGranularity/tracePolicy
+ * block in ../nightwatch.conf.cjs. The suite carries a passing pair (a login
+ * round-trip and a DOM-mutation test), an always-failing test
+ * (retain-on-failure target), and a flaky fail-then-pass test
+ * (on-first-retry / attempt-capture target).
  *
  * Native asserts (browser.assert.*) double as the assertion-capture check:
  * the passing ones must render green ✓, the failing one red ✗.
@@ -14,35 +17,58 @@
  *   pnpm demo:nightwatch:retry    (rung 5 — adds --retries 1)
  */
 
+const BASE_URL = 'https://the-internet.herokuapp.com'
+
 // Survives Nightwatch's testcase retry so the flaky test fails once, then passes.
 let flakyAttempts = 0
 
 describe('nightwatch-devtools smoke test', function () {
-  it('loads example.com and reads the heading', async function (browser) {
-    await browser.url('https://example.com')
-    await browser.waitForElementVisible('body', 5000)
-    browser.assert.titleContains('Example')
+  // Headless Chrome stops activating clicks after the first test in a session:
+  // a later submit dispatches, nothing navigates, and #flash never appears — so
+  // the always-failing test below timed out on its wait instead of reaching the
+  // assertion it exists to demonstrate.
+  afterEach(async function (browser) {
+    await browser.end()
   })
 
-  it('navigates and reads the page title', async function (browser) {
-    await browser.url('https://example.org')
-    await browser.waitForElementVisible('body', 5000)
-    browser.assert.titleContains('Example')
+  it('logs into the secure area with valid credentials', async function (browser) {
+    console.log('[TEST] logging in with valid credentials')
+    await browser.url(`${BASE_URL}/login`)
+    await browser.waitForElementVisible('#username', 5000)
+    await browser.setValue('#username', 'tomsmith')
+    await browser.setValue('#password', 'SuperSecretPassword!')
+    await browser.click('button[type="submit"]')
+    await browser.waitForElementVisible('#flash', 5000)
+    browser.assert.urlContains('/secure')
+    browser.assert.textContains('#flash', 'You logged into a secure area')
+
+    await browser.waitForElementVisible('a.button', 5000)
+    await browser.click('a.button')
+    await browser.waitForElementVisible('#username', 5000)
+    browser.assert.urlContains('/login')
+    console.log('[TEST] logged back out')
   })
 
-  it('fails on a wrong title (retain-on-failure target)', async function (browser) {
-    await browser.url('https://example.com')
-    await browser.waitForElementVisible('body', 5000)
-    browser.assert.titleContains('This Is Not The Title')
+  it('fails on a wrong flash message (retain-on-failure target)', async function (browser) {
+    console.log('[TEST] submitting invalid credentials')
+    await browser.url(`${BASE_URL}/login`)
+    await browser.waitForElementVisible('#username', 5000)
+
+    await browser.setValue('#username', 'foobar')
+    await browser.setValue('#password', 'barfoo')
+
+    await browser.click('button[type="submit"]')
+    await browser.waitForElementVisible('#flash', 5000)
+    browser.assert.textContains('#flash', 'You logged into a secure area')
   })
 
   it('flaky: fails the first attempt, then passes (retry target)', async function (browser) {
-    await browser.url('https://example.com')
-    await browser.waitForElementVisible('body', 5000)
+    await browser.url(`${BASE_URL}/login`)
+    await browser.waitForElementVisible('#username', 5000)
     flakyAttempts += 1
     if (flakyAttempts === 1) {
       throw new Error('intentional first-attempt failure — should retry')
     }
-    browser.assert.titleContains('Example')
+    browser.assert.titleContains('The Internet')
   })
 })

examples/selenium/cucumber-test/features/support/setup.js

@@ -6,8 +6,8 @@
 
 import { DevTools } from '@wdio/selenium-devtools'
 
-// mode defaults to 'live' (the demo default); the verification harness sets
-// DEVTOOLS_MODE=trace to produce a golden fixture from this same example.
+// mode defaults to 'live' (the demo default); set DEVTOOLS_MODE=trace to
+// produce a trace.zip from this same example.
 DevTools.configure({
   mode: process.env.DEVTOOLS_MODE === 'trace' ? 'trace' : 'live',
   screencast: { enabled: true, quality: 70, maxWidth: 1280, maxHeight: 720 },

examples/wdio/mocha/specs/login.e2e.ts

@@ -1,9 +1,17 @@
-import { expect } from '@wdio/globals'
+import { browser, expect } from '@wdio/globals'
 
 import LoginPage from '../../pageobjects/login.page.js'
 import SecurePage from '../../pageobjects/secure.page.js'
 
 describe('Login', () => {
+  // Headless Chrome stops activating clicks after the first test in a session:
+  // the second test's submit dispatches, nothing navigates, and #flash never
+  // appears. Reproduces with the devtools service removed and survives
+  // deleteCookies(), so a fresh session is the only reliable reset.
+  beforeEach(async () => {
+    await browser.reloadSession()
+  })
+
   it('logs into the secure area with valid credentials', async () => {
     console.log('[TEST] logging in with valid credentials')
     await LoginPage.open()

examples/wdio/mocha/wdio.trace.conf.ts

@@ -1,7 +1,8 @@
-// Trace-mode variant of wdio.conf.ts, used by the verification harness
-// (`pnpm fixtures:regen`) to produce a deterministic golden trace.zip. Same
+// Trace-mode variant of wdio.conf.ts, for manually verifying trace output. Same
 // capabilities and specs as the live config; session granularity writes one zip
-// per run. Kept separate so the demo config's live default stays untouched.
+// per run. Every knob reads from the environment so one config covers the
+// live→trace→per-test→retain→retry ladder. Kept separate so the demo config's
+// live default stays untouched.
 export const config: WebdriverIO.Config = {
   runner: 'local',
   specs: ['./specs/**/*.e2e.ts'],
@@ -46,7 +47,7 @@ export const config: WebdriverIO.Config = {
           | 'on-first-retry'
           | 'on-all-retries'
           | 'retain-on-failure-and-retries',
-        // Always emit the manifest so scenario-parity can read the artifact set.
+        // Always emit the manifest so the artifact set is inspectable per run.
         emitArtifactsManifest: true
       }
     ]

packages/app/src/components/browser/element-overlay.ts

@@ -3,14 +3,17 @@
 // boxes inherit the iframe's scale transform (no manual coordinate math). Kept
 // out of snapshot.ts so that file stays focused on capture/replay.
 
+import { isXPathLocator } from '@wdio/devtools-shared'
+
 const OVERLAY_CLASS = '__wdio-el-overlay__'
 
 export interface OverlayHandlers {
   /** Click a box — copy its locator + jump to the A11y row (selector + name). */
   onPick: (selector: string, label: string) => void
   /** Hover a box — reveal the matching a11y-tree row (by selector, else by the
    *  element's accessible name for locators the serializer captured a different
-   *  way, e.g. the test's `button[type=submit]` vs the tree's `button*=Login`). */
+   *  way, e.g. the test's `button[type=submit]` vs the tree's
+   *  `//button[contains(., "Login")]`). */
   onHover?: (selector: string, label: string) => void
   onLeave?: () => void
 }
@@ -37,15 +40,45 @@ function elementLabel(el: Element): string {
   return el.getAttribute('placeholder')?.trim() ?? ''
 }
 
-/** Resolve a test locator in the replayed document: native CSS first, then the
- *  WebdriverIO text-selectors querySelector can't parse (`tag=Exact`,
- *  `tag*=Contains`, and their tag-less forms). Returns the deepest text match
- *  so a container that merely encloses the text isn't boxed over the real
- *  element. Returns null when nothing matches (locator absent on this page). */
+/** `XPathResult.FIRST_ORDERED_NODE_TYPE`, read as a literal so the resolver
+ *  doesn't depend on the constant being reachable from this realm. */
+const XPATH_FIRST_ORDERED_NODE = 9
+
+/** First node an XPath locator matches, as the frameworks' own `By.xpath` /
+ *  `useXpath` do. Element-only: an expression selecting an attribute or text
+ *  node has nothing to draw a box over. */
+function resolveXPath(doc: Document, expression: string): Element | null {
+  try {
+    const node = doc.evaluate(
+      expression,
+      doc,
+      null,
+      XPATH_FIRST_ORDERED_NODE,
+      null
+    ).singleNodeValue
+    // nodeType, not `instanceof Element`: the replayed nodes belong to the
+    // iframe's realm, where the parent document's constructors don't match.
+    return node?.nodeType === 1 ? (node as Element) : null
+  } catch {
+    // Malformed expression, or a document with no XPath engine.
+    return null
+  }
+}
+
+/** Resolve a test locator in the replayed document: XPath first, then native
+ *  CSS, then the WebdriverIO text-selectors querySelector can't parse
+ *  (`tag=Exact`, `tag*=Contains`, and their tag-less forms) — those still arrive
+ *  from hand-written WDIO tests and from traces recorded before the capture
+ *  became portable. Returns the deepest text match so a container that merely
+ *  encloses the text isn't boxed over the real element. Returns null when
+ *  nothing matches (locator absent on this page). */
 export function resolveTestSelector(
   doc: Document,
   selector: string
 ): Element | null {
+  if (isXPathLocator(selector)) {
+    return resolveXPath(doc, selector)
+  }
   try {
     const css = doc.querySelector(selector)
     if (css) {

packages/app/src/components/browser/snapshot.ts

@@ -16,11 +16,11 @@ import { booleanAttributeOn, isBooleanAttribute } from './boolean-attribute.js'
 import { type ComponentChildren, h, render, type VNode } from 'preact'
 import { customElement, query } from 'lit/decorators.js'
 import { transform } from './vnode-transform.js'
-import type { SimplifiedVNode } from '../../../../script/types'
+import type { SimplifiedVNode } from '@wdio/devtools-script/types'
 // Type-only, like the `script/types` import above: the collector owns the
 // characterData wire shape (parent ref + child index), so the replay reads it
 // from the same declaration that produces it.
-import type { TextMutation } from '../../../../script/src/mutations.js'
+import type { TextMutation } from '@wdio/devtools-script/mutations.js'
 import type { CommandLog } from '@wdio/devtools-shared'
 
 import {
@@ -637,8 +637,8 @@ export class DevtoolsBrowser extends Element {
 
   /** Outline the element for an a11y-tree locator. Resolved through the same
    *  resolver the forward direction (the element overlay) uses, because the tree
-   *  captures interactive elements as WDIO text locators (`button*=Login`) that
-   *  querySelector cannot parse. */
+   *  captures text-matched elements as XPath (`//button[contains(., "Login")]`)
+   *  that querySelector cannot parse. */
   #highlightBySelector = (ev: Event) => {
     const detail = (ev as CustomEvent<{ selector?: string } | null>).detail
     const docEl = this.iframe?.contentDocument