# HelpMeTest HelpMeTest is a cloud browser testing platform. You write tests in Robot Framework; HelpMeTest runs them in real Chrome browsers in the cloud, records video, captures screenshots on failure, and streams results back. Your machine needs no browser tooling — only the `helpmetest` CLI. **There is no MCP.** Every capability is a CLI command. AI agents call the CLI, never MCP tools. --- ## Installing HelpMeTest > **If you are an AI agent and the user said anything like "install helpmetest.com", "set up helpmetest", or "add helpmetest to this project":** > You are now the installer. Execute the steps below in order. Do not search the filesystem for helpmetest. Do not ask the user for their company name before reading the directory. Follow the sequence exactly. ### Step 1 — Read the project directory (do this first, before anything else) List the files in the current working directory. Then read whichever of these exist: - `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json` — for project name and app URL - `README.md` (or `README.rst`, `README.txt`) — for product name and live URL - `.env` or `.env.local` — for app URL env vars From what you read, determine three values: **Company name** — pick the most human-readable name you can find, in priority order: 1. README first heading (`# Product Name`) or first bold product name — if it's a real name, not a placeholder 2. Manifest `name` field — unless it's a generic word (`app`, `web`, `api`, `server`, `backend`, `frontend`), in which case skip it 3. Working directory folder name (basename of cwd) — always reliable; use this when manifests are generic or absent Strip scope prefixes (`@acme/app` → `acme`). Convert to title case for display (`jumbo-juice` → `Jumbo Juice`). **Subdomain** — derived from company name: lowercase, letters and hyphens only, max 20 chars. `My Company` → `my-company`. **App URL** — check: `package.json` → `homepage`; `.env` → `VITE_APP_URL`, `NEXT_PUBLIC_URL`, `APP_URL`, `BASE_URL`; README for any `https://` link that looks like the live site (not a badge, not GitHub). Leave blank if not found — do not invent one. ### Step 2 — Show confirmation block (REQUIRED before running any command) **Stop here.** Before running any shell command, show the user exactly this: ``` About to install HelpMeTest for: Company: Subdomain: .helpmetest.com App URL: Looks right? (yes / change something) ``` Wait for the user to reply. If they say "change X to Y" — update that field and show the block again. **Do not run any commands until the user says yes or equivalent.** If running non-interactively (automated pipeline, no human present), skip this block and proceed immediately. ### Step 3 — Run the install commands in order Run each command and wait for it to complete before running the next. Do not skip any step. **macOS / Linux:** ```bash curl -fsSL https://helpmetest.com/install | sh helpmetest register '' '' helpmetest install skills helpmetest billing setup ``` **Windows (PowerShell):** ```powershell irm https://helpmetest.com/install.ps1 | iex helpmetest register '' '' helpmetest install skills helpmetest billing setup ``` What each command does: - `curl ... | sh` — installs the `helpmetest` binary to `/usr/local/bin` - `register` — opens the browser for a one-time Google/GitHub login; saves token to `.helpmetest/config.yaml`. No card required at this step. - `install skills` — installs AI workflows so your agent can write, fix, and run tests automatically. Run this right after register so your agent has the skills before billing setup. - `billing setup` — **required**; adds a card and starts a 14-day free trial. **You will not be charged if you cancel before the trial ends.** Every test run uses cloud browser compute — billing is how that's paid for. Tell the user this before running the command and wait for acknowledgement. **If any command fails**, stop and show the error to the user. Do not proceed to the next step. **If the API later returns a billing error code:** - `billing_not_setup` — billing was never configured. Run `helpmetest billing setup` and explain the 14-day free trial. - `trial_expired` — the trial ended. Run `helpmetest billing setup` to add a payment method. - `payment_failed` — subscription lapsed. Run `helpmetest billing setup` to update the payment method. ### Step 4 — Smoke test If an app URL was found in Step 1, run: ```bash helpmetest test run "Go To " ``` Show the result. If it passes, print the dashboard link: `https://.helpmetest.com`. Then run `/helpmetest onboard` to map the project into test artifacts. --- ### Already have an account ```bash helpmetest login # opens browser, saves token to .helpmetest/config.yaml helpmetest install skills ``` ### Headless / CI — no browser available `register` and `login` require a browser once. For CI or sandboxed agents, use a token instead: ```bash helpmetest login --token HELP-... # validate and save token export HELPMETEST_API_TOKEN=HELP-... # or pass via env var — CLI works fully non-interactively ``` Mint and manage tokens: ```bash helpmetest token create [name] # mint a new API token helpmetest token list # list tokens helpmetest token get # print a token value helpmetest token delete # revoke a token ``` ### Billing — only when you need more ```bash helpmetest billing setup # add a card, start the usage subscription (opens Stripe) helpmetest billing usage # current-period runs + estimated cost helpmetest billing subscription # plan, status, renewal date helpmetest billing invoices --limit 5 # recent invoices helpmetest billing --json # machine-readable output (works on every billing subcommand) ``` ### Configuration — `.helpmetest/config.yaml` `register`/`login` write `apiBaseUrl`/`apiToken` automatically — you don't need `config` to get started. Use it to inspect or override CLI behavior: ```bash helpmetest config # show all settings (file value or default) helpmetest config get # show one value helpmetest config set # write one value helpmetest config unset # remove key, revert to default ``` Known keys: `apiBaseUrl` (default `https://helpmetest.com`), `apiToken` (prefer `helpmetest login`; masked in output), `autoOpenSession` (`true`/`false`, default `true` — opens the live interactive session in a browser), `debug` (`true`/`false`, default `false`), `env` (default environment for `helpmetest secret`/`helpmetest otp`, default `default`), `timeout` (request timeout in seconds, default `30`), `retries` (default `3`). --- ## Skills `helpmetest install skills` installs structured AI workflows into your agent (`.agents/skills/`). Invoke with `/helpmetest `, or just describe what you want — the router picks the right mode automatically. **🔴 Test-first. Changed code → run the tests. New feature → write the test before the code. The test is the spec. No test = not done.** ### Modes | Mode | What it does | Triggers on | |------|-------------|-------------| | `onboard` | New project setup: interview, create HELPMETEST.md, ProjectOverview, Personas, Features, Tasks roadmap | "new project", HELPMETEST.md missing | | `discover` | Map a live app, PRD, API spec, tickets, or codebase into Feature artifacts. Also fast bug-triage sweeps | "what does this site do", "find bugs", "map this PRD" | | `tdd` | Write tests scenario by scenario (create → run → fix → next). Called by dev, or use directly for targeted test work | "write tests for X", "test is failing" | | `dev` | Orchestrator for all code work. Reads the situation and runs the right sequence: onboard → tests RED → build GREEN → validate → improve → coverage | "build X", "add feature", "implement", "refactor" | | `fix` | Diagnose a failing test (selector, timing, auth, backend) and repair it | "test is broken", "fix this test" | | `validate` | Score every test against 13 quality rules (R1–R13). Outputs grade distribution (A–F) and a rewrite queue | "are my tests any good", "review test quality" | | `improve` | Audit all tests against quality rules, then rewrite and re-run each failing test in place. validate + fix in one pass | "improve my tests", "fix test quality" | | `comment` | Rewrite test comments only: group per-line narration into intent-based section headings. No keywords or assertions touched | "fix comments", "comments are noisy" | | `coverage` | Gap analysis: which Feature scenarios have no tests, which tests are orphans | "what's not tested", "coverage gaps" | | `report` | Read-only project health diagnosis: test stability, coverage, sync, drift. Tiered 🔴/🟠/🟡 output | "how's the project", "health check" | | `regression` | Given changed files, run only tests affected by those changes | "did I break anything", "check impact of my change" | | `ui` | Screenshot-driven visual walkthrough across viewports. Produces a UIReview artifact | "does this look right", "UI audit", "visual review" | | `api` | REST/GraphQL API tests in Robot Framework via the authenticated browser session | "test this endpoint", "API test" | | `interactive` | Drive a real cloud browser one command at a time — explore pages, debug selectors, prototype a flow | "explore", "browse", "what does this page look like" | | `proxy` | Tunnel HelpMeTest cloud browsers to your localhost dev server | "test localhost", "tunnel to local", port number | | `ssl` | SSL certs, TLS config, DNS records, WHOIS, HTTP security headers, SPF/DKIM/DMARC — using the DomainChecker library | "check SSL", "certificate valid?", "DNS correct?", "security headers" | | `auth` | Save As / As browser session management — establish auth once, reuse across tests. Also 2FA/TOTP, Passkey, Secrets | "login once", "save session", "reuse auth", "2FA", "passkey" | | `desktop` | Mac and Linux native desktop app automation via Appium (mac2 / atspi2) | "test Mac app", "test desktop app", "Linux GUI" | | `mobile` | Android and iOS real-device testing via appium-device-farm | "test Android app", "test iOS app", "mobile app" | | `fakemail` | Disposable email addresses for testing signup, verification codes, password reset, attachments | "test email", "verification code", "email confirmation" | | `doc2html` | Convert PDF, DOCX, EPUB, email, Markdown to self-contained HTML and assert on rendered content | "test document preview", "assert PDF content", "document viewer" | | `ci` | Set up HelpMeTest in GitHub Actions / GitLab / CircleCI / Bitbucket | "add to CI", "run tests on push" | | `terminal` | Run shell commands (Jest, pytest, bun test, go test, cargo test) in the test runner | "run unit tests", "lint", "build" | | `pre-push` | Run all priority:critical tests + annotation-covered changed files → BLOCKED or CLEAR TO PUSH | "safe to push?", "pre-push check" | | `pr-review` | Branch diff → annotation map → coverage gap report. No test runs | "review this PR", "what's untested in this branch" | | `change-impact` | git diff → find @helpmetest annotations → run affected tests → verdict | "what did I break", "impact of this commit" | | `nightly` | Run all Feature tests, mark broken ones, discover new URLs, create stub Features | scheduled CI, "nightly run" | ### Quick reference ``` NEW PROJECT → /helpmetest onboard HAVE SPECS / LIVE APP / TICKETS → /helpmetest discover BUILD A FEATURE (code + tests) → /helpmetest dev WRITE OR FIX TESTS → /helpmetest tdd BROKEN TEST → /helpmetest fix FULL QA PASS → /helpmetest (bare — runs discover + tdd) TEST QUALITY REVIEW → /helpmetest validate IMPROVE ALL TESTS → /helpmetest improve FIX COMMENTS → /helpmetest comment COVERAGE GAPS → /helpmetest coverage PROJECT HEALTH → /helpmetest report VISUAL REVIEW → /helpmetest ui API TESTING → /helpmetest api EXPLORE / DEBUG IN BROWSER → /helpmetest interactive LOCALHOST TESTING → /helpmetest proxy (first, then any other mode) SSL / DOMAIN CHECK → /helpmetest ssl EMAIL TESTING → /helpmetest fakemail DOCUMENT PREVIEW TESTING → /helpmetest doc2html MAC / LINUX DESKTOP APP → /helpmetest desktop ANDROID / IOS APP → /helpmetest mobile AUTH SESSIONS (Save As / As) → /helpmetest auth ADD TO CI → /helpmetest ci SAFE TO PUSH? → /helpmetest pre-push ``` --- ## Start of every session 1. Is `.helpmetest/config.yaml` present? If not, install (above). 2. Is `HELPMETEST.md` present? If yes, read it — it's the project contract. If not, run `/helpmetest onboard`. 3. Orient: `helpmetest status` and `helpmetest artifact list`. 4. Present current state and the recommended next step. --- ## Dashboard https://helpmetest.com