Merge pull request #523 from webdriverio/feat/501-open-whole-run

Open several trace zips or a whole run in the player

Author: vishnuv688

.changeset/open-whole-run.md

@@ -0,0 +1,6 @@
+---
+'@wdio/devtools-app': minor
+'@wdio/devtools-backend': minor
+---
+
+The trace player opens several traces at once. `show-trace` accepts several zips or a folder (`npx show-trace test-results/`), and the hosted player takes several zips through its Open button, or zips and folders dropped on the page. The player then lists every trace beside the timeline, one row per test with its outcome, failures first and then in run order, and plays the one picked without reloading. With `traceGranularity: 'test'` a run is a folder of per-test zips, so the whole run opens in one go. A zip records no test state, so the outcome is read from the trace: failed when an action or step failed, passed when it holds actions and none failed, unknown when it holds none. Files in the folder that are not zips are skipped, and a zip that cannot be opened is listed with the reason without stopping the rest. Opening a single zip works exactly as before.

CLAUDE.md

@@ -105,7 +105,7 @@ They import from `shared` and `core`, never from each other. They aren't importe
 
 ### Backend and app are framework-agnostic
 
-`backend` and `app` import from `shared` (for contracts) and from each other via the WS/HTTP boundary. Neither imports an adapter package. `backend` also imports `trace`, to write and read zips; `app` imports only `trace`'s reader, which the hosted player (`trace.webdriver.io`, built with `pnpm player:hosted`, deployed by Vercel from `vercel.json`) runs in the browser to open a dropped zip with no backend at all. It runs the reader in a module Web Worker loaded from the player's own origin (`app/src/controller/trace-parse.worker.ts`, which `script-src 'self'` already admits), so the tab stays responsive and the landing screen names the phase the open is on; the live build never references the worker. That build is `HOSTED_PLAYER` in `app/src/controller/constants.ts`; it never writes the trace to browser storage, and `vercel.json` is also what `vite preview` serves, so its CSP is checked locally before it ships.
+`backend` and `app` import from `shared` (for contracts) and from each other via the WS/HTTP boundary. Neither imports an adapter package. `backend` also imports `trace`, to write and read zips; `app` imports only `trace`'s reader, which the hosted player (`trace.webdriver.io`, built with `pnpm player:hosted`, deployed by Vercel from `vercel.json`) runs in the browser to open a dropped zip with no backend at all. It runs the reader in a module Web Worker loaded from the player's own origin (`app/src/controller/trace-parse.worker.ts`, which `script-src 'self'` already admits), so the tab stays responsive and the landing screen names the phase the open is on; the live build never references the worker. That build is `HOSTED_PLAYER` in `app/src/controller/constants.ts`; it never writes the trace to browser storage, and `vercel.json` is also what `vite preview` serves, so its CSP is checked locally before it ships. Several zips or a folder open as a run (`controller/trace-run.ts`), in the hosted player and in `show-trace`, which lists them at `TRACE_API.run` for the app to read: each zip is parsed once, one at a time, and its payload kept for when its row is picked. A zip records no test state, so a row's outcome is read from its rows (`utils/trace-summary.ts`: a failed action or step means failed, actions with none failed mean passed, no actions mean unknown); a jest `expect` that records no row can therefore fail a test whose trace reads as passed. Keeping every payload costs memory in proportion to the run; a reader that reads entries on demand would shrink each payload, which is why the run holds the reader's own payload rather than a cache of its own.
 
 Framework-specific behavior in the backend is contained in two files: `runner.ts` and `framework-filters.ts`. Both branch on a typed `TestRunnerId` from shared, never on a magic string. The `framework-filters` dispatch is a `switch` over `TestRunnerId` (not a table lookup) so CodeQL's `unvalidated-dynamic-method-call` query trusts the call site.
 

README.md

@@ -262,7 +262,16 @@ The player exposes everything captured in the archive:
 
 The `show-trace` bin is exposed by each JavaScript adapter (`@wdio/devtools-service`, `@wdio/nightwatch-devtools`, `@wdio/selenium-devtools`), so `pnpm show-trace <zip>` / `npx show-trace <zip>` work in any project that installs one — no extra dependency.
 
-**Hosted player: [trace.webdriver.io](https://trace.webdriver.io).** The same player as a web page, for opening a trace without installing anything: drop a `.zip` on the page or pick one. The archive is parsed in the browser tab and never uploaded, which matters because a trace records everything the run showed or typed. Run controls are absent, as in `show-trace`. A replayed page still loads its own stylesheets and images from the site under test, as it does in `show-trace`; from an `https` page the browser blocks the `http` ones, so a trace of an `http` site can render unstyled there and fully in `show-trace`. To try the hosted build locally:
+**A whole run at once.** With `traceGranularity: 'test'` every test writes its own `trace.zip`, so a run is a folder of them. Give `show-trace` the folder, or several zips, and the player lists every trace beside the timeline, one row per test with its outcome, failures first and then in the order they ran; picking a row plays that trace without reloading (`↑`/`↓` move between rows, `Enter` opens one). The hosted player does the same for several zips picked with its one Open button, or for a folder dropped on the page (a browser's file dialog picks files or folders, never both).
+
+```sh
+pnpm show-trace test-results/                        # every zip under the folder
+pnpm show-trace a/trace.zip b/trace.zip              # several zips
+```
+
+Each zip is read once, as the list fills in, and kept for when it is picked. Anything in the folder that is not a `.zip` (screenshots, videos, the artifacts manifest) is skipped; a zip that cannot be opened stays in the list with the reason, and the rest open normally. A zip records no test state, so the outcome is read from the trace itself: **failed** when an action or step in it failed, **passed** when it holds actions and none failed, **unknown** when it holds none. An assertion library that records no row (a jest `expect`, chai) can fail a test whose trace still reads as passed. One zip opens exactly as before, with no list.
+
+**Hosted player: [trace.webdriver.io](https://trace.webdriver.io).** The same player as a web page, for opening a trace without installing anything: pick one or several `.zip` files, or drop them or a folder of them on the page. The archive is parsed in the browser tab and never uploaded, which matters because a trace records everything the run showed or typed. Run controls are absent, as in `show-trace`. A replayed page still loads its own stylesheets and images from the site under test, as it does in `show-trace`; from an `https` page the browser blocks the `http` ones, so a trace of an `http` site can render unstyled there and fully in `show-trace`. To try the hosted build locally:
 
 ```sh
 pnpm player:hosted   # builds it and serves it at http://localhost:4173 under the production headers
@@ -534,6 +543,8 @@ With `mode: 'trace'` no UI opens — the run writes a portable `trace.zip` under
 pnpm show-trace test-results/trace-<sessionId>.zip
 # or from a project that installs an adapter:
 npx show-trace <path-to-trace.zip>
+# a folder of per-test zips opens as a list of tests:
+npx show-trace test-results/
 ```
 
 <p align="center">

packages/app/src/app.ts

@@ -6,10 +6,12 @@ import { TraceType, type CommandLog } from '@wdio/devtools-shared'
 import { Element } from '@core/element'
 import { DataManagerController } from './controller/DataManager.js'
 import { TraceOpenController } from './controller/trace-open.js'
+import { TraceRunController } from './controller/trace-run.js'
 import { KeyboardController, KBD } from './controller/keyboard.js'
 import { DragController, Direction } from './utils/DragController.js'
 import {
   HOSTED_PLAYER,
+  TRACE_RUN_SELECT_EVENT,
   SIDEBAR_MIN_WIDTH,
   SIDEBAR_DEFAULT_WIDTH
 } from './controller/constants.js'
@@ -26,6 +28,8 @@ import './components/sidebar.js'
 import './components/workbench.js'
 import './components/onboarding/start.js'
 import './components/onboarding/open-trace.js'
+import './components/trace-run-list.js'
+import './components/placeholder.js'
 import './components/workbench/compare.js'
 import './components/shortcuts-overlay.js'
 
@@ -40,16 +44,25 @@ onThemeChange(applyDarkMode)
 @customElement('wdio-devtools')
 export class WebdriverIODevtoolsApplication extends Element {
   dataManager = new DataManagerController(this)
+  #traceRun = new TraceRunController(this, (data) =>
+    this.dataManager.loadPlayerData(data)
+  )
   #traceOpen = HOSTED_PLAYER
-    ? new TraceOpenController(this, (file, onPhase) =>
-        this.dataManager.openTraceArchive(file, onPhase)
-      )
+    ? new TraceOpenController(this, {
+        one: async (bytes, onPhase) => {
+          await this.dataManager.openTraceArchive(bytes, onPhase)
+          this.#traceRun.clear()
+        },
+        many: (sources) => void this.#traceRun.open(sources)
+      })
     : undefined
 
   @state() showShortcuts = false
 
   constructor() {
     super()
+    this.dataManager.onServedRun = (sources) =>
+      void this.#traceRun.open(sources)
     // Global keyboard shortcuts — a side-effect controller (hooks window
     // keydown via addController); active in both the player and live dashboard.
     new KeyboardController(this, {
@@ -117,6 +130,7 @@ export class WebdriverIODevtoolsApplication extends Element {
     // or a popout — and the Compare tab, which keys on it, kept showing the
     // previously selected test's baseline after clicking a different test.
     this.addEventListener('app-test-select', this.#onTestSelect)
+    this.addEventListener(TRACE_RUN_SELECT_EVENT, this.#onTraceRunSelect)
     window.addEventListener('show-command', this.#onShowCommand)
     window.addEventListener(KBD.step, this.#onKbdStep)
     window.addEventListener(KBD.jump, this.#onKbdJump)
@@ -134,6 +148,7 @@ export class WebdriverIODevtoolsApplication extends Element {
   disconnectedCallback(): void {
     super.disconnectedCallback()
     this.removeEventListener('app-test-select', this.#onTestSelect)
+    this.removeEventListener(TRACE_RUN_SELECT_EVENT, this.#onTraceRunSelect)
     window.removeEventListener('show-command', this.#onShowCommand)
     window.removeEventListener(KBD.step, this.#onKbdStep)
     window.removeEventListener(KBD.jump, this.#onKbdJump)
@@ -143,6 +158,10 @@ export class WebdriverIODevtoolsApplication extends Element {
     this.dataManager.setSelectedTestUid((event as CustomEvent<string>).detail)
   }
 
+  #onTraceRunSelect = (event: CustomEvent<number>): void => {
+    this.#traceRun.select(event.detail)
+  }
+
   #onShowCommand = (event: Event): void => {
     const command = (event as CustomEvent<{ command?: CommandLog }>).detail
       ?.command
@@ -250,15 +269,61 @@ export class WebdriverIODevtoolsApplication extends Element {
     </div>`
   }
 
+  #runPane() {
+    const run = this.#traceRun
+    if (run.selectedId !== undefined) {
+      return html`<wdio-devtools-workbench
+        class="basis-auto"
+        .playerMode="${true}"
+      ></wdio-devtools-workbench>`
+    }
+    if (run.loading) {
+      return html`<wdio-devtools-placeholder
+        class="flex-1"
+      ></wdio-devtools-placeholder>`
+    }
+    return html`<wdio-devtools-placeholder
+      class="flex-1"
+      heading="None of these traces could be opened"
+      description="Each row says why."
+    ></wdio-devtools-placeholder>`
+  }
+
+  // Several traces opened together: their list where a live run's tree would be.
+  #runContent() {
+    return html`
+      <section
+        data-resizer-window
+        class="flex h-[calc(100%-40px)] w-full relative"
+      >
+        <wdio-devtools-trace-run-list
+          style="${this.#drag?.getPosition()}"
+          .entries="${this.#traceRun.ordered}"
+          .selectedId="${this.#traceRun.selectedId}"
+        ></wdio-devtools-trace-run-list>
+        ${this.#drag.getSlider('z-10 h-full')} ${this.#runPane()}
+        ${this.#traceOpenBanner()}
+      </section>
+    `
+  }
+
   #mainContent() {
     const traceOpen = this.#traceOpen
-    // Once a trace is loaded, a failed open keeps it and reports in a banner.
-    if (traceOpen && (traceOpen.opening || !this.dataManager.hasConnection)) {
-      return html`<wdio-devtools-open-trace
-        .busy="${traceOpen.opening}"
-        .phase="${traceOpen.phase}"
-        .error="${traceOpen.error}"
+    const landing = (busy: boolean) =>
+      html`<wdio-devtools-open-trace
+        .busy="${busy}"
+        .phase="${traceOpen?.phase}"
+        .error="${traceOpen?.error}"
       ></wdio-devtools-open-trace>`
+    if (traceOpen?.opening) {
+      return landing(true)
+    }
+    if (this.#traceRun.active) {
+      return this.#runContent()
+    }
+    // Once a trace is loaded, a failed open keeps it and reports in a banner.
+    if (traceOpen && !this.dataManager.hasConnection) {
+      return landing(false)
     }
     if (!this.dataManager.hasConnection) {
       return html`<wdio-devtools-start></wdio-devtools-start>`

packages/app/src/components/header.ts

@@ -15,7 +15,7 @@ import {
 } from '../controller/theme.js'
 import { HOSTED_PLAYER } from '../controller/constants.js'
 import { TRACE_FILE_ACCEPT } from '../controller/constants.js'
-import { announceTraceFile, takePickedFile } from '../utils/trace-file.js'
+import { announceTraceSources, takePickedSources } from '../utils/trace-file.js'
 
 @customElement('wdio-devtools-header')
 export class DevtoolsHeader extends Element {
@@ -115,26 +115,24 @@ export class DevtoolsHeader extends Element {
     return html`
       <button
         class="p-2"
-        title="Open another trace.zip"
-        aria-label="Open another trace.zip"
+        title="Open trace .zip files, or drop a folder of them on the page"
+        aria-label="Open trace .zip files"
         @click="${() => this.traceInput?.click()}"
       >
         <icon-mdi-upload></icon-mdi-upload>
       </button>
       <input
         type="file"
         accept="${TRACE_FILE_ACCEPT}"
+        multiple
         hidden
-        @change="${this.#onTracePicked}"
+        @change="${() => this.#onTracePicked(this.traceInput)}"
       />
     `
   }
 
-  #onTracePicked() {
-    const file = takePickedFile(this.traceInput)
-    if (file) {
-      announceTraceFile(this, file)
-    }
+  #onTracePicked(input?: HTMLInputElement) {
+    announceTraceSources(this, takePickedSources(input))
   }
 
   #switchMode() {

packages/app/src/components/onboarding/open-trace.ts

@@ -7,9 +7,13 @@ import {
   TRACE_OPEN_PHASE_LABEL
 } from '../../controller/constants.js'
 import type { TraceOpenPhase } from '../../controller/trace-parse-protocol.js'
-import { announceTraceFile, takePickedFile } from '../../utils/trace-file.js'
+import {
+  announceTraceSources,
+  takePickedSources
+} from '../../utils/trace-file.js'
+import type { TraceSource } from '../../utils/trace-sources.js'
 
-/** Landing screen of the hosted trace player: pick or drop a trace.zip. */
+/** Landing screen of the hosted trace player: pick or drop trace zips or a folder of them. */
 @customElement('wdio-devtools-open-trace')
 export class DevtoolsOpenTrace extends Element {
   @property({ type: Boolean }) busy = false
@@ -109,9 +113,9 @@ export class DevtoolsOpenTrace extends Element {
     `
   ]
 
-  #open(file: File | undefined) {
-    if (file && !this.busy) {
-      announceTraceFile(this, file)
+  #open(sources: readonly TraceSource[]) {
+    if (!this.busy) {
+      announceTraceSources(this, sources)
     }
   }
 
@@ -128,25 +132,39 @@ export class DevtoolsOpenTrace extends Element {
     }
   }
 
+  // Left to bubble: the app opens a drop anywhere on the window, this one included.
   #onDrop(event: DragEvent) {
     event.preventDefault()
-    // The app also opens files dropped anywhere on the window.
-    event.stopPropagation()
     this.dragging = false
-    this.#open(event.dataTransfer?.files[0])
   }
 
-  #onPick() {
-    this.#open(takePickedFile(this.input))
+  #onPick(input?: HTMLInputElement) {
+    this.#open(takePickedSources(input))
   }
 
   #status(): string {
     if (!this.busy) {
-      return 'Drop a trace.zip here'
+      return 'Drop trace .zip files or a folder of them here'
     }
     return this.phase ? TRACE_OPEN_PHASE_LABEL[this.phase] : 'Opening trace…'
   }
 
+  // A picker takes files or folders, never both, so folders come in by drop.
+  #pickers() {
+    return html`
+      <button ?disabled="${this.busy}" @click="${() => this.input?.click()}">
+        Open traces
+      </button>
+      <input
+        type="file"
+        accept="${TRACE_FILE_ACCEPT}"
+        multiple
+        hidden
+        @change="${() => this.#onPick(this.input)}"
+      />
+    `
+  }
+
   render() {
     return html`
       <div
@@ -160,29 +178,18 @@ export class DevtoolsOpenTrace extends Element {
         <div class="drop ${this.dragging ? 'dragging' : ''}">
           <p class="text-lg" role="status">${this.#status()}</p>
           ${this.busy ? html`<div class="progress"></div>` : nothing}
-          <button
-            ?disabled="${this.busy}"
-            @click="${() => this.input?.click()}"
-          >
-            Select file
-          </button>
-          <input
-            type="file"
-            accept="${TRACE_FILE_ACCEPT}"
-            hidden
-            @change="${this.#onPick}"
-          />
+          ${this.#pickers()}
         </div>
         ${
           this.error
             ? html`<p class="error" role="alert">${this.error}</p>`
             : nothing
         }
         <p class="muted text-sm max-w-xl text-center">
-          The trace is opened in this browser tab and never leaves your machine.
-          To open one offline, run
-          <code>npx show-trace trace.zip</code> in a project with WebdriverIO
-          DevTools installed.
+          Traces are opened in this browser tab and never leave your machine. To
+          open them offline, run
+          <code>npx show-trace trace.zip</code> (or a folder of traces) in a
+          project with WebdriverIO DevTools installed.
         </p>
       </div>
     `

packages/app/src/components/sidebar/state-icon.ts

@@ -0,0 +1,56 @@
+import { css, html, type TemplateResult } from 'lit'
+
+import '~icons/mdi/check.js'
+import '~icons/mdi/close.js'
+import '~icons/mdi/debug-step-over.js'
+import '~icons/mdi/circle-outline.js'
+import '~icons/mdi/alert-circle-outline.js'
+
+/** What a row's status icon can say; `unreadable` is a trace the player could not open. */
+export type StateIconKind =
+  'running' | 'passed' | 'failed' | 'skipped' | 'idle' | 'unreadable'
+
+/** For any host that renders a `running` icon. */
+export const STATE_ICON_STYLES = css`
+  .run-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: var(--vscode-charts-blue);
+    animation: run-pulse 1.5s ease-in-out infinite;
+  }
+  @keyframes run-pulse {
+    0%,
+    100% {
+      opacity: 1;
+      transform: scale(1);
+    }
+    50% {
+      opacity: 0.4;
+      transform: scale(0.7);
+    }
+  }
+`
+
+const ICONS: Record<StateIconKind, TemplateResult> = {
+  running: html`<span class="run-dot"></span>`,
+  passed: html`<icon-mdi-check class="text-chartsGreen"></icon-mdi-check>`,
+  failed: html`<icon-mdi-close class="text-chartsRed"></icon-mdi-close>`,
+  skipped: html`<icon-mdi-debug-step-over
+    class="text-chartsYellow"
+  ></icon-mdi-debug-step-over>`,
+  idle: html`<icon-mdi-circle-outline
+    class="text-disabledForeground"
+  ></icon-mdi-circle-outline>`,
+  unreadable: html`<icon-mdi-alert-circle-outline
+    class="text-chartsRed"
+  ></icon-mdi-alert-circle-outline>`
+}
+
+/** Centred on the row's first line, so it lines up with the row's buttons. */
+export function stateIcon(kind: StateIconKind): TemplateResult {
+  return html`<span
+    class="w-4 h-[18px] shrink-0 self-center grid place-items-center"
+    >${ICONS[kind]}</span
+  >`
+}