# `webtest-ai run`

Runs one Markdown suite file or a directory of suite files through the WebTest AI parser, interpreter, execution driver, and reporters.

```bash
webtest-ai run --suite specs/webtest-ai-demo.md
webtest-ai run --suite specs --tags smoke
webtest-ai run --suite specs --exclude-tags serial --workers 4
```

## Flags

- `--suite <path>`: Markdown suite file or directory. Defaults to `specs/`.
- `--config <path>`: JSON config path. Defaults to `webtest-ai.config.json`.
- `--browser <name>`: browser override. Supported aliases are `chromium`, `chrome`, `google-chrome`, `edge`, `msedge`, `firefox`, `webkit`, and `safari`.
- `--tags <a,b>`: runs tests containing all listed tags.
- `--exclude-tags <a,b>`: skips tests matching any listed tag.
- `--workers <n>`: runs parallel-safe tests concurrently. Tests tagged `serial` remain serial.
- `--headed`: opens a visible browser.
- `--debug`: opens Playwright Inspector before execution.
- `--refresh-auth`: ignores reusable auth state and creates a fresh session when the suite uses auth.
- `--auth-profile <name>`: overrides the auth profile used for reusable sessions.
- `--profile fast|ci|debug`: applies a runtime profile overlay before other run flags.
- `--trace <mode>`: overrides trace capture, for example `off`, `on`, `always`, or `retain-on-failure`.
- `--screenshot <mode>`: overrides screenshots, for example `off`, `always`, or `only-on-failure`.
- `--quality off`: disables a11y and vitals checks for this run.
- `--journey <mode>`: captures journey snapshots with `navigation` or `step`; use `off` to disable.

## Output

The command prints suite counts, status counts, run ids, and report paths. JSON and HTML reports are written under `artifacts/reports/`; per-test artifacts are written under `artifacts/<runId>/<testId>/`.

The process exits non-zero when any final test result is `failed`.