> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percio.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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-<timestamp>.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)