QAwalk

All guides › By use case

By use case

Desktop apps: Electron and macOS apps on the same canvas

QAwalk opens Electron apps through Playwright with every web check, captures macOS app windows with their accessibility tree, and imports screens from any other tool, so desktop flows get the same review as web and mobile.

Desktop apps are often the product nobody walks through before a release: the web version gets the review, the Electron wrapper gets a smoke test. QAwalk treats a desktop window like any other screen.

The problem

Desktop releases are checked by opening the app and clicking around. Nothing is recorded, nothing is compared with the last release, and localized menus or dialogs are seen by customers first.

What changes with QAwalk

platform: electron opens the app through Playwright. Its window is a web page to QAwalk, so selectors, accessibility checks, console errors and semantic questions all work unchanged. platform: desktop captures a macOS app's window with its accessibility tree (or the text on it). Every screen is framed as a window on the canvas, next to the web and mobile runs of the same feature.

How it works

  1. Name the app

    app.electron.main: dist/main.js (or the packaged executable), or app.desktop.name: Notes for a macOS app.

  2. Script the steps

    Electron steps get a Playwright page, so app.tap('#new') or any Playwright code works. macOS steps are driven by your tool, by AppleScript or by a person, and QAwalk captures the window.

  3. Check

    packs a11y and console apply to Electron as on the web. The app pack checks labels, sizes and truncated texts in macOS windows.

  4. Review and compare

    the canvas shows each step in a window frame. The next release's run compares screen by screen against the accepted baseline.

Skills and prompts

Walk our Electron app in en and cs: the empty state, creating a note and the settings dialog. Use the a11y pack and share the run for review.
Capture the preferences window of our macOS app after each change in this PR, and tell me which labels got truncated in Czech.

Expected outcome: window-framed screens per locale with their checks, console errors from the renderer and a comparison with the previous release.

What you get

FAQ

Windows and Linux apps?

The built-in window capture is macOS only. On Windows or Linux, drive the app with WinAppDriver, Appium or your own tool and import the screenshot (and the UI dump if you have one) with qawalk capture --image.

Which macOS permissions does it need?

Screen Recording for window screenshots and Accessibility for the UI tree, granted to the terminal or the agent app. Without Accessibility, QAwalk falls back to text recognition.

More guides

Accepting a task with an AI agent, in the pull requestRegression before a release: compare the run with the accepted baselineSEO and landing-page checks on production, read-only, every dayE-mail flows: capture the message next to the screen that sent it

Install in three steps

QAwalk runs where your code and your agent are. The service stores and versions the results, shows the canvas and collects approvals.

  1. Add the CLI to the project
    npm install --save-dev @qawalk/cli

    Needs Node 20 or newer. Update later with npm update @qawalk/cli.

  2. Create the config and install the skill
    npx qawalk init --agent claude --org <your-org>
npx qawalk doctor

    The skill is copied to .claude/skills/qawalk.

  3. Create your organization and a token

    Create an organization; you become its admin. The start page offers a tester token in one click, later under Settings → API tokens. Put it into the project .env:

    QAWALK_TOKEN=qwk_…
TYPESAFE_API_KEY=…   # optional: semantic evaluator
  4. Run and share
    npx qawalk start --scenario docs/tasks/TASK-123/qa/scenario.yml --env local
npx qawalk walk        # playwright steps; agent/manual steps: qawalk capture
npx qawalk evaluate
npx qawalk share --pr

    Or ask your agent: “Walk the acceptance plan of TASK-123 with QAwalk on local and share the result.”