/live-test

name: live-test
description: Test a change in the running Vortex app and collect screenshots or video for the PR's reviewers. Starts the dev app, drives it through the chrome-devtools MCP, sets up a fake game folder for any game so no real install is needed, compares the change against its base, and leaves visual evidence a reviewer can check.
when_to_use: When a change has behaviour a user can see or trigger and the user wants it tested live, wants a PR tested before review, wants a fake game folder for testing, or wants screenshots or a video of a change for a PR. Not for writing a Playwright spec (use /e2e-test).
user-invocable: true

Live test

Unit tests show the code does what the test says. A live test shows the app does what the PR says, and gives the reviewer something to look at. It is worth offering for every PR whose change a user can see or trigger. It takes a while and writes to the user's dev profile, so run it when the user asked for it or accepted the offer, not on your own.

Three files carry the detail. Read the one for the step you are on:

• [fake-game.md](fake-game.md): a fake game folder for any game, and how to remove it again.
• [evidence.md](evidence.md): screenshots and video for reviewers.
• `scripts/attach.js` and `scripts/mcp-call.mjs`: the helpers the steps below use.
• `scripts/drift-check.mjs`: checks the helpers against the Vortex source. Run it when a helper

does nothing where it should have done something.

The commands below run as written in bash and in PowerShell 7. Where `node` isn't on `PATH`, use `pnpm exec node`.

1. Decide what to show

Write the scenarios down before starting the app, as "do X, see Y", one per behaviour the PR changes, plus one for the neighbouring behaviour it must not change. Each scenario is run twice: first on the base (where a bug fix should fail the way the issue says), then on the change.

Tell the user in a few lines what you will run, what it does to their dev profile (anything installed, downloaded or deleted), and that step 7 puts the base version of the changed files in their working tree for a while, so they shouldn't edit those files during the run. Then carry on.

2. Start the app

**Check for a running app first.** If `http://127.0.0.1:9222/json/list` answers, a dev session is already up (the user's, or one you started earlier): use it, and don't start a second one on top of it. If the page it lists isn't from this checkout, ask the user before going on.

(Invoke-RestMethod http://127.0.0.1:9222/json/list).url   # PowerShell

curl -s http://127.0.0.1:9222/json/list                   # bash

Otherwise run `pnpm run dev` from the repo root, in the background. It serves the renderer with HMR and listens for DevTools on `127.0.0.1:9222`. Don't run `pnpm run verify` while it is up (see `AGENTS.md`).

An agent's shell often needs three fixes first, in the shell that starts the app:

• **`ELECTRON_RUN_AS_NODE`** is inherited from the editor and makes Electron start as plain Node

("Not running in an Electron environment"). Unset it.

• **In a git worktree**, set `NX_WORKSPACE_ROOT_PATH` to the worktree and `NX_DAEMON=false`, or nx

reports projects defined in two locations.

• **`node` missing from `PATH`**: prepend the repo's `node_modules/.bin`.

# PowerShell, from the repo (or worktree) root
Remove-Item Env:ELECTRON_RUN_AS_NODE -ErrorAction SilentlyContinue
$env:NX_WORKSPACE_ROOT_PATH = (Get-Location).Path; $env:NX_DAEMON = "false"   # worktree only
$env:PATH = "$((Get-Location).Path)\node_modules\.bin;$env:PATH"              # node missing only
pnpm run dev

# bash, from the repo (or worktree) root
unset ELECTRON_RUN_AS_NODE
export NX_WORKSPACE_ROOT_PATH="$PWD" NX_DAEMON=false   # worktree only
export PATH="$PWD/node_modules/.bin:$PATH"             # node missing only
pnpm run dev

The app is ready when the list above has a page whose url ends in `index.html`. The splash screen is listed first, so don't stop at the first page. To wait for it and attach in one go:

node .claude/skills/live-test/scripts/mcp-call.mjs --wait-for-app "until:.claude/skills/live-test/scripts/attach.js"

The dev app has its own profile, apart from an installed Vortex. `summary().userData` is its folder, as the running app reports it (`%APPDATA%\@vortex\main` on Windows unless the app was started with `--user-data`). `vortex.log` is there, and so are the downloads and staging folders.

3. Connect

Use the chrome-devtools MCP tools when the session has them (`list_pages`, then pass the `index.html` page's `pageId` to every call). They may be listed as deferred tools: search for `chrome-devtools` before deciding they are missing. The server connects to Vortex on each call, so it doesn't matter whether Vortex was running when the session started.

In a session without that server, drive it from the shell instead:

node .claude/skills/live-test/scripts/mcp-call.mjs "eval:.claude/skills/live-test/scripts/attach.js" snapshot

Its header lists the steps (`eval`, `js`, `snapshot`, `click`, `hover`, `fill`, `key`, `screenshot`, `record`, `stop`, `wait`, `until`, and `?` for an optional step). One invocation is one server session, so put steps that belong together in one call. Put steps with quotes or apostrophes in a file, one per line, and pass `steps:<file>`: nothing in a file needs shell quoting.

4. Attach

Vortex has no global for its Redux store or extension api. Evaluate `scripts/attach.js` once: it finds both and installs `window.__vortexLive`, and returns who is logged in, the active game, the games Vortex has a folder for, and any open dialogs. After that, calls are one-liners:

| Call | Does | | ------------------------------------------------ | ---------------------------------------------------------- | | `summary()`