Running & debugging tests

When a test fails on a device you can't see, you need a record of what happened. Taqwright captures two kinds — a per-action trace and a full-run video — writes them under the output directory, and hands everything to Playwright's reporters.

Tracing — post-mortem debugging

Set trace in a project's use block to capture a per-action screenshot + page-source timeline of every test run. The result is a self-contained trace.html file under the test's output directory, attached to the Playwright HTML report as taqwright-trace.

Copy{
  name: 'android',
  use: {
    // ... rest of your use options
    trace: 'on-failure',
  },
}

What ends up in trace.html:

• Per-action timeline — each click / fill / assertVisible / etc. gets a row, in execution order.
• Post-state screenshot for every step (click thumbnail to zoom).
• Page-source XML snapshot at that moment.
• Per-step timing + error message highlighted on the failing step.

How it works under the hood: the mobile fixture wraps the Mobile + Locator instances in a Proxy when trace !== 'off'. Chain methods (filter / first / nth / locator / and / or) pass through untraced — only the terminal action (click, fill, etc.) records an entry. So mobile.getByType('Cell').nth(2).click() produces one row in the trace, not three.

For interactive debugging during development (instead of post-mortem), drop await mobile.pause() in a test — it hands the in-flight WebDriver session off to the inspector in your browser. See Generating tests → Debug a live test.

Screen recording — full-run video

Set video in a project's use block to capture an Appium on-device screen recording of every test run. The result is a screen.mp4 under the test's output directory, attached to the Playwright HTML report as taqwright-video.

Copy{
  name: 'android',
  use: {
    // ... rest of your use options
    video: 'on-failure',
  },
}

Run & verify

With video set, just run the project — recording is automatic. The .mp4 is written when the test finishes (teardown), so let the run complete.

Copy# run the project (emulator/simulator up; Appium auto-starts if configured)
npx taqwright test --project=android

# open the HTML report, then: pick the test → Attachments → taqwright-video
npx taqwright show-report

In the report, open the test and expand Attachments — click taqwright-video to play the recording inline (alongside taqwright-trace if tracing is also on). To skip the report and grab the file directly, it's screen.mp4 in the test's output folder:

Copyfind test-results -name screen.mp4 -exec open {} \;

Expectations: with 'on' you get an .mp4 every run (pass or fail); with 'on-failure' only failing tests keep one. The file lives under outputDir (gitignored by the taqwright init scaffold), so it isn't committed. If you don't see the attachment, confirm the run actually reached teardown and that the project's use.video isn't 'off'.

How it works under the hood: the mobile fixture calls Appium's startRecordingScreen before the test body and always stopRecordingScreen at teardown (so the device recorder can't leak between tests). The base64 payload is written to screen.mp4 and attached only when the run's outcome matches the selected mode. video and trace are independent — enable both and you get a taqwright-video MP4 plus a taqwright-trace HTML timeline for the same run.

Output directory & artifacts

outputDir is the root directory for everything a test run produces on disk — the trace.html from tracing, any testInfo.attach(...) files, and anything a test writes via testInfo.outputPath(...). It's a top-level defineConfig option, overridable per project.

Copyexport default defineConfig({
  testDir: './tests',
  outputDir: './test-results',     // top-level default for every project

  projects: [
    {
      name: 'android',
      outputDir: './test-results/android',   // optional per-project override
      use: { /* ... */ },
    },
  ],
});

• Per-test subfolder — each test gets its own directory under outputDir, named <file>-<title>-<project>/. Two tests never clobber each other's artifacts.
• Path resolution — relative paths are resolved against the taqwright.config.ts location, not the shell's cwd, so the runner works the same whether launched from the project root or a subfolder.
• Default — if you omit outputDir, it falls back to Playwright's default test-results/ in the config directory.
• Reading it from a test — testInfo is the second argument to the test function: test('name', async ({ mobile }, testInfo) => { ... }). Use testInfo.outputDir or testInfo.outputPath('file.png') to write your own artifacts into the per-test folder.

Reports

taqwright forwards the reporter option straight to Playwright. Reporters are run-level (there is no per-project reporter), and you stack several at once with the array form. Need a bespoke format? See Custom reporters.

Copyexport default defineConfig({
  reporter: [
    ['list'],                                            // ONE console reporter only
    ['html',  { open: 'never', outputFolder: 'reports/html' }],
    ['json',  { outputFile:  'reports/results.json' }],
    ['junit', { outputFile:  'reports/results.xml' }],
    ...(process.env.CI ? [['github'] as [string]] : []), // CI-only annotations
    ['blob',  { outputDir:   'reports/blob' }],
  ],
});

• One console reporter. list / line / dot all write to stdout — stacking two interleaves the output into noise. Pick one; the file reporters coexist cleanly.
• Give json / junit an outputFile — without it they print to stdout and collide with the console reporter.
• github is CI-only. It emits GitHub Actions ::notice:: / ::error:: annotations; locally it just prints a hardcoded Playwright summary line. Gate it on process.env.CI as shown.

Viewing the HTML report

After a run, serve it with:

Copynpx taqwright show-report reports/html
# --host <host> (default localhost) · --port <port> (default 9323)

taqwright prints this exact (taqwright-branded) command at the end of an interactive run. show-report also serves a blob .zip directly.

Per-project report directories

Because reporters are run-level, one run merges every project into a single report. For an isolated report per project, run once per project and let the config derive reporter paths from an env var — taqwright.config.ts is just TypeScript, so it can read process.env:

Copyconst proj = process.env.TW_REPORT_PROJECT;
const base = proj ? `reports/${proj}` : 'reports/_all';

export default defineConfig({
  outputDir: './test-results',                  // sibling of reports/ — no clash
  reporter: [
    ['list'],
    ['html',  { open: 'never', outputFolder: `${base}/html-report` }],
    ['json',  { outputFile:  `${base}/results.json` }],
    ['junit', { outputFile:  `${base}/results.xml` }],
    ['blob',  { outputDir:   `${base}/blob-report` }],
  ],
  // ...
});

Copy{
  "scripts": {
    "test:android": "TW_REPORT_PROJECT=android taqwright test --project=android",
    "test:ios":     "TW_REPORT_PROJECT=ios taqwright test --project=ios",
    "report:android": "taqwright show-report reports/android/html-report",
    "report:ios":     "taqwright show-report reports/ios/html-report"
  }
}

Each invocation writes only under its own reports/<project>/ — runs never clobber each other. A plain taqwright test (all projects, one run, env unset) falls back to reports/_all/.