# Authenticate Source: https://docs.percio.app/agent/authentication Set up your API key for the CLI and MCP server The agent talks to the Percio API, so it needs a key. You have two options. ## Option A — `percio login` (recommended) Run: ```bash theme={null} percio login ``` You'll be prompted to paste your API key. Percio stores it at: ``` ~/.config/percio/credentials.json ``` Both the CLI and the MCP server read from this file automatically. You only need to log in once per machine. ## Option B — `PERCIO_API_KEY` environment variable Set: ```bash theme={null} export PERCIO_API_KEY="pk_..." ``` Useful for: * **CI.** Store the key in a secret, expose it as an env var, run `percio test` directly. * **Ephemeral shells** where you don't want to write credentials to disk. * **Shared machines** where each user's key stays scoped to their shell session. The env var takes precedence over the credentials file if both are set. ## Getting an API key Keys are created in the web app: 1. Sign in at [percio.app](https://percio.app). 2. Go to **Integrations**. 3. Under **Agent integrations**, generate a new API key. 4. Copy it immediately — you won't see it again. ## Rotating or revoking a key On the **Integrations** page you can revoke an existing key and generate a new one. After revoking, update your credentials: ```bash theme={null} percio login # paste the new key ``` Or re-export `PERCIO_API_KEY` in any shell that uses the env-var approach. ## Verifying it worked Any command that talks to the API will fail fast with `No API key found` if it can't read a key. The simplest smoke test: ```bash theme={null} percio personas list ``` If the CLI prints your personas, you're authenticated. ## What's next * [The local daemon](/agent/daemon) * [Run your first test](/agent/cli/test) # percio login Source: https://docs.percio.app/agent/cli/login Store your API key on disk Save your API key so the CLI and MCP server can use it automatically. ## Synopsis ```bash theme={null} percio login ``` You'll be prompted to paste your API key. Paste it and press enter. ## What it does * Stores the key at `~/.config/percio/credentials.json`. * Makes the key available to every future `percio` and `percio-mcp` invocation on this machine. ## Example ```bash theme={null} $ percio login Paste your API key: pk_•••••••••••••••••••••••••••• Validating key... API key saved to ~/.config/percio/credentials.json You're all set! Run: percio test --url --flow ``` ## When to use this * First time you install the CLI on a machine. * After rotating your API key on the dashboard. ## When *not* to use this * In CI — prefer the `PERCIO_API_KEY` environment variable so nothing writes to disk. * On shared machines where you don't want your key persisted for other users of your account. See [Authenticate](/agent/authentication) for the full comparison. ## Where the key is stored ``` ~/.config/percio/credentials.json ``` Delete this file to log out. `PERCIO_API_KEY` (if set) takes precedence over whatever is in the file. ## What's next * [percio test](/agent/cli/test) * [percio personas list](/agent/cli/personas-list) # percio personas list Source: https://docs.percio.app/agent/cli/personas-list List your cloud personas and their UUIDs Print every persona on your account. Use it to find the UUIDs you need for `percio test --persona-id`. ## Synopsis ```bash theme={null} percio personas list ``` ## Options | Flag | Description | | --------------------- | --------------------------------------- | | `-c, --config ` | Path to a `.perciorc.json` config file. | ## Example ```bash theme={null} $ percio personas list 3 personas from Percio API: 👨‍💻 Sam the first-timer — Freelance designer ID: 123e4567-e89b-12d3-a456-426614174000 New to subscription tools Tech expertise: intermediate 👩‍💼 Rachel the power user — Growth marketer ID: 223e4567-e89b-12d3-a456-426614174001 Ships daily, expects keyboard shortcuts Tech expertise: expert 📱 Maya on mobile — Cafe owner ID: 323e4567-e89b-12d3-a456-426614174002 Shops from her phone while on break Tech expertise: beginner ``` Copy the `ID:` line for the persona you want to use with `--persona-id`. ## Using the output ```bash theme={null} percio test --url https://example.com \ --flow "Sign up" \ --persona-id 123e4567-e89b-12d3-a456-426614174000 ``` To evaluate the same flow through a different persona, run a second `percio test` command with that persona's UUID. ## Don't see the persona you want? Create one: * From the web app on the **Personas** page ([Creating personas](/personas/creating-personas)). * From Cursor via the MCP tools `chat_persona` and `create_persona` ([MCP tools](/agent/mcp-tools/create-persona)). ## What's next * [percio test](/agent/cli/test) * [Persona strategy](/personas/strategy) # percio start Source: https://docs.percio.app/agent/cli/start Start the local Percio daemon Start the daemon that powers the Percio CLI. You rarely need to run this explicitly — other commands auto-start the daemon — but you will use it for MCP mode, pinned ports, and troubleshooting. ## Synopsis ```bash theme={null} percio start [options] ``` ## Options | Flag | Description | | ----------------- | ------------------------------------------------------------------- | | `-d, --detach` | Run the daemon in the background and return immediately. | | `--mcp` | Start with the MCP server enabled on stdio. Used by `percio-mcp`. | | `--port ` | Pin the daemon to a specific port instead of picking one at random. | ## Examples **Foreground (default).** Best for integrated terminals where you want the shell to stay usable while the daemon runs: ```bash theme={null} percio start ``` **Detached.** Runs in the background, returns immediately, and prints the port it bound to: ```bash theme={null} percio start -d # Daemon started in background at http://127.0.0.1:52431. Use percio stop to stop. ``` **Pinned port.** Useful when you're integrating with something that needs to know the port ahead of time: ```bash theme={null} percio start --port 5174 ``` **MCP mode.** Starts the daemon with the MCP server attached to stdio. This is what `percio-mcp` does under the hood, and what your Cursor config invokes: ```bash theme={null} percio start --mcp ``` ## What it does * Binds an HTTP server to `127.0.0.1` (localhost only). * Writes a lockfile so future CLI commands know how to reach it. * Creates `.perciorc.json` in the current directory if one doesn't exist. ## Auto-start Every other CLI command (`percio test`, `percio personas list`, etc.) will auto-start the daemon if one isn't running. You don't need to call `percio start` unless you want one of the scenarios above. ## Checking it's running After a detached start, the daemon port is printed to your terminal. You can also check via any CLI command that talks to the daemon — they'll fail fast if the daemon is unreachable. ## What's next * [percio stop](/agent/cli/stop) * [The local daemon](/agent/daemon) # percio stop Source: https://docs.percio.app/agent/cli/stop Shut down the local Percio daemon Stop a running Percio daemon. ## Synopsis ```bash theme={null} percio stop ``` ## What it does * Reads the daemon's lockfile to find the running daemon. * Sends it a shutdown request. * Removes the lockfile. ## Example ```bash theme={null} $ percio stop Daemon stopped. ``` If no daemon is running, Percio tells you: ```bash theme={null} $ percio stop Daemon is not running. ``` ## When to use this * You're done for the day and want to free up the Chromium processes. * You're troubleshooting a stuck daemon — `percio stop` followed by retrying your command usually clears the issue. * You pinned the daemon to a specific port and want to free it. ## When *not* to use this * During a running test. The CLI holds the test alive through the daemon — stopping the daemon mid-test will cut it off. ## What's next * [percio start](/agent/cli/start) * [The local daemon](/agent/daemon) # percio test Source: https://docs.percio.app/agent/cli/test Run an AI-powered usability test on a URL The main command. Runs a full usability test — browser automation, persona evaluation, and a written report — against any URL, including `localhost`. ## Synopsis ```bash theme={null} percio test --url [options] ``` Run without `--flow` to start an interactive scenario conversation in your terminal. Pass `--flow` to skip the conversation and run directly. ## Options | Flag | Description | Default | | --------------------------- | ------------------------------------------------------------------------------ | ----------------- | | `-u, --url ` | Target URL to test. Supports `localhost` and any valid URL. | *required* | | `-f, --flow ` | Scenario for the persona to attempt. Omit to run the interactive conversation. | *none* | | `-p, --persona ` | Local persona preset: `casual`, `professional`, or `power`. | `casual` | | `--persona-id ` | Cloud persona UUID (from `percio personas list`). Overrides `--persona`. | *none* | | `--max-steps ` | Maximum steps before the agent stops. | `50` | | `--viewport ` | Browser viewport. Bounds: 320–3840 × 240–2160. | `1280x800` | | `--headless` | Run the browser in headless mode. | `false` (visible) | | `--timeout ` | Overall test timeout. | *no limit* | | `-o, --output ` | Write JSON results to disk. | *none* | | `-v, --verbose` | Print detailed step-by-step output to the terminal. | `false` | | `-c, --config ` | Path to a `.perciorc.json` config file. | *auto* | ## Examples **Interactive mode.** No `--flow` — Percio helps you build the scenario in your terminal: ```bash theme={null} percio test --url https://example.com ``` **Direct mode.** Scenario provided, skip the Q\&A: ```bash theme={null} percio test --url https://example.com --flow "Sign up for an account" ``` **Cloud persona.** Run the test through a persona you created in the web app: ```bash theme={null} percio personas list # get the UUID percio test --url https://example.com \ --flow "Buy a product" \ --persona-id 123e4567-e89b-12d3-a456-426614174000 ``` **Testing `localhost`.** Probably your most common use case in development: ```bash theme={null} percio test --url http://localhost:3000 \ --flow "Create an account and post your first comment" ``` **Headless in CI with JSON output.** Runs without a visible window and writes results to disk: ```bash theme={null} percio test --url https://staging.example.com \ --flow "Complete checkout with a test card" \ --headless \ --output results.json ``` **Mobile viewport.** ```bash theme={null} percio test --url https://example.com \ --flow "Find the nearest store" \ --viewport 390x844 ``` ## What you see in the terminal By default, Percio prints phase-level progress: navigating, executing the flow, analyzing results. With `-v / --verbose`, every step is logged with the agent's reasoning and action details. When the run finishes, Percio writes a markdown report to the current directory: ``` percio-report-2026-04-21T17-42-32.md ``` The same report is also saved server-side and appears in your web app test history. ## Interactive scenario mode When you omit `--flow`, Percio starts a conversational scenario builder in your terminal: ```bash theme={null} $ percio test --url https://example.com What do you want to test? > Sign up flow for a new user Great. What kind of user are we simulating? > Someone who's never used the product before Anything specific you're worried about? > The email confirmation step Based on your answers, here's the scenario: "As a first-time visitor, sign up for a new account, confirm your email, and post your first comment." Proceed? (y/n) ``` You can refine the scenario before confirming. When you say yes, the test runs. ## Local persona presets vs. cloud personas The `--persona` flag accepts a built-in preset for local testing without setting up cloud personas. The three presets are intentionally generic — for real reports you'll want to use `--persona-id` with a persona tailored to your product. Local presets: * `casual` — the default; a moderately tech-savvy everyday user. * `professional` — a business user focused on efficiency. * `power` — an expert user who expects shortcuts and density. `--persona-id` overrides `--persona` when both are given. ## Exit codes * **0** — test completed and a report was produced. * **1** — error (invalid flags, auth failure, daemon issue, etc.). A test that runs to completion but is low-quality (agent abandoned the flow) still exits `0` — the report itself tells you what happened. ## What's next * [percio personas list](/agent/cli/personas-list) * [Writing good scenarios](/tests/writing-scenarios) * [Troubleshooting](/agent/troubleshooting) # Cursor setup Source: https://docs.percio.app/agent/cursor-setup Wire Percio into Cursor via MCP in two minutes The Percio MCP server lets you use Percio tools directly from Cursor's AI. You can ask Cursor things like "run a usability test on the checkout flow" and it'll orchestrate the whole thing — picking personas, building a scenario with you, and running the test — through Percio's tools. ## Recommended setup — `npx` + API key You don't need to install anything globally. Open **Cursor Settings → MCP**, or create **`mcp.json`** in your project root (some setups use **`.cursor/mcp.json`**). Use this shape — replace the API key with the one from your Percio dashboard (**Integrations** → **Agent integrations**): ```json theme={null} { "mcpServers": { "percio": { "command": "npx", "args": ["-y", "@percio/mcp"], "env": { "PERCIO_API_KEY": "$API_KEY" } } } } ``` Paste your real key where `$API_KEY` is shown (or set `PERCIO_API_KEY` to that value in the `env` block). Restart Cursor or reload MCP servers. The Percio tools should now be visible. ## Alternative — use `percio login` credentials If you've already run `percio login` on your machine, you can omit the API key from config and rely on `~/.config/percio/credentials.json`: ```json theme={null} { "mcpServers": { "percio": { "command": "npx", "args": ["-y", "@percio/mcp"] } } } ``` The MCP server reads stored credentials automatically when `PERCIO_API_KEY` is not set. ## Project-scoped vs. user-scoped config Cursor supports both: * **Project-scoped** — `mcp.json` or `.cursor/mcp.json` in the root of a project. Only applies when Cursor opens that project. Good for per-project keys. * **User-scoped** — `~/.cursor/mcp.json` (or the global MCP config path Cursor shows in Settings). Applies across all projects when the same key is used everywhere. Use whichever fits your workflow. Project-scoped wins if both exist. ## Reloading after a config change Changes to `mcp.json` only take effect after Cursor reloads its MCP servers. Either: * Restart Cursor, **or** * Open the MCP settings panel in Cursor and reload servers. ## Verifying it's wired up In Cursor, the MCP tools panel should list Percio tools (names depend on your server version), such as persona and scenario helpers and test-run tools. If they don't appear, see [Troubleshooting](/agent/troubleshooting). ## First prompt to try Once the tools show up, try asking Cursor: > "Can you run a usability test on my sign-up flow at `http://localhost:3000/signup`? I want to test it as a first-time visitor." Cursor will use the listed tools to pick or create a persona, shape the scenario with you, and run the test. ## Using with other MCP clients The same pattern works for Claude Desktop and other **stdio** MCP clients: **`command`** `npx`, **`args`** `-y` and `@percio/mcp`, and **`env.PERCIO_API_KEY`** for your key (or rely on `percio login` credentials when omitting `env`). ## What's next * [MCP tools](/agent/mcp-tools/list-personas) * [Troubleshooting](/agent/troubleshooting) # The local daemon Source: https://docs.percio.app/agent/daemon How the Percio CLI talks to your machine The Percio CLI doesn't do the browser work itself — it talks to a local **daemon** that handles Playwright, manages the test lifecycle, and proxies requests to the Percio API. ## Why the daemon exists * **Browser reuse.** Playwright is expensive to start up. A long-running daemon keeps the browser context warm across commands. * **Isolation.** The daemon runs in its own process so CLI commands return fast even while a test is running. * **MCP integration.** The MCP server runs inside the daemon — starting the daemon with `--mcp` gives you a ready MCP endpoint on stdio. ## You mostly don't have to think about it Every CLI command auto-starts the daemon if one isn't running. `percio test` and `percio personas list` will spin it up transparently the first time you run them. You don't need to `percio start` manually unless: * You're running the MCP server (`percio start --mcp`). * You want the daemon pinned to a specific port (`percio start --port 5174`). * You're debugging a stuck daemon and want to start it in the foreground to see logs. ## How it listens The daemon binds to `127.0.0.1` (localhost only — it's never reachable from the network) on a random port by default. The chosen port is recorded in a lockfile that the CLI reads on every invocation. ## Starting and stopping explicitly ```bash theme={null} percio start # foreground — useful for seeing daemon logs percio start -d # detached — runs in the background and returns immediately percio stop # shuts the daemon down ``` See: * [percio start](/agent/cli/start) * [percio stop](/agent/cli/stop) ## What happens when a command can't reach the daemon If the lockfile is stale (daemon crashed without cleaning up, for example), the CLI will either start a fresh daemon or report a port conflict. Running `percio stop` followed by the failing command usually clears it. ## What's next * [percio start](/agent/cli/start) * [percio stop](/agent/cli/stop) * [Troubleshooting](/agent/troubleshooting) # Install the agent Source: https://docs.percio.app/agent/install Install the Percio CLI and MCP server The agent ships as a single npm package that installs both the CLI and the MCP server. ## Requirements * **Node.js ≥ 18** — check with `node --version`. * A Percio account and an API key (see [Authentication](/agent/authentication)). ## Install ```bash theme={null} npm install -g @percio/agent ``` This installs two binaries globally: * `percio` — the CLI. * `percio-mcp` — the MCP server used by Cursor and other MCP-capable clients. ## Verify ```bash theme={null} percio --version ``` should print a version number. If you get `command not found`, your global npm bin isn't on your `PATH`. Run `npm config get prefix` — the `bin` directory inside that prefix needs to be on your `PATH`. ## Upgrade ```bash theme={null} npm install -g @percio/agent@latest ``` ## Uninstall ```bash theme={null} npm uninstall -g @percio/agent ``` This removes both `percio` and `percio-mcp`. Your stored credentials at `~/.config/percio/credentials.json` are **not** removed — delete that file manually if you want a clean slate. ## What's next * [Authenticate](/agent/authentication) * [Run your first test](/agent/cli/test) # chat_persona Source: https://docs.percio.app/agent/mcp-tools/chat-persona MCP tool — build a persona through conversation The persona builder. Like [`chat_scenario`](/agent/mcp-tools/chat-scenario), this is a conversational loop between **you** and Percio's persona assistant, with the MCP client as a strict **relay**. When the persona is complete, the client passes the generated data to [`create_persona`](/agent/mcp-tools/create-persona) to save it. ## Inputs | Field | Type | Description | | ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `messages` | array | Full conversation history. Each entry has `role` (`user` or `assistant`) and `content` (string). Append each new message and resend the whole array on every call. | ## Output The assistant's next response. Includes an `isComplete` boolean and, once finished, the generated persona data ready to pass to `create_persona`. ## The relay rule Same as `chat_scenario`: Cursor must show the assistant's questions to you verbatim and wait for your answer. It should never invent details about the persona — only your actual words go in as `role: "user"` messages. ## Typical loop 1. Client calls `chat_persona` with an opening `role: "user"` message describing the persona you want. 2. Assistant replies with follow-up questions — occupation, device context, pain points, tech level, etc. 3. Client relays the questions to you. 4. You answer. 5. Client appends to the history and calls again. 6. Repeat until `isComplete: true`. 7. Client calls [`create_persona`](/agent/mcp-tools/create-persona) with the generated data to save the persona. ## Example prompt in Cursor > "Create a Percio persona for a 35-year-old bakery owner who mostly uses Instagram on her phone to run her business." Cursor will call `chat_persona` with that opening line and start the Q\&A. ## When to use it Whenever you want to create a persona without leaving Cursor — or when a scenario calls for a persona you don't have and you want to create one on the spot. ## What's next * [create\_persona](/agent/mcp-tools/create-persona) * [chat\_scenario](/agent/mcp-tools/chat-scenario) # chat_scenario Source: https://docs.percio.app/agent/mcp-tools/chat-scenario MCP tool — build a test scenario through conversation The scenario builder. This tool is a conversational loop between **you** and Percio's scenario assistant — the MCP client (Cursor) acts strictly as a **relay**, passing your messages in and displaying the assistant's replies. ## Inputs | Field | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | string | The URL you want to test. Supports `localhost` and any valid URL. | | `messages` | array | Full conversation history. Each entry has `role` (`user` or `assistant`) and `content` (string). Append each new message and resend the whole array on every call. | ## Output The assistant's next response. Includes a `isReadyToTest` boolean and, once the scenario is finalized, a `testConfig` with the generated scenario string. ## The relay rule This is important — the MCP client must not answer the assistant's questions on your behalf. When the assistant asks "What does success look like?", Cursor must show you the question verbatim and wait for your answer. Only words you actually typed should appear as `role: "user"` messages. If you notice the client inventing answers or skipping your input, stop it and tell it to relay the assistant's question back to you. ## Typical loop 1. Client calls `chat_scenario` with `role: "user"` saying what you want to test. 2. Assistant replies with a clarifying question. 3. Client displays the question to you verbatim. 4. You answer. 5. Client appends `role: "user"` and `role: "assistant"` messages to the history and calls again. 6. Repeat until `isReadyToTest: true`. 7. Client shows you the final scenario for approval. 8. On approval, client calls [`run_usability_test`](/agent/mcp-tools/run-usability-test) with the scenario as `task`. ## When to use it Whenever you want Cursor to help you build a scenario — anytime you're about to kick off a test and don't have an exact scenario in mind. Even if you do, running this tool gives you a sharper, more testable version of your idea. ## Example prompt in Cursor > "Help me test the checkout flow at `http://localhost:3000/checkout`. I want to make sure the guest checkout path works." Cursor will call `chat_scenario` and start the Q\&A with you. ## What's next * [run\_usability\_test](/agent/mcp-tools/run-usability-test) * [chat\_persona](/agent/mcp-tools/chat-persona) # create_persona Source: https://docs.percio.app/agent/mcp-tools/create-persona MCP tool — save a generated persona to your account Takes the persona data produced by [`chat_persona`](/agent/mcp-tools/chat-persona) and saves it to your Percio account. Once created, the persona is immediately available for test runs in both the web app and the agent. ## Inputs | Field | Type | Description | | ------------------ | ----------------- | ----------------------------------------- | | `name` | string | Persona's full name. | | `mainObjective` | string | Main life or work goal, 30–200 chars. | | `techLevel` | number | Tech expertise, 1–5. | | `occupation` | string | Job title or role. | | `description` | string | 2–3 sentence background. | | `systemPrompt` | string | Full evaluation system prompt. | | `focusAreas` | string\[] | 3–5 things the persona pays attention to. | | `painPoints` | string\[] | 2–4 frustrations the persona brings. | | `behavioralTraits` | string\[] | 3–5 personality traits. | | `deviceContext` | string | Primary device and usage context. | | `emoji` | string (optional) | Emoji for the persona. | Every field maps directly to the persona fields in the web app — see [Creating personas](/personas/creating-personas) for the full field guide. ## Output The saved persona, including its new UUID, plus a ready-to-use CLI command for running a test with it: ```bash theme={null} percio test --persona-id --url --flow ``` ## When to use it * After a `chat_persona` loop returns `isComplete: true`, to save the generated persona. * Directly, if Cursor has enough structured input to skip the conversation. ## Cost Creating a persona is free. It does not consume credits. ## Typical MCP flow 1. User asks Cursor to create a persona. 2. Cursor calls [`chat_persona`](/agent/mcp-tools/chat-persona) and relays the Q\&A. 3. When the conversation returns `isComplete: true`, Cursor calls `create_persona` with the generated data. 4. Cursor confirms the persona was saved and optionally offers to run a test with it. ## What's next * [chat\_persona](/agent/mcp-tools/chat-persona) * [run\_usability\_test](/agent/mcp-tools/run-usability-test) * [Managing personas](/personas/managing-personas) # list_personas Source: https://docs.percio.app/agent/mcp-tools/list-personas MCP tool — list your cloud personas Returns every persona on your account. This is always the first step in the MCP test flow: a test requires a persona UUID, and this tool is how Cursor (or any MCP client) discovers what's available. ## Inputs None. ## Output A JSON array of personas. Each entry contains the persona's id, name, emoji, occupation, tagline, and tech expertise — enough for the AI client to present them to you for selection. ## Behavior * If your account has zero personas, the client should offer to create one via `chat_persona` + [`create_persona`](/agent/mcp-tools/create-persona) before running a test. * Results come from the Percio API in real time — personas you create in the web app show up immediately. ## Typical MCP flow 1. Cursor calls `list_personas` and presents the results. 2. You pick one, or ask to create a new one. 3. Cursor moves on to [`chat_scenario`](/agent/mcp-tools/chat-scenario) to build a scenario. 4. Cursor calls [`run_usability_test`](/agent/mcp-tools/run-usability-test) with the chosen persona id. ## Example prompt in Cursor > "List my Percio personas." or simply > "Run a usability test on [http://localhost:3000](http://localhost:3000)." — the client will call `list_personas` as part of orchestrating the run. ## What's next * [chat\_scenario](/agent/mcp-tools/chat-scenario) * [chat\_persona](/agent/mcp-tools/chat-persona) # run_usability_test Source: https://docs.percio.app/agent/mcp-tools/run-usability-test MCP tool — run a usability test and return the report The main event. Launches a real browser, navigates the target URL as the chosen persona, and returns a markdown report plus structured JSON findings. ## Inputs | Field | Type | Description | Default | | ------------ | ------- | --------------------------------------------------------------------------------- | ---------------------------------- | | `url` | string | URL to test. Supports `localhost` and any valid URL. | *required* | | `task` | string | What the persona should try to do. Minimum 10 characters for clarity. | *required* | | `persona_id` | string | Cloud persona UUID. Get it via [`list_personas`](/agent/mcp-tools/list-personas). | *required* | | `max_steps` | number | Maximum steps before stopping (1–200). | `50` | | `headless` | boolean | Run the browser in headless mode. | `false` (visible so you can watch) | | `timeout` | number | Overall test timeout in seconds. | *no limit* | | `viewport` | object | `{ width, height }` for the browser viewport. | `{ 1280, 800 }` | ## Output Three pieces of content: 1. **A full markdown report** — the same report you'd see in the web app, ready to paste into a document. 2. **The structured JSON** — issues, flow analysis, score, metadata. Useful if Cursor wants to do something programmatic with it. 3. **A path to a saved markdown file** — `percio-report-.md` written to the working directory for future reference. ## Required flow before calling this tool The tool itself enforces an ordered flow via its description — a well-behaved MCP client (like Cursor) will: 1. Call [`list_personas`](/agent/mcp-tools/list-personas) and present the personas to you. 2. Let you pick one or offer to create a new one via [`chat_persona`](/agent/mcp-tools/chat-persona) + [`create_persona`](/agent/mcp-tools/create-persona). 3. Call [`chat_scenario`](/agent/mcp-tools/chat-scenario) to build the scenario with you. 4. Show the generated scenario to you for approval. 5. **Only then** call `run_usability_test` with your chosen `persona_id` and the approved scenario as `task`. If you see Cursor trying to run a test without confirming the persona and scenario with you first, stop it and ask it to follow the standard flow. ## Example prompts in Cursor > "Run a usability test on `http://localhost:3000/checkout` using Rachel the power user." > "Test the sign-up flow on the staging site with the first-time visitor persona. Then rerun it with the power user persona so I can compare." ## Visibility vs. headless The default is **visible** — the browser window appears on your desktop so you can watch the agent work. Pass `headless: true` if you're running in the background and don't want a window popping up, or if you're on a headless system. ## Timeouts and step limits * `max_steps` defaults to 50. For simple flows, 25 is usually plenty. Raise it (up to 200) for long flows with many navigation steps. * `timeout` is optional. If you want a hard wall-clock cap, set it — otherwise the test runs until it completes or hits `max_steps`. ## Where the report is saved A timestamped markdown file is written to the current working directory of the MCP server process: ``` percio-report-2026-04-21T17-42-32.md ``` The same report appears in your test history in the web app. ## What's next * [list\_personas](/agent/mcp-tools/list-personas) * [chat\_scenario](/agent/mcp-tools/chat-scenario) * [Cursor setup](/agent/cursor-setup) # Agent overview Source: https://docs.percio.app/agent/overview The Percio CLI and MCP server — test localhost, drive Percio from Cursor The Percio **agent** is a local tool that runs real-browser usability tests against any URL — **including `localhost`**. It ships as a single npm package, `@percio/agent`, which gives you two surfaces: * **The `percio` CLI** — run tests from your terminal. Great for dev loops, CI, and anywhere you can reach a URL that the Percio web app can't. * **The `percio-mcp` MCP server** — expose Percio as a set of tools to MCP-capable clients like Cursor, so you can kick off tests without leaving your editor. Both surfaces use the same account, the same personas, and the same Percio API. A test run from the CLI shows up in your test history in the web app just like any other. ## When to use the agent vs. the web app **Use the agent when:** * You're testing `localhost`, staging on a private network, or any URL the Percio web app can't reach. * You want to run tests from your terminal or CI instead of clicking through a UI. * You want Percio tools available in Cursor while you're coding. **Use the web app when:** * You're testing a publicly reachable URL and want the polished UI. * You want to watch the browser run live and inspect results in one place. * You're sharing reports with non-technical teammates. You can freely mix — a test started from the CLI lives alongside tests from the web app. ## What gets installed `npm install -g @percio/agent` installs both: * The `percio` CLI (entry point: `percio`) * The `percio-mcp` MCP server (entry point: `percio-mcp`) The MCP server is bundled — you don't install it separately. ## Requirements * **Node.js ≥ 18** * An API key (create one on the dashboard → Integrations) ## In depth Install the npm package and verify the CLI is reachable. `percio login` vs. `PERCIO_API_KEY`. What the local HTTP daemon does and why it exists. Every command, every flag. Wire Percio into Cursor via MCP in two minutes. The five tools exposed to MCP clients. # Agent troubleshooting Source: https://docs.percio.app/agent/troubleshooting Common problems with the CLI and MCP server Most agent issues fall into a few buckets. Here's how to clear them. ## "No API key found" The agent can't find a valid API key. Options: * Run `percio login` and paste your key. * Set `PERCIO_API_KEY` in your shell: `export PERCIO_API_KEY="pk_..."`. * If both are set, the env var wins. Generate keys on the dashboard under **Integrations** → **Agent integrations**. ## "Daemon not reachable" or port conflicts The lockfile is pointing at a daemon that isn't actually running, or the port is in use by something else. Clear it: ```bash theme={null} percio stop percio start ``` If that doesn't work, try starting on a different port: ```bash theme={null} percio stop percio start --port 5174 -d ``` ## The CLI hangs at startup Rare, but can happen if something else on your machine is holding the lockfile. Delete it: ```bash theme={null} rm -rf ~/.config/percio/daemon.lock ``` Then retry. ## `command not found: percio` Your npm global `bin` directory isn't on your `PATH`. Find it: ```bash theme={null} npm config get prefix ``` Add `$(npm config get prefix)/bin` to your shell's `PATH`. ## Cursor doesn't see the Percio tools * **Did you restart Cursor?** MCP config changes require a reload. * **Is the JSON valid?** A missing comma or bracket breaks the whole file. * **Is the key correct?** Try the same key with `percio personas list` from your terminal. If that fails, the key is the problem. * **Is `npx` installed?** It comes with npm — `npx --version` should print a number. ## MCP server starts but tools fail Check what the MCP server actually sees. Run it manually: ```bash theme={null} PERCIO_API_KEY=pk_... npx -y @percio/mcp ``` Any errors print to stderr. ## Tests on `localhost` don't find my app * **Is the port right?** `http://localhost:3000` vs. `http://localhost:5173` — make sure the URL matches your dev server. * **Is the dev server running?** Check with your browser first. * **Is the app behind auth?** Scope the scenario to unauthenticated pages, or pre-authenticate the browser context (requires more advanced setup — open an issue if you need this). ## The test abandons immediately Usually means the agent couldn't interact with the page: * **Cookie banner or modal** blocking the viewport — include "dismiss any cookie banner first" in your scenario. * **Heavy client-side routing** that takes longer than the agent expects to wait — rerun with `--max-steps` higher if needed. * **URL redirected to a login page** — see above. ## The test runs but results are generic Almost always a scenario problem. See [Writing good scenarios](/tests/writing-scenarios). The agent can only evaluate what you ask it to — a vague scenario produces a vague report. ## Where to get help * Check [core concepts](/core-concepts) if the terminology is the confusion. * Ping Percio support with your test id or the output of the failing command. ## What's next * [percio test](/agent/cli/test) * [Cursor setup](/agent/cursor-setup) # Credits Source: https://docs.percio.app/billing/credits What credits are, what uses them, and what to do when you run out Credits are how Percio meters test runs. Your plan includes a monthly credit allotment — Indie gets one amount, Pro gets more. ## What uses credits * **Running a test** costs credits per run. If you want to evaluate the same flow through a different persona, run a second test — that's a second credit. ## What's free * **Creating, editing, duplicating, or deleting a persona** in the web app or via MCP. * **Viewing past test results** within your retention window. * **Using the CLI or MCP** is free — credits only charge when a test actually runs. ## Checking your balance On the **Billing** page, the top of the page shows: * Your current credit balance. * When credits reset (next billing cycle). * Your plan and its monthly allotment. ## Running out of credits When you try to run a test without enough credits, Percio shows an **Insufficient credits** dialog before any browser work happens — you won't be charged for a blocked attempt. The dialog gives you two options: * **Upgrade your plan** — if you're on Indie and need Pro's allotment. * **Wait for next cycle** — credits reset each billing period. ## Credits and retention Credits reset with your billing cycle. Unused credits do **not** roll over. ## Being efficient with credits A few habits stretch your credits further: * **Nail the scenario before rerunning.** A well-written scenario gets more signal per credit than a vague one. * **Pick the persona that matches the question.** A first-timer's take on an onboarding flow is different from a power user's — choose the one whose perspective you actually need. * **Rerun with a different persona for a second opinion.** After the first report, run the same scenario with a different persona if you want contrasting findings on the same flow. * **Validate issues.** Mark false positives and dismissals so future runs don't re-surface the same noise. * **Don't rerun a failed test with the same input.** If the first run failed because the scenario was too vague or the URL was wrong, fix that before retrying. ## What's next * [Plans](/billing/plans) * [Managing your subscription](/billing/subscription) # Deactivating and returning Source: https://docs.percio.app/billing/deactivation What happens when you cancel, and how to come back When you cancel your subscription or your account is otherwise deactivated, Percio keeps your data but marks the account inactive. You can come back. ## What deactivation means * Your account is marked inactive. You can't sign in to the app normally. * Your personas, past test results (within retention), and billing history are preserved. * Your trial consumption flag is preserved — if you've already used your Indie trial, returning does **not** give you a new one. * The account is a soft-delete. It's not gone; it's just deactivated. ## When accounts are deactivated * **You cancel your subscription** and the cycle ends. * **A payment fails** and Stripe exhausts its retry schedule. * **You delete your account** from the Settings page (see [Settings](/settings)). ## Returning if you used email + password You can use the normal sign-up form with the **same email** and a **new password**. Percio detects the existing deactivated account, applies your new password, and reactivates the account — no fresh email-confirmation step. This means: * Your old personas and history are still there. * Your old Indie trial flag is still there (no new trial). * You pick back up on whichever plan you're signing up for now. ## Returning if you used Google OAuth Sign in with Google as normal. If the account is deactivated, Percio will route you to the reactivation flow at `/reactivate` where you can restore the account and pick a plan. ## What you won't get back * **The Indie trial**, if you've used it before. The trial consumption flag is never cleared. * **Expired test history** — results that aged out of retention while deactivated are gone. ## Fully deleting your account Deactivation is reversible. If you want everything permanently removed, contact Percio support — account deletion beyond the soft-delete has to be done manually for compliance reasons. ## What's next * [Managing your subscription](/billing/subscription) * [Settings](/settings) # Plans Source: https://docs.percio.app/billing/plans Indie vs. Pro — what's included in each Percio offers two plans: **Indie** and **Pro**. Both are available monthly or annually. ## At a glance | | Indie | Pro | | ---------------------- | ----------------------------- | ------------------------ | | Trial | 14 days, credit card required | No trial | | Personas | Up to 5 | Up to 10 | | Test history retention | 90 days | 365 days | | Credits | Monthly allotment | Higher monthly allotment | | Billing | Monthly or annual | Monthly or annual | Exact credit allotments and pricing are on the [Billing page](/billing/subscription) in the app — they're the single source of truth. ## Indie — for solo founders and small teams Built for founders and small teams iterating on a single product. You get: * Enough credits to run regular tests across your core flows. * Up to 5 personas — room to cover 2–3 core segments with a couple of variants. * 90 days of test history — long enough to track one or two release cycles. * A 14-day trial (credit card required) to evaluate before committing. ## Pro — for teams For teams running more tests, across more products, with more personas: * Higher credit allotment. * Up to 10 personas — enough to cover multiple device contexts, expertise levels, and segments. * 365 days of test history — keep a full year of historical usability data. * No trial (sign up directly on a paid plan). ## Monthly vs. annual Both plans are available monthly or annually. Annual plans are billed upfront at a discount. You can switch between monthly and annual at any time — the next billing cycle will reflect the change. ## Upgrading or downgrading Change plans at any time from the **Billing** page in the app. Upgrades take effect immediately; downgrades take effect at the end of your current billing cycle. When downgrading, be aware of the limits: * If you have more than 5 personas and downgrade to Indie, you'll need to delete some before you can create new ones. * Retention changes take effect immediately — tests older than 90 days on the new plan will age out. ## What's next * [Trial](/billing/trial) * [Credits](/billing/credits) * [Managing your subscription](/billing/subscription) # Managing your subscription Source: https://docs.percio.app/billing/subscription Upgrade, downgrade, billing portal, cancellation Manage everything about your plan from the **Billing** page. ## What's on the Billing page * Your current plan and billing cycle (monthly or annual). * Your credit balance and next reset date. * Your persona count and the limit for your plan. * A link to the **Billing portal** — the Stripe-hosted page where you update your card, download invoices, and see payment history. * Actions to **Upgrade**, **Downgrade**, or **Cancel**. ## Upgrading From Indie to Pro: **Upgrade** on the Billing page. The change takes effect immediately. Your next invoice is prorated so you're not double-charged. Upgrading gives you immediate access to Pro's higher limits — more personas, longer retention, and a higher credit allotment. ## Downgrading From Pro to Indie: **Downgrade** on the Billing page. The change takes effect at the **end of your current billing cycle** — you keep your Pro features until then. Things to watch for when downgrading: * **Personas.** If you have more than 5 personas on Pro and downgrade to Indie, you'll need to delete some before creating new ones. * **Test history retention.** When the downgrade kicks in, tests older than 90 days will start aging out. * **Credits.** Your next billing cycle uses the Indie allotment. ## Switching monthly ↔ annual Switch billing cycles from the Billing page. Switches take effect at the next renewal. Annual plans are billed upfront at a discount compared to paying monthly. ## The billing portal For anything related to payment itself — updating your card, changing your billing address, downloading invoices, checking payment history — use the **Billing portal** link. That opens Stripe's secure billing page with your full history. ## Cancelling Cancel from the Billing page. Cancellation: * Takes effect at the **end of your current billing cycle**. You keep full access until then. * Does not delete your account or your data. You can reactivate anytime. * Does not immediately delete your test history — that follows the normal retention rules until you either reactivate or your account is fully deactivated. See [Deactivation](/billing/deactivation) for what happens to your account after cancellation. ## Failed payments If a payment fails, Stripe retries on a schedule. You'll get email notifications. If all retries fail, your account is deactivated (same as a voluntary cancellation). Update your card in the billing portal and you can reactivate. ## What's next * [Plans](/billing/plans) * [Credits](/billing/credits) * [Deactivation](/billing/deactivation) # The Indie trial Source: https://docs.percio.app/billing/trial How the 14-day trial works The **Indie** plan includes a 14-day free trial. Pro does not. ## What's included in the trial * Full access to Indie plan features for 14 days. * The same credit allotment as a paid Indie subscription. * Full access to all test creation, personas, results, and agent functionality. ## Credit card required Starting the trial requires a valid credit card. Your card is not charged during the trial — it's charged automatically on day 15 unless you cancel first. ## One trial per account The Indie trial is **one-per-account**. It's consumed the first time you start it and is never reset, even if you: * Cancel before day 15. * Let the trial expire without upgrading. * Deactivate your account and return later. Once consumed, signing up again or returning to the plan will charge you from day one. ## What happens on day 15 If you haven't cancelled: * Your card is charged for the monthly or annual Indie plan (whichever you selected during trial signup). * Your access continues uninterrupted. If you cancelled during the trial: * Your access ends on day 14. * Your card is not charged. * Your account goes inactive (see [Deactivation](/billing/deactivation)). ## Cancelling during the trial Cancel from the **Billing** page at any point before the trial ends. Cancellation takes effect at the end of the trial, not immediately — you keep access until day 14. ## Upgrading from trial If Indie meets your needs, no action is required — day 15 rolls you into a paid plan. If you need Pro's higher limits, upgrade from the **Billing** page any time during the trial. ## What's next * [Plans](/billing/plans) * [Credits](/billing/credits) * [Managing your subscription](/billing/subscription) # Core concepts Source: https://docs.percio.app/core-concepts The vocabulary you'll see everywhere in Percio Before you go deeper, here's the vocabulary the rest of the docs uses. ## Test A single usability evaluation of a URL. A test has a **scenario**, a **persona**, and produces a **result**. Every test run consumes credits — see [Credits](/billing/credits). ## Scenario The task you want a persona to attempt. Good scenarios describe *what the user is trying to accomplish*, not step-by-step instructions. Examples: * "Find a pair of running shoes under \$120 and add them to the cart" * "Sign up for an account and post your first comment" * "Cancel an existing subscription" Bad scenarios are too vague ("explore the site") or too prescriptive ("click button X, then Y, then Z"). See [Writing good scenarios](/tests/writing-scenarios). ## Persona The lens Percio uses to evaluate your product. A persona has an occupation, a device context, a tech expertise level, focus areas, pain points, behavioral traits, priority Nielsen heuristics, and a full system prompt that governs how it interprets what it sees. Personas in Percio are either **created during onboarding**, **created by you** on the `/personas` page, or generated via the **Agent's MCP tools**. There are no generic built-in personas — every persona is specific to your product. See [Personas overview](/personas/overview). ## Flow The sequence of steps the browser actually took during a test — click here, type there, scroll down, navigate away. The flow is what the persona evaluates after the run is complete. ## Step One action inside a flow. Each step has: a screenshot captured before the action, the agent's reasoning, and the action it took (click, type, select, scroll, wait, navigate, complete, or abandon). Tests cap at **50 steps** by default in the agent (you can adjust with `--max-steps`). Tests can end early if the agent hits 3 consecutive failures, gets stuck below 50% progress, or decides the task is done. ## Issue A specific usability problem a persona found. Each issue has: * **Severity** (critical / high / medium / low) * **Nielsen heuristic** it violates * **What's happening** — the observed problem * **Why it matters** — the user impact * **Who it affects most** — when the issue hits some users harder than others * **Recommendation** — a concrete fix After a test, you can mark each issue **Confirmed**, **False positive**, or **Dismissed**. ## Heuristic A usability principle from Jakob Nielsen's 10 heuristics (visibility of system status, match between system and real world, user control, consistency, error prevention, recognition over recall, flexibility, aesthetic and minimalist design, help users recover from errors, help and documentation). Every issue ties to one so you know *why* it's a problem, not just *that* it's a problem. ## Credit The unit that meters test runs. Running a test costs credits — creating a persona in the web app does not. Your plan (Indie or Pro) determines how many credits you get per billing cycle. If you run out, new test runs are blocked until the next cycle or an upgrade. See [Credits](/billing/credits). ## Execution A single test run identified by an `executionId`. The live test page lives at `/test-running/[executionId]` and the final report lives at `/results/[executionId]`. You can share a results URL with teammates on your account. ## Report retention Results are kept for the lifetime of your plan window — **90 days on Indie**, **365 days on Pro**. After that they're deleted. If long-term archiving matters to you, export what you need before it ages out. ## What's next * [Creating a test](/tests/overview) * [Personas overview](/personas/overview) * [Reading results](/results/overview) # Introduction Source: https://docs.percio.app/introduction AI-powered usability testing for any website or app ## What is Percio Percio is an AI-powered usability testing platform. You point it at a URL, describe what a user would try to do, and pick a persona — Percio launches a real browser, navigates the site as that persona would, and returns a usability report grounded in Nielsen heuristics. A run gives you a usability score, an executive summary, issues with severity and recommendations, quick wins, biggest risks, drop-off patterns, and a full flow timeline of every step Percio took. ## Two ways to run Percio Paste a URL, answer a short conversation, watch the test run live, read the report. The fastest way to get started. Run tests against `localhost` from your terminal, or drive Percio from Cursor via MCP while you code. ## Start here Sign up and run your first test in under 5 minutes. The vocabulary you'll see everywhere: test, scenario, persona, credit, execution. Scenario quality is the single biggest lever for test quality. Start here. Install the CLI, authenticate, and run tests against `localhost`. ## How a test works 1. **You describe what to test.** A URL, a scenario (e.g. "Sign up for an account"), and a persona. 2. **Percio launches a real browser.** Playwright drives Chromium end-to-end, exactly as a user would. 3. **The agent navigates as your persona.** Each step: screenshot, decide, act. It can click, type, scroll, select, wait, and navigate. 4. **The persona evaluates the recorded flow.** Claude reviews every step through the persona's lens and surfaces issues tied to Nielsen heuristics. 5. **You get a report.** Usability score, executive summary, issues grouped by severity, and a step-by-step flow timeline. ## What's next * Run your first test → [Quickstart](/quickstart) * Understand the pieces → [Core concepts](/core-concepts) * Test `localhost` from your terminal → [Agent: install](/agent/install) # Creating personas Source: https://docs.percio.app/personas/creating-personas The conversational creation flow and every field explained Create personas on the **Personas** page by clicking **Create new**. The flow is conversational — describe the person you want in your own words, and Percio fills in the rest. You can then edit any field before saving. ## The conversation Start with a one-sentence description. Examples: * *"A 35-year-old bakery owner who uses Instagram on her phone to market her business."* * *"A technical buyer at a 200-person SaaS company evaluating our platform."* * *"A first-time mobile shopper who's never used a subscription service before."* Percio asks follow-ups — device usage, tech comfort, what they're trying to accomplish, what frustrates them. Answer in plain language. When it has enough, it generates the full persona and shows you the fields. ## Every field explained ### Name and emoji Used throughout the UI to identify the persona. A strong name and emoji make it easier to pick the right persona from the list and to scan past reports. ### Occupation The persona's job or role. This anchors the persona's worldview and the assumptions they bring to your product. Prefer specific ("Neighborhood bakery owner") over generic ("Small business owner"). ### Description A 2–3 sentence background. Short enough to read at a glance, rich enough to establish context. ### Main objective The persona's big-picture goal — what they're ultimately trying to accomplish that your product might help with. 30–200 characters. ### Device context The primary device and usage context. "Desktop during work hours" is different from "iPhone while commuting" — Percio uses this to interpret what's reasonable for the persona to do. ### Tech expertise A 1–5 scale: * **1** — struggles with anything beyond basic apps. * **2** — comfortable with familiar tools, cautious with new ones. * **3** — average consumer, figures things out with some effort. * **4** — comfortable with new software, explores UIs confidently. * **5** — power user, expects keyboard shortcuts and advanced features. ### Focus areas 3–5 things this persona pays attention to when evaluating a product. Examples: * "Clear pricing and no hidden costs" * "Speed — I don't have time to wait" * "Visual trust signals (reviews, security badges)" * "Mobile-first design" ### Pain points 2–4 frustrations this persona brings to every interaction. Examples: * "Gets impatient with long sign-up forms" * "Distrusts ambiguous CTAs" * "Hates when fixes require calling support" ### Behavioral traits 3–5 personality traits that govern how the persona reacts when something goes wrong. Examples: * "Abandons easily when confused" * "Reads every word before clicking" * "Skims headlines, ignores body copy" ### Priority heuristics The Nielsen heuristics this persona weights most heavily. A tech-anxious persona might over-index on **Help users recover from errors**; a power user might over-index on **Flexibility and efficiency of use**. ### System prompt The full prompt that governs how the persona evaluates a flow. Auto-generated from the other fields. You can edit it directly if you want total control. ## Saving Once the fields look right, save. The persona appears on your Personas page and is immediately available for test runs. ## Editing later Every field is editable after the fact. If reports from a persona feel off-target, tweak the focus areas, pain points, or behavioral traits — those have the biggest impact on what the persona flags. ## What's next * [Managing personas](/personas/managing-personas) * [Persona strategy](/personas/strategy) # Your first persona Source: https://docs.percio.app/personas/first-persona What Percio creates during onboarding and how to refine it When you sign up, Percio opens an onboarding wizard that generates your first persona. You don't start with a blank slate. ## What onboarding does The wizard asks a handful of questions about your product and your target users: * What does your product do? * Who's the primary user? * What device do they use most? * How technical are they? * What are they trying to accomplish? From those answers, Percio generates a persona with all the fields populated — name, occupation, tech level, focus areas, pain points, and a system prompt ready to evaluate your flows. ## Why this matters Your first persona is the one that runs your first test. If the onboarding answers are rushed or generic, the persona will be generic too, and your first report will feel vague. Spend two extra minutes on the onboarding questions. It pays back on every test. ## Reviewing and refining After onboarding, head to **Personas** and open your new persona. Review each field: * Does the **occupation** match the person you had in mind? * Do the **focus areas** cover what this persona would actually care about? * Do the **pain points** feel real, or generic? * Is the **tech expertise** right for this segment? Edit anything that feels off. You can tweak fields individually or rewrite the whole system prompt if you know what you want. ## Skipping or dismissing onboarding If you dismiss the onboarding wizard without completing it, you won't have a persona to run tests with. Open **Personas** → **Create new** to build one manually — same fields, no pressure to do it in one shot. ## When to create more One persona is enough to run your first test. For ongoing use, two to four personas that represent distinct segments of your audience is the sweet spot for most products. See [Persona strategy](/personas/strategy). ## What's next * [Creating personas](/personas/creating-personas) * [Persona strategy](/personas/strategy) # Managing personas Source: https://docs.percio.app/personas/managing-personas Editing, duplicating, and deleting personas Manage your personas on the **Personas** page. ## Editing Open any persona and edit any field — name, occupation, focus areas, pain points, traits, the full system prompt. Edits take effect immediately; future tests use the updated persona. Past test results are **not** re-evaluated when you edit a persona. A result is a snapshot of the persona at the time of the run. ## Duplicating The duplicate action makes a copy of a persona. Useful when: * You want to create a variant (e.g. the same persona on mobile instead of desktop). * You're about to experiment with changes and want to preserve the original. * You want a starting point for a new persona that's similar to one you already have. Duplicates start with `"Copy of "` prepended to the name — rename them before saving. ## Deleting Deleting a persona removes it from your account. Past test results that used the persona are preserved — the persona's name and key fields are embedded in the report. Deletion is permanent. If you're unsure, duplicate the persona and delete the copy, or deactivate its use by removing it from your rotation instead of deleting it. ## Persona limits * **Indie** — 5 personas * **Pro** — 10 personas If you're at the limit and want to add a new persona, delete or replace an existing one. ## What's next * [Persona strategy](/personas/strategy) * [Plans](/billing/plans) # Personas Source: https://docs.percio.app/personas/overview The lens Percio uses to evaluate your product A **persona** is how Percio views your product. Every test evaluates a recorded flow through one persona, and every issue in a report is tied back to that persona's perspective. ## Why personas matter Usability isn't universal. A checkout flow that feels natural to a frequent shopper can be confusing to a first-time visitor. A dashboard that works for a technical user can be alien to a non-technical one. Personas let Percio evaluate the same product from a specific perspective — so the issues it surfaces matter to the user you actually care about, not to a generic average. To cover more than one perspective, run separate tests with different personas and compare the reports. ## Where personas come from * **Onboarding generates your first persona.** When you sign up, Percio walks you through creating a persona tailored to your product. * **You create more on `/personas`.** The creation flow is conversational — describe the person you want and Percio fills in the rest. You can then edit every field. * **The agent MCP can create personas too.** If you're working in Cursor, you can use `chat_persona` + `create_persona` to build personas without leaving your editor. There are **no generic built-in personas**. Every persona on your account is specific to your product. ## What's in a persona Every persona has: * **Name and emoji** — for recognizability in the UI. * **Occupation and device context** — who they are and how they access your product. * **Tech expertise** — a 1–5 scale that shapes how the persona interprets affordances. * **Focus areas** — the 3–5 things this persona cares about when evaluating a product. * **Pain points** — 2–4 frustrations they bring to every interaction. * **Behavioral traits** — 3–5 traits that govern how they react when things go wrong. * **Priority heuristics** — the Nielsen heuristics this persona weights most heavily. * **Main objective** — their big-picture goal. * **System prompt** — the full prompt that governs how the persona evaluates a flow. Advanced users can edit this directly. ## Persona limits Plans cap how many personas you can keep on your account: * **Indie** — up to 5 personas * **Pro** — up to 10 personas Creating, editing, and deleting personas is free — only running tests consumes credits. ## In depth What the onboarding flow creates and how to refine it. The conversational creation flow and every field explained. Editing, duplicating, deleting. How many to keep, how to mix them, what makes a signal-rich set. # Persona strategy Source: https://docs.percio.app/personas/strategy How many to keep, how to mix them, and what makes a signal-rich set You have limited persona slots (5 on Indie, 10 on Pro). Here's how to get the most signal out of them. ## The core principle **Personas earn their slot by being different from each other.** Two personas who evaluate the same flow the same way use up a slot without adding insight. Aim for personas that would reliably disagree. ## A good starter set (3 personas) If you're running tests on a single product, this mix works for most cases: 1. **First-time visitor** — never used your product before, tech level 2–3, needs trust signals and clear copy. 2. **Core user** — the persona your product is built for, tech level 3–4, focuses on efficiency and completing their main job. 3. **Skeptical power user** — tech level 4–5, impatient, picks up on inconsistencies and missing shortcuts. These three contradict each other in useful ways. A feature that delights the power user may frustrate the first-timer; a change that clarifies things for the first-timer may feel patronizing to the power user. ## Expanding to a richer set (5 personas) On Indie, add: 4. **Mobile-only user** — accesses the product primarily on a phone. Surfaces responsive, touch-target, and small-screen issues. 5. **Persona specific to a segment you care about** — accessibility-focused user, international user, decision maker vs. end user for B2B, etc. ## Expanding on Pro (up to 10) With Pro's 10 slots you can cover: * Multiple device contexts (desktop, mobile, tablet). * Multiple expertise levels in the same role. * Multiple intent modes (researching, buying, using, troubleshooting). * Stakeholder personas for B2B (decision maker, end user, admin/buyer). Avoid creating "the same persona but slightly different." That's a sign the slot would be better spent on a genuinely different segment. ## When to rotate personas Personas aren't permanent. Rotate when: * A persona's reports feel repetitive across tests. * You've shipped fixes for the issues that persona used to catch. * Your product has shifted to a new audience. * You want to probe a new segment for a specific project. ## How to cover multiple perspectives Every test runs with a single persona. To evaluate the same flow through more than one lens, run separate tests with different personas and compare the reports side by side in your test history. A common workflow: * **Iterating on a flow:** run one test with the persona closest to the segment you're worried about. * **Standard review:** run the same scenario twice with two contrasting personas (e.g. first-timer vs. power user). * **Pre-launch or cross-functional review:** run three or more tests, each with a persona representing a different segment you want covered. Each test consumes credits. See [Credits](/billing/credits). ## What's next * [Creating personas](/personas/creating-personas) * [Picking a persona for a test](/tests/picking-personas) # Quickstart Source: https://docs.percio.app/quickstart Sign up, run your first test, and read the report — in about 5 minutes This walks you through your first Percio test using the web app. If you'd rather test `localhost` or wire Percio into Cursor, jump to the [Agent overview](/agent/overview). ## 1. Create an account Head to [percio.app](https://percio.app) and sign up with email or Google. Email sign-ups are confirmed via a link sent to your inbox — click it to finish creating your account. If you're picking the **Indie** plan, you'll start a 14-day trial (credit card required). **Pro** has no trial. See [Plans](/billing/plans) for the full comparison. ## 2. Create your first persona On first sign-in, Percio opens an onboarding wizard that generates a persona tailored to the product you're building. Answer a few questions about your users and you'll end up with a persona ready to run tests against. You can create more personas later on the **Personas** page. See [Creating personas](/personas/creating-personas) for the field-by-field walkthrough. ## 3. Start a test Go to **Tests** and paste the URL you want to test. Percio will: 1. **Fetch context from the page** so it knows what it's looking at. 2. **Ask a few quick questions** about what you want to test — what the user should try to do, what success looks like, any constraints. 3. **Generate a scenario** from that conversation. 4. **Let you pick a persona** to run the test through. When you hit **Run Test**, Percio launches a real browser on our servers and starts working. The quality of your scenario drives the quality of your report. See [Writing good scenarios](/tests/writing-scenarios) for the one-page guide that pays for itself. ## 4. Watch the test run You'll be taken to the live execution page. While the test runs, you can watch: * The **progress ring** showing how far along the agent thinks it is. * The **step timeline** — each action the browser takes (click, type, scroll, navigate, wait). * The **AI reasoning panel** — what the agent is thinking before each action, so you can see why it made every move. Most tests finish in 1–3 minutes depending on the flow. ## 5. Read your report When the run finishes, Percio drops you on the results page. You'll see: * A **usability score** from 0–100. * An **executive summary** with the biggest risk, drop-off patterns, and quick wins. * **Issues**, each with severity, the Nielsen heuristic it violates, and a four-part breakdown: *What's happening*, *Why it matters*, *Who it affects most*, *Recommendation*. * **Positive notes** — things the persona liked. * A **flow timeline** with every step the browser took, screenshot by screenshot. For each issue, you can mark it **Confirmed**, **False positive**, or **Dismissed** to keep your findings clean. ## What's next The single biggest lever for test quality. Which persona to use for a test and what makes a persona signal-rich. The full anatomy of the results page. Install the CLI and test unshipped work before it goes live. # Issues Source: https://docs.percio.app/results/issues Severity, Nielsen heuristic mapping, and the four-part issue card Issues are the core of every report. Each issue is a specific, actionable usability problem a persona found, with enough context for you to decide what to do about it. ## The issue card Every issue has the same structure: **Severity.** One of: * **Critical** — the persona couldn't complete the scenario, or the issue causes data loss, trust damage, or abandonment. * **High** — significant friction. The persona could finish, but with visible effort or frustration. * **Medium** — real usability problem, but not blocking. Worth fixing. * **Low** — polish. Wouldn't stop the persona, but detracts from the experience. **Heuristic.** The Nielsen heuristic the issue violates. One of the [10 heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/): * Visibility of system status * Match between system and real world * User control and freedom * Consistency and standards * Error prevention * Recognition rather than recall * Flexibility and efficiency of use * Aesthetic and minimalist design * Help users recognize, diagnose, and recover from errors * Help and documentation **What's happening.** The observed behavior. What the persona saw and what they did. Concrete, not abstract. **Why it matters.** The user impact. Why this specific behavior is a problem for this persona. **Who it affects most.** Sometimes the issue hits some users harder than others — a confusing label may be fine for a power user but crippling for a first-timer. This section names the audience most at risk. **Recommendation.** A concrete suggestion for how to fix it. Not always the *right* fix for your product — but a starting point that makes the conversation easier. ## How to use severity Severity is Percio's best judgment. It's calibrated for the persona running the test — a critical issue for a first-timer might be a medium for a power user. Use it as a starting point, not a tribunal. A good first pass on a report: 1. Read every **critical** and **high** issue. Decide which are confirmed, false positives, or dismissed. 2. Look for patterns across the **medium** issues — several mediums pointing at the same area often signal a larger problem. 3. Skim the **lows**. They're usually polish work that can wait. ## How to use the heuristic tag The heuristic tells you *why* the issue is a problem — which is what you need if you're explaining the issue to a teammate who wasn't in the room. Seeing the same heuristic flagged repeatedly across different parts of your product is a strong signal. Recurring **Consistency and standards** violations suggest a design system gap. Recurring **Error prevention** violations suggest your forms and state transitions need attention. Recurring **Match between system and real world** violations suggest your copy is speaking a different language from your users. ## Comparing reports across personas To get another angle on the same flow, run a second test with a different persona. A first-timer and a power user rarely raise the same issues — the contrast is where a lot of the signal lives. Comparison is done by reading both reports side by side in your test history; Percio doesn't fold multiple persona reports into a single view. ## What's next * [Validating issues](/results/validation) # Reading results Source: https://docs.percio.app/results/overview The anatomy of the Percio results page When a test finishes, Percio drops you on `/results/[id]` — the full report. Here's what's on it. ## The animated interstitial Before the report renders, Percio plays a short "Analyzing your experience" animation (\~3.5 seconds). This isn't cosmetic — results sometimes finish processing in the background, and the interstitial gives the final payload time to settle. ## The page, top to bottom **Header.** Test name, URL, date, and the status chip (completed / failed). If the test is older than your retention window, the content is already gone. **Usability score.** A single number from 0–100 calculated from the severity of the issues found. See [Usability score](/results/usability-score). **Executive summary.** A brief narrative of what happened: the biggest risk, the drop-off patterns Percio observed, and the quick wins it recommends. See [Executive summary, risk, and quick wins](/results/summary). **Issues.** Everything the persona flagged. Each issue has a severity chip, a Nielsen heuristic tag, and four sections: *What's happening*, *Why it matters*, *Who it affects most*, and *Recommendation*. See [Issues](/results/issues). **Positive notes.** Things the persona liked. Easy to skim past, but worth reading — they tell you what's working. **Flow timeline.** Every step the browser took, with screenshots and the agent's reasoning. Collapsible. See [Flow timeline](/results/flow-timeline). ## What you can do with an issue Each issue has three actions: * **Confirmed** — you agree this is a real issue. * **False positive** — the persona flagged something that isn't actually a problem. * **Dismissed** — you've seen it and don't want to act on it. These don't delete the issue — they annotate it. See [Validating issues](/results/validation). ## Sharing results A results page URL is private to your account. Anyone signed in on the same account can open it. There's no public sharing link today. ## Retention Results live for the lifetime of your plan's retention window — **90 days on Indie**, **365 days on Pro**. Older results are deleted. Export what you need before it ages out. ## In depth How the number is calculated. Biggest risk, drop-off patterns, quick wins. Severity, heuristics, the four-part card. Confirmed, false positive, dismissed. Every step the browser took, with screenshots. # Executive summary, biggest risk, drop-off patterns, and quick wins Source: https://docs.percio.app/results/summary The narrative section at the top of every report Below the usability score, Percio generates a narrative summary of the run. It's structured into four parts and is designed to be the section you show your team in a review. ## Executive summary A 2–4 sentence overview of how the test went. What the persona was trying to do, how it went, and the headline takeaway. Read this first — it frames everything else in the report. ## Biggest risk The single issue Percio considers the most dangerous for your product. It's often (but not always) the most severe issue — Percio weighs severity alongside how central the issue is to the flow. If the biggest risk is something you can fix quickly, do that before running the next test. If it's a deeper structural problem, use it as ammunition to prioritize the work. ## Drop-off patterns Where the persona got stuck, hesitated, or almost abandoned. This is the section most connected to your conversion funnel — drop-off patterns in the usability test map directly to drop-off patterns you'd see in real analytics. Common drop-off patterns Percio surfaces: * Decision paralysis on choice-heavy pages. * Confusion at state transitions (e.g. "I don't know what this page is for"). * Implicit expectations the product doesn't meet (e.g. expected a confirmation email, didn't receive one). * Trust anxiety at high-stakes moments (payment, account creation, irreversible actions). ## Quick wins Small, high-leverage changes Percio thinks would improve the experience significantly. Quick wins are characterized by being: * **Cheap to implement** — copy changes, button labels, reordering, removing friction. * **Directly observed** — tied to something the persona actually struggled with, not hypothetical. * **High-impact** — fixing them would meaningfully change the persona's experience. Treat quick wins as a shortlist of things to try between now and the next test. ## How the summary is generated Every part of the narrative is produced by Claude after it's seen the full flow and issues — it's not pulled from a template. That means the language reflects your specific product and scenario, but also that wording can vary run-to-run. Comparisons across runs should be done on the issues list and score, not on summary text alone. ## What's next * [Issues](/results/issues) * [Validating issues](/results/validation) # Usability score Source: https://docs.percio.app/results/usability-score What the 0–100 score means and how it's calculated Every Percio report leads with a **usability score** between 0 and 100. It's designed to be directional, not absolute — a fast signal to tell you whether a flow is in good shape or needs work. ## How it's calculated The score is derived from the severity of the issues a test found. Issues at higher severities (critical, high) pull the score down more than lower-severity issues (medium, low). Positive notes don't increase the score — they provide context, not credit. The score is specific to the persona who ran the test. A flow can score 90 for a power user and 55 for a first-timer — comparing two reports is how you see that contrast, not combining them into one number. ## How to read the number * **85–100** — strong flow. Most issues are minor and tactical. * **65–84** — solid flow with real issues to address. Ship the fixes in the next cycle. * **40–64** — significant usability problems. Worth prioritizing above most new work. * **Below 40** — the flow is broken for at least one persona. Treat as a blocker. These bands are guidelines, not guarantees. A score of 70 on an early-stage prototype is different from a 70 on a mature production flow — context matters. ## What the score doesn't capture * **Aesthetic quality.** Percio evaluates usability, not brand or visual polish. * **Performance.** If the flow was slow but eventually worked, that may not show up in the score. * **Success rate.** A persona that *completed* the scenario will still score lower if it hit real issues along the way. * **Business metrics.** Usability affects conversion, retention, and support load — but Percio can't measure those directly. ## Comparing scores across runs Two runs of the same scenario and the same persona on the same product are roughly comparable. Runs with different personas, different scenarios, or against different products are not — don't compare a landing page score to a checkout flow score. ## What's next * [Executive summary](/results/summary) * [Issues](/results/issues) # Validating issues Source: https://docs.percio.app/results/validation Confirmed, false positive, dismissed Percio's issues are generated by an AI reviewing a browser flow. It's accurate much of the time, but not always. The validation actions let you annotate each issue so your report reflects what your team actually agrees with. ## The three states Every issue has three actions in the UI: **Confirmed.** You agree this is a real issue. Use this when the issue matches a real user problem you recognize or plan to fix. **False positive.** The persona flagged something that isn't actually a problem for your product. Maybe it misread the UI, maybe it applied a heuristic that doesn't apply, maybe it hallucinated a detail. **Dismissed.** You've seen it, you don't disagree, but you don't plan to act on it. Could be "we know, it's on the roadmap" or "not important right now." Issues start unvalidated. Validating is optional but recommended — it keeps reports useful over time and gives you a filter when you come back to the report later. ## Why validate * **Filters noise.** Future you (or a teammate) can focus on confirmed issues. * **Tracks what's been triaged.** Dismissed and false-positive issues are no longer on your plate. * **Calibrates your understanding of the persona.** If a persona produces lots of false positives, it may need tuning (see [Creating personas](/personas/creating-personas)). ## Validation is per issue Each issue is validated on its own. Validation lives with the specific report — if you run the same scenario again (even with the same persona) and a similar issue comes back, you'll validate it again in the new report. ## Changing your mind You can toggle the validation state at any time. Marked something false positive that turned out to be real? Flip it back. ## Validation does not delete issues Validation annotates — it doesn't remove. All issues stay in the report regardless of their validation state so you can always see what Percio originally found. ## What's next * [Issues](/results/issues) * [Flow timeline](/results/flow-timeline) # Account & settings Source: https://docs.percio.app/settings Profile, password, theme, and deleting your account Manage your account from the **Settings** page in the sidebar. ## Profile * **Email** — the address you sign in with. * **Name** — how you're referred to in the UI. Changes save immediately. ## Password * **Reset password** sends a password-reset email to your account's address. * If you signed up with Google, you won't have a password by default — you can set one from here if you want email + password as an alternative sign-in method. ## Theme Toggle between **Light**, **Dark**, and **System** themes. The setting applies to every surface of the web app. ## Plan Shows your current plan. Plan changes happen on the **Billing** page — see [Managing your subscription](/billing/subscription). ## Deleting your account The **Delete account** action triggers the deactivation flow — see [Deactivation](/billing/deactivation). Your data is preserved and you can reactivate later. For permanent, non-reversible deletion, contact Percio support. Deleting your account ends your subscription, cancels any trial, and revokes your API keys. You lose access immediately. ## API keys API keys for the agent are managed on the **Integrations** page, not **Settings**. See [Authenticate](/agent/authentication). ## What's next * [Plans](/billing/plans) * [Deactivation](/billing/deactivation) # Test history Source: https://docs.percio.app/test-history Browse, search, and filter every test on your account The **Test history** page lists every test run on your account within your plan's retention window. Find it in the sidebar. ## The table Each row is one test and shows: * **Test name and URL** — with a favicon of the target domain. * **Date** — when the test was run. * **Status** — completed or failed. * **Usability score** — the 0–100 number. * **Issue badges** — the count of issues by severity. Click a row to open the full results page. ## Search and filters * **Search** — by test name or URL. * **Status filter** — all, completed only, failed only. * **Sort** — newest, oldest, highest score, lowest score, most issues. ## Pagination The table paginates with a configurable page size. Deeper history loads on demand. ## Retention Results are kept for the lifetime of your plan's retention window: * **Indie** — 90 days * **Pro** — 365 days After that, test results are deleted. Plan-window expiration applies regardless of whether the test was viewed or validated. If a test has aged out, the row will either disappear or show a clear "deleted" state depending on timing. To preserve findings long-term, copy the key takeaways into your team's source of truth before they expire. ## Failed tests Tests that errored before completing still appear in history, usually with enough context to tell you why. Common causes: * The URL wasn't reachable. * The browser crashed. * The test hit the step ceiling without reaching a conclusion. * The persona couldn't evaluate the flow (very rare — usually a malformed scenario). Failed tests don't count against your credit balance in most cases. ## What's next * [Reading results](/results/overview) * [Troubleshooting](/troubleshooting) # The conversation flow Source: https://docs.percio.app/tests/conversation-flow How Percio turns a URL into a ready-to-run test In the web app, every test starts as a conversation. Here's what happens between "paste URL" and "Run Test." ## Step 1 — Paste the URL On the **Tests** page, paste the URL you want to test. This can be any publicly reachable page: your homepage, a specific feature, a landing page, a checkout flow, anything. The web app needs to be able to reach the URL from our servers. To test `localhost` or any internal URL, use the [agent CLI](/agent/overview) instead — it runs the browser on your machine. ## Step 2 — Percio scrapes page context As soon as you submit the URL, Percio fetches a lightweight representation of the page: the title, visible headings, key actions, and structural hints. This grounds the rest of the conversation so Percio's questions are specific to your product rather than generic. You don't see the scrape happen — just a brief loading state and then the chat opens. ## Step 3 — The Q\&A Percio asks 2 to 5 short questions to understand what you actually want to test. Typical questions: * "What is the goal you want the user to complete?" * "Is there a specific segment of user you're worried about?" * "Are there any known constraints — sign-in required, feature flags, limited inventory?" * "What does success look like for you?" Answer in your own words. The tone is conversational — you're not filling out a form. ## Step 4 — Scenario generation When Percio has enough, it generates a **scenario**: a clear, actionable description of the task the persona will attempt. Something like: > *"As a first-time visitor, find a pair of running shoes under \$120, add them to the cart, and proceed to checkout."* You'll see the scenario before the test runs. If it doesn't match what you meant, say so in the chat — Percio will refine it. ## Step 5 — Persona selection Once the scenario is locked in, you pick **the persona** to run the test through. Your onboarding persona is available by default. Any personas you've created on `/personas` show up in the same picker. See [Picking a persona](/tests/picking-personas). ## Step 6 — Run Hit **Run Test**. Percio checks you have enough credits, kicks off a server-side execution, and takes you to the live view at `/test-running/[executionId]`. ## Editing mid-test You can't change the scenario once a test is running — the execution runs to completion (or abandons itself early; see [Live execution](/tests/live-execution)). If something's wrong, stop the run and start over. ## What's next * [Writing good scenarios](/tests/writing-scenarios) * [Picking a persona](/tests/picking-personas) * [Live execution view](/tests/live-execution) # Credits and what a test costs Source: https://docs.percio.app/tests/credits How Percio meters test runs and what to do when you run low Percio uses credits to meter test runs. This page covers what consumes credits, what doesn't, and how to avoid getting blocked mid-session. ## What consumes credits * **Running a test** costs credits per run. ## What's free * **Creating a persona** in the web app — free. * **Editing, duplicating, or deleting a persona** — free. * **Viewing past test results** within your retention window — free. * **Browsing `/test-history`** — free. ## When you hit the limit If you try to run a test without enough credits, Percio shows an **Insufficient credits** dialog before any browser work starts — you don't get charged for a blocked attempt. The dialog points you at your plan and the upgrade flow. ## How to see your balance Open the **Billing** page. Your current credit balance and plan are shown at the top, along with when credits reset. ## Avoiding surprises * **Nail the scenario before rerunning.** A well-written scenario gets more signal per credit than a vague one. * **Only rerun when you've changed something.** Rerunning the same scenario with the same persona on the same build rarely produces new insight — spend the credit after you've shipped a fix or want a different persona's take. * **Watch the balance on long iteration days.** Percio shows the balance on the test creation page. ## Credits by plan * **Indie** — a monthly allotment suitable for solo founders and small teams iterating on a single product. * **Pro** — a higher allotment plus longer retention and more personas. See [Plans](/billing/plans) for the full comparison. ## What's next * [Plans](/billing/plans) * [Managing your subscription](/billing/subscription) # Watching a test run Source: https://docs.percio.app/tests/live-execution The progress ring, step timeline, and AI reasoning panel When you hit **Run Test**, Percio takes you to `/test-running/[executionId]` — the live view of the run. ## What you see **Progress ring.** A circular indicator that estimates how far along the agent is. It's based on the agent's self-assessment of scenario completion, so it can move in both directions — a step that reveals new complexity can drop progress. **Step timeline.** Every action the browser has taken, in order, with the screenshot captured before each step and the action that followed. Click any step to expand its detail. **AI reasoning panel.** The agent's thoughts before each action: what it's trying to do, what it sees on the page, and why it picked the action it did. This is the most useful panel for understanding whether Percio is interpreting your scenario correctly. **Phase indicator.** Shows which high-level phase Percio is in — navigating, executing the flow, or analyzing. ## What Percio is doing under the hood Each step: 1. Capture a screenshot of the current viewport. 2. Serialize the page into a simplified representation the agent can read. 3. Send that + the step history + your scenario to the agent. 4. The agent returns a single action: click, type, select, scroll, wait, navigate, complete, or abandon. 5. Execute the action via a real browser. 6. Repeat. Every five steps or so, Percio evaluates whether the task looks complete and decides whether to continue. ## When a test stops A test ends when any of these happens: * **The agent decides it's complete.** The scenario goal has been reached. * **The agent decides to abandon.** The task appears unreachable from the current state. * **Stuck below 50% progress after 15 steps.** A safety net to stop drifting runs. * **The step ceiling.** Default 50 steps. When the run ends, the selected persona evaluates the full recorded flow and produces issues. Then you're redirected to the results page. ## Can I cancel a test? Yes — there's a cancel control on the live view. Cancelled tests do not produce a report. ## What's next * [Reading results](/results/overview) * [Troubleshooting: "My test was abandoned"](/troubleshooting) # Creating a test Source: https://docs.percio.app/tests/overview How to go from a URL to a finished usability report Tests in the web app are created through a guided conversation. Paste a URL, answer a few questions, pick a persona, and run. ## The short version 1. Go to **Tests**. 2. Paste the URL you want to test. 3. Percio scrapes page context so it understands what it's looking at. 4. Answer 2–5 quick questions about what you want to test. 5. Review the generated scenario. 6. Pick a persona. 7. Hit **Run Test**. ## What you'll need * **A reachable URL.** Production, staging, or a public preview link all work in the web app. To test `localhost` or URLs behind your dev machine, use the [agent CLI](/agent/overview) instead. * **A clear goal.** Even a rough sentence is enough to start. Percio's conversation will help sharpen it. * **A persona.** Your onboarding persona works for a first run. To cover different segments, create additional personas and run separate tests against them. * **Credits.** Each test run consumes credits. If you're low, Percio shows an **Insufficient credits** dialog before the run starts. ## In depth Exactly how the Q\&A works and what each step does. The highest-leverage skill for getting useful reports. How to choose the right persona for a test. What a test costs and how to avoid running out. The progress ring, step timeline, and reasoning panel. # Picking a persona for a test Source: https://docs.percio.app/tests/picking-personas How to choose the right persona and what makes each test signal-rich Every test runs with one persona. The persona decides *how* the recorded flow is evaluated — which affordances feel natural, which copy reads clearly, which moments create friction. ## How persona selection works On the test creation page, after the scenario is generated you'll see every persona on your account. Pick the one whose perspective matters for this test. Percio will launch the browser once, then that persona reviews the steps through its own lens. If you want a second perspective on the same flow, run another test with a different persona — the scenario is easy to reuse and findings can be compared side by side in the test history. ## Choosing the right persona Match the persona to the question you're asking: * **Validating a new sign-up or onboarding flow?** Use a first-time visitor. * **Testing an advanced feature or keyboard-driven workflow?** Use a power user. * **Checking a mobile experience?** Use a mobile-context persona. * **Evaluating a B2B decision flow?** Use a decision maker or buyer persona. A persona whose focus areas and pain points line up with the scenario will produce the sharpest report. ## Running the same scenario through different personas The highest-signal workflow is usually: 1. Run the test with one persona. 2. Read the report. 3. If you want another viewpoint (a different segment, a different device, a different expertise level), run another test with that persona on the same URL and scenario. Different personas reliably surface different issues — a first-timer flags onboarding gaps, a power user flags missing shortcuts. You see the contrast by comparing the two reports, not by running them in a single test. ## Persona limits Plans cap the **number of personas you can have** on your account: * **Indie** — 5 personas * **Pro** — 10 personas Creating personas in the web app is free. Only running tests consumes credits. See [Credits](/billing/credits). ## What if I don't have the right persona? Create a new one. The persona creation modal walks you through it conversationally. See [Creating personas](/personas/creating-personas). ## What's next * [Creating personas](/personas/creating-personas) * [Persona strategy](/personas/strategy) # Writing good scenarios Source: https://docs.percio.app/tests/writing-scenarios The single biggest lever for getting useful reports Scenario quality drives report quality more than any other input. Here's how to write ones that produce useful findings. ## What a good scenario looks like A good scenario describes **what the user is trying to accomplish**, leaves the *how* to the persona, and gives Percio enough context to know when the task is complete. ```text Good theme={null} Find a pair of running shoes under $120, add them to the cart, and proceed to checkout. ``` ```text Good theme={null} Sign up for an account, confirm your email, and post your first comment on any article. ``` ```text Good theme={null} Cancel an existing monthly subscription, assuming you're already signed in. ``` Each of these: * States a clear goal. * Implies the criteria for success (reaching a specific page, seeing a confirmation). * Leaves the path open — the persona can explore and get stuck in ways that surface real usability issues. ## What bad scenarios look like ```text Too vague theme={null} Explore the site. ``` ```text Too prescriptive theme={null} Click the red button in the top right. Then click "Sign up." Then type your email into the first field. Then click "Next." ``` ```text Ambiguous success theme={null} See if the checkout works. ``` * **Too vague** gives the persona nothing to evaluate. The report will be generic. * **Too prescriptive** turns the test into a script instead of a usability evaluation. You'll learn nothing about where real users would get stuck. * **Ambiguous success** leaves Percio unable to decide when it's done — it may wander, abandon early, or declare a flawed run complete. ## The three rules 1. **State the goal, not the steps.** "Buy a blue shirt" is better than "click this, then that." 2. **Give enough context to know when it's done.** Does success mean landing on a thank-you page? Seeing a confirmation? Getting an email? 3. **Match the scenario to the persona.** A "power user" scenario shouldn't be the same as a "first-time visitor" scenario — see [Picking a persona](/tests/picking-personas). ## Useful context to include Anything Percio can't infer from the URL belongs in the scenario: * **Sign-in state.** "Assume you're already signed in" or "you do not have an account yet." * **Inventory or state constraints.** "The cart is empty." "You have one unread notification." * **Feature flags or hidden entry points.** "The new onboarding is behind the `?v=2` query param." * **Time or region constraints.** "You're shopping from the US." "It's the middle of business hours." * **Prior actions.** "You just received a payment failure email." ## Scenario anti-patterns * **Multiple unrelated goals in one scenario.** Run separate tests — you'll get cleaner findings. * **Tasks that require credentials Percio doesn't have.** If sign-in is required, either pre-authenticate on a staging environment where the flow is open, or scope the scenario to the signed-out experience. The agent CLI supports more flexibility here. * **Scenarios that depend on external services.** Third-party OAuth, payment providers in test mode with strict requirements, and email verification can all block the agent if they're in the critical path. Call them out explicitly or scope around them. ## Iterating on a scenario If your first report reads as generic or off-target, the scenario is almost always the culprit. Treat scenario writing as an iterative skill — each run teaches you how to be more specific the next time. ## What's next * [Picking a persona](/tests/picking-personas) * [Reading results](/results/overview) # Troubleshooting Source: https://docs.percio.app/troubleshooting Common problems and how to fix them For CLI and MCP issues, see [Agent troubleshooting](/agent/troubleshooting). This page covers the web app and general Percio issues. ## "My test was abandoned" A test abandons when the agent decides it can't complete the scenario. Common causes: * **Three consecutive failed actions.** The agent tried to do something three times in a row without success. * **Stuck below 50% progress after 15 steps.** A safety net to stop drifting runs. * **Hit the step ceiling.** Default 50 in the agent; the web app has its own cap. To fix: * **Check the flow timeline** — the last few steps usually show what tripped the agent up. * **Dismiss cookie banners / modals in the scenario.** Include "dismiss any cookie banners that appear" explicitly if they're blocking. * **Sharpen the scenario.** "Buy something" is too vague; "Add a specific product from the running shoes category to the cart" is testable. See [Writing good scenarios](/tests/writing-scenarios). ## "Percio can't reach my URL" The web app's browser runs on our servers and needs network access to your URL. * **Authentication walls.** If the URL requires sign-in, the agent can't get past it. Either test signed-out flows, or use a staging environment with the auth removed. * **Staging / internal URLs.** If the URL is only reachable from inside your company network, Percio can't see it. Use the [agent CLI](/agent/overview) to run the test from your own machine. * **`localhost`.** The web app can't reach your local machine. Use the CLI: `percio test --url http://localhost:3000 --flow "..."`. * **IP allowlists.** If your staging environment allowlists specific IPs, Percio's server IP needs to be on the list. ## "I ran out of credits mid-month" Credits reset at the start of each billing cycle. Options: * **Upgrade to Pro** for a higher monthly allotment. * **Wait for the reset.** Your Billing page shows when the next reset happens. * **Be more selective.** Only rerun a scenario when you've changed something — a fix, a different persona, a tightened scenario. Repeating the same run on the same build rarely produces new insight. See [Credits](/billing/credits). ## "Results don't match what I expected" Almost always a scenario problem. Read [Writing good scenarios](/tests/writing-scenarios). Quick checks: * Is the scenario **specific enough**? Generic scenarios produce generic reports. * Did the **right persona** run the test? A first-timer's report will differ sharply from a power user's. * Did the agent actually **test what you wanted**? The flow timeline shows exactly what the browser did. If it never reached the feature you care about, the scenario needs to steer it more directly. ## "I can't find an old test" Test results age out of retention: * **Indie** — 90 days * **Pro** — 365 days If a test is older than your retention window, it's been deleted. Upgrading to Pro doesn't restore already-deleted results — the policy applies going forward. ## "A persona keeps raising false positives" Tune the persona. On the Personas page, open the persona and adjust: * **Focus areas** — too broad? Narrow them. * **Pain points** — are they accurate for this segment, or generic? * **Behavioral traits** — does the persona react the way you'd expect this user to react? Small changes to the persona have large effects on what it flags. ## "I accidentally deleted a persona" Personas can't be recovered after deletion. Past test results that used the persona are still viewable (the persona's details are captured in the report). To keep something similar going forward, recreate it — the [creation flow](/personas/creating-personas) is quick. ## "I forgot my password" Use the **Forgot password** link on the sign-in page. A reset email goes to your account's address. If you signed up with Google, you don't have a password — use Google sign-in. You can optionally set a password from **Settings** if you want email + password as an alternative. ## Where to get help * Check [Core concepts](/core-concepts) if the terminology is the confusion. * Check [Agent troubleshooting](/agent/troubleshooting) for CLI or MCP issues. * Contact Percio support for anything else, with your test id or the specific error you're seeing.