# Run

**Help URL:** `/forms/run`

## Purpose

Select one or more generated tests from the repository and trigger a Playwright run via GitHub Actions.

## Quick Start

1. Confirm **Site URL** (defaults to the repository homepage).
2. (Optional) Pick **Browser** and **Viewport**.
3. Select tests in the **Tests picker**.
4. Click **Start** to dispatch `run-tests-v1.yml`.

## How Runs Work

* TestVibe dispatches the GitHub Actions workflow `run-tests-v1.yml` in your project repository.
* Workflow inputs include:
  * `tests`: a comma-separated list of selected test file paths
  * `site_url`: the "Site URL" field from the form
  * `status_webhook`: `https://<your-testvibe-host>/api/run-status` (used for live status callbacks)
* After dispatch, TestVibe loads the latest workflow run and initializes a persistent live-status session for it.

## Selecting Tests

* **All tests**: by default, the form can pre-select all leaf tests.
* **Group selection**: a group can be preselected (for example from elsewhere in the app).
* **Direct selection**: selecting a single test runs only that test.
* The form also supports "best-effort" selection by a selector string (used by the [Assistant](/reference/forms/assistant.md) tool integrations).

## Configuration, Browser, and Viewport

TestVibe supports Playwright configurations stored in the repository:

* Use **Select config** to open [PlaywrightTestConfiguration](/reference/forms/playwright-test-configuration.md).
* The **Browser** and **Viewport** fields on this form are treated as "simple overrides":
  * They are persisted back into the selected Playwright config (best-effort) so future runs can reuse them.
  * The workflow itself is driven by the repository's Playwright configuration; these fields are not currently sent as explicit workflow inputs.

If you need deeper config options (headers, proxy, tracing, reporters, web server), use [PlaywrightAdvancedOptions](/reference/forms/playwright-advanced-options.md).

## Device Profiles (Viewport Presets)

When prefilled (for example by the [Assistant](/reference/forms/assistant.md)), device profiles map to viewports:

* `mobile-portrait` -> `390x844`
* `mobile-landscape` -> `844x390`
* `tablet` -> `820x1180`
* `desktop-1080p` -> `1920x1080`

## Troubleshooting

* "Select at least one test": choose one or more tests in the picker before clicking **Start**.
* Live status not updating: confirm your TestVibe instance is reachable at the run's `status_webhook` URL (`/api/run-status`).
* Wrong site under test: update **Site URL** and restart the run.

## Notes

* TestVibe shows a short guided tour for this form once per browser (cookie `testvibe.tour.run`).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/reference/forms/run.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.