Trace viewer

A taqwright trace is a recording of everything a test did, action by action, that you can replay afterwards to see exactly what happened on the device. Each action is captured with a screenshot of the screen just after it ran, the page-source XML at that moment, its timing and arguments, and any error. It is the fastest way to debug a failure you cannot reproduce locally.

Not a Playwright trace

The taqwright trace is a self-contained trace.html file you open in a browser. It is not a Playwright .zip trace, so there is no show-trace command and no trace.playwright.dev. Open the HTML directly, or from the HTML report (below).

Record a trace

Tracing is off by default. Turn it on with the trace option in your use block, at the top level or per project (see Configuration):

taqwright.config.ts

import { defineConfig, Platform } from '@taqwright/taqwright';

export default defineConfig({
  projects: [
    {
      name: 'android',
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
        trace: 'on-failure',
      },
    },
  ],
});

Mode	Behaviour
'off'	No tracing (default). Zero overhead.
'on'	Record every test and always write the trace.html.
'on-failure'	Record every test, but only keep the trace.html when the test fails.
'retain-on-failure'	Alias of 'on-failure' on mobile.

Recording adds roughly 100 to 300 ms per action (it captures a screenshot and the page source each time), so 'on-failure' is the usual choice: you pay the cost on every run but only keep artifacts for the tests that actually failed. See the Tracing section in Running and debugging for more on the overhead.

Open the trace

The trace is attached to the HTML report. Open the report, then open the test and click the taqwright-trace attachment:

npx taqwright show-report

It is also a normal file on disk, written under the test's output folder. Because the HTML is fully self-contained, you can open it directly in any browser:

open test-results/<test-name>/trace.html

See Command line for show-report.

What the viewer shows

The trace player gives you:

• a timeline of the test's actions, clickable to seek, with failed actions highlighted;
• the device screenshot captured just after the action at the playhead;
• the action's name, arguments, and error (if it threw);
• the page-source XML snapshot taken with the action, so you can inspect the UI tree;
• playback controls (play, step, and speed) to scrub through the run;
• a network panel when network capture is enabled, with the HAR embedded inline and time-correlated to the actions.

What is not in the trace

• Console logs are not captured (there is no DOM console on a device).
• Video is a separate artifact (screen.mp4), recorded by the video option rather than the trace. See Screen recording.
• Only terminal actions are recorded. Chained locator steps (getBy*().filter().nth()) pass through untraced; the action at the end of the chain is the one that shows up.

On CI

Set trace: 'on-failure' (optionally gated on process.env.CI) so every test is traced but only failing tests keep their trace.html. The trace rides along inside the HTML report, so it survives a blob reporter plus merge-reports flow and is there to open when a CI run goes red.

taqwright.config.ts

use: {
  // ...
  trace: process.env.CI ? 'on-failure' : 'off',
},