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

# percio 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 <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 <url>`           | Target URL to test. Supports `localhost` and any valid URL.                    | *required*        |
| `-f, --flow <task>`         | Scenario for the persona to attempt. Omit to run the interactive conversation. | *none*            |
| `-p, --persona <preset>`    | Local persona preset: `casual`, `professional`, or `power`.                    | `casual`          |
| `--persona-id <uuid>`       | Cloud persona UUID (from `percio personas list`). Overrides `--persona`.       | *none*            |
| `--max-steps <number>`      | Maximum steps before the agent stops.                                          | `50`              |
| `--viewport <WIDTHxHEIGHT>` | Browser viewport. Bounds: 320–3840 × 240–2160.                                 | `1280x800`        |
| `--headless`                | Run the browser in headless mode.                                              | `false` (visible) |
| `--timeout <seconds>`       | Overall test timeout.                                                          | *no limit*        |
| `-o, --output <path>`       | Write JSON results to disk.                                                    | *none*            |
| `-v, --verbose`             | Print detailed step-by-step output to the terminal.                            | `false`           |
| `-c, --config <path>`       | 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)