/user-test

name: user-test
description: "Test an app, API or CLI like a real user: launch it, try every feature or named ones, log bugs, perf and UX issues, auto-fix simple ones, report. Don't use for unit tests, E2E suite code, or design audits."
license: MIT
effort: high
metadata:
  version: 1.0.1
  author: "Luong NGUYEN <luongnv89@gmail.com>"
  architecture: "orchestrator (explorer, then one tester per area in sequence, then fixer + fresh verifier per finding, then validated report)"

User Test

Use the app the way its users would. Launch it, walk every in-scope journey through its real interface, prove each problem with evidence, fix the simple and medium problems and verify each fix the same way, then hand back one report with a plan for the rest. The run is done when `report` exits 0.

Terms used throughout:

• **run dir**: `.user-test/<UTC stamp>/` in the project root. `init` creates it and excludes `.user-test/` from git.
• **journey**: one user goal done start to finish through the app's own interface: UI, public API, or CLI.
• **finding**: one problem or improvement with steps, expected and actual results, and evidence. A suspicion without evidence is a note, not a finding.
• **side-effect action**: a step that charges real money, messages a real person, posts publicly, or changes data the run did not create. Sandbox payments, mail catchers and `example.com` addresses are not side effects.
• **env notes**: facts the user gave about the environment (test keys, accounts, "Stripe is in test mode"). Pass them to every worker.
• **fix mode**: on by default. Off when the request says "report only", "don't change code", "no fixes" or `fix: off`, and always off on the Remote branch.
• **verified fix**: the build exits 0, tests show no new failures against the baseline, and a fresh verifier repeated the finding's steps and saw the expected result.
• **checkpoint**: whole-file copies of the files a fix touches, saved before its first edit. Restoring returns those files to their state before that fix.

`UT` means `python3 <skill-dir>/scripts/user_test.py`. Each subcommand prints JSON. Exit 1 means a check failed, 2 bad input or a missing tool, 3 a conflict that needs the user; read the `error:` and `fix:` lines on stderr. Workers load `references/testing.md` and `references/fixing.md`; the main agent never opens them, because a long run's context budget is the scarce resource.

When to Use

Use when the user wants an app, API or CLI tried the way a real user would: "test my app end to end", "QA or dogfood this before release", "click through every feature", "check checkout like a customer". Not for writing unit tests (test-coverage), writing Playwright or Cypress suites, reviewing code without running it (code-review), design-only audits (design-optimizer), confirming that one recent change works (just run the app), load testing, or penetration testing.

Prerequisites

• `python3` and a shell. The script requires only the standard library.
• A driver for the app type: an isolated browser (a Playwright MCP server or a Playwright script) for a web UI, `curl` for an API, the shell (plus `tmux` for a full-screen TUI) for a CLI.
• Fix mode requires the source and a build or test command. Gated features require test credentials.

Step 0: Select the branch

Check the rows in order; the first match wins.

| Condition | Branch | |---|---| | The request gives a URL, or calls the app deployed, staging or production | **Remote**: no launch; fix mode off; report and plan only | | The user says the app already runs locally | **Local-reuse**: skip the launch; fix mode as requested | | Source code is in the named or current directory | **Local**: launch from source; fix mode as requested | | Neither source nor URL can be found | Ask for one. Do nothing else |

Scope is **all** features unless the request names some; then it is **focus**: the named features are tested, and the journeys needed to reach them (sign-in, cart) are only preconditions. Print the branch, scope and fix mode in one line, then continue without waiting. Remote against production: ask once before creating any account or record.

Repo Sync Before Edits (mandatory)

Applies when fix mode is on and the project is a git repo. Run it right after `UT init`, before `UT detect`, in the project root (`<root>`):

branch="$(git -C <root> rev-parse --abbrev-ref HEAD)"
git -C <root> fetch origin && git -C <root> pull --rebase origin "$branch"

If the tree is dirty: `git -C <root> stash push -u -m "pre-user-test"`, sync, then `stash pop`. If `origin` is missing or the branch has no upstream, ask once whether to continue without a sync, unless the request says the repo is local-only. If `branch` is `HEAD` (detached), skip the sync and note it. If the rebase or the pop conflicts, stop and ask the user.

Workflow

Steps 3–5 delegate to subagents. Without the Agent tool, read the named reference yourself, run the step inline one area at a time, and run `UT update --run-dir <run_dir> --note "ran inline: fixes verified by the same agent"`.

Step 1: Preflight

1. Run `UT init --root <root> --branch <local|local-reuse|remote> --scope <all|"a,b"> --fix <on|off> [--url <url>]`. Record `run_dir`. Then run the Repo Sync. 2. Run `UT doctor` and `UT detect --root <root>`. Prefer a command the README documents over a detected one. 3. Pick a driver every subagent can use: Playwright MCP or a Playwright script with a fresh profile for a web UI, never the user's own browser profile; `curl` for an API; the shell or `tmux` for a CLI or TUI. Record it: `UT update --run-dir <run_dir> --json '{"driver": "<driver>"}'`.

Bar: `run.json` names the branch, scope, fix mode and driver.

Step 2: Launch the app

1. Install dependencies only when `detect` reports `deps_missing`, only with its lockfile command, and never on Local-reuse or Remote. 2. Backing services: if `detect` lists `services` or the README needs a database, run its `check` comm