Diagnose problems running flows

Use qawolf doctor to check your environment, find missing dependencies, and read the CLI’s log file.

When a flow run fails for reasons that aren’t in the flow itself — a missing browser, an Android SDK that isn’t on the path, a Node.js version mismatch — qawolf doctor is the first thing to run.

Run the diagnostics

1. From the project root, run:

   qawolf doctor
   

   The CLI checks:

   • the CLI version
   • the Node.js version against the required minimum
   • the Playwright installation, if any flow targets a browser
   • browser availability for each target the project uses
   • the Android SDK, if any flow targets Android
2. Read the output. Each check reports a pass, a warning, or a failure, with a remediation hint when it fails.

Check every platform

qawolf doctor only checks the platforms your project actually uses. Pass --all to run every check, including platforms not used by the current project:

qawolf doctor --all

This is useful when copying the project to a new machine and you want a single command that surfaces every missing dependency.

Read the log file

The CLI writes structured logs to the platform’s user cache directory:

• macOS: ~/Library/Caches/qawolf/qawolf.log
• Linux: $XDG_CACHE_HOME/qawolf/qawolf.log or ~/.cache/qawolf/qawolf.log

Run with --verbose to mirror debug logs to stderr in real time:

qawolf flows run --verbose

Common issues

The CLI Troubleshooting reference covers the specific errors the CLI emits, including authentication failures, missing Android SDK, expired download links, and the @qawolf/testkit resolution error.