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

# Validation workflows

> Choose between test runs, sandboxes, and PR checks

Arga has three validation workflows:

* **Test Runs** execute a browser test against a live URL.
* **Sandboxes** deploy a branch into an isolated preview environment.
* **PR Checks** run validation automatically or manually for repository changes.

Other sidebar items are supporting primitives. **Tests** are saved browser-test definitions, **Scenarios** are reusable twin seed data, and **Twins** provisions service doubles without running validation by itself.

## Which validation workflow should I use?

| I want to...                                                  | Use in the web app      |
| ------------------------------------------------------------- | ----------------------- |
| Run a browser test against a live URL and watch it execute    | [Runs](#test-runs)      |
| Deploy a branch into a preview environment with service twins | [Sandboxes](#sandboxes) |
| Validate PRs or branch pushes with repository-aware checks    | [PR Checks](#pr-checks) |

<CardGroup cols={3}>
  <Card title="Test Runs" icon="flask" href="#test-runs">
    Start a live browser run from a prompt and URL, then watch frames, events, and editable blocks.
  </Card>

  <Card title="Sandboxes" icon="cube" href="#sandboxes">
    Deploy a branch into an isolated preview environment with service twins.
  </Card>

  <Card title="PR Checks" icon="git-pull-request" href="#pr-checks">
    Validate repository changes and publish results back to GitHub.
  </Card>
</CardGroup>

***

## Validation Workflows

<a id="url-run" />

<a id="runs" />

### Test Runs

Use **Runs** when you have a live URL and want Arga to create or execute a browser test. This is the web UI equivalent of `arga test-runner runs url`, but with a live browser, event stream, chat, and editable blocks.

<Info>
  **Free plan users:** Runs are available on the Free plan. You must provide a test prompt describing what to validate. Free plan runs are limited to 1 digital twin per run and 10 runs per month. See [Plans and limits](/plans).
</Info>

**From the web app:**

1. Open **Runs** in the **Test Runner** section of the sidebar.
2. Enter the starting URL.
3. Describe the browser flow to test, such as `sign in and complete checkout`.
4. Click **Start test**.
5. Watch the live browser frame, run events, and generated blocks.
6. Edit blocks or parameters as needed, then rerun or save the run as a test.

Runs are block-based. A run can include navigation, click, type, key press, wait, assertion, and ask-user blocks. Arga also streams browser frames while the run is active, so you can inspect what the runner sees.

In the CLI, use `arga test-runner runs url`. See the [CLI mapping](#cli-mapping) below for examples.

<a id="sandbox-run" />

### Sandboxes

Use **Sandboxes** to deploy a branch into an isolated preview environment with service twins. This is the preview-environment workflow: choose a repository and branch, pick twins, deploy, and then use the resulting URL for manual inspection or test execution.

<Note>Sandboxes require a Team or Paid plan.</Note>

**From the web app:**

1. Open **Sandboxes** in the **Previews** section of the sidebar.
2. Choose the repository and branch to deploy.
3. Select service twins to provision alongside the preview.
4. Start the deployment.
5. Open the preview URL when the environment is ready.

Sandboxes are useful when you want a fresh environment before running a saved test, reproducing a bug, or testing with API twins without waiting for a PR trigger.

For monorepos or non-root Dockerfiles, add `.arga/sandbox.yml` to the repo. See [Sandbox configuration](/features/sandbox-config).

In the CLI, use `arga previews sandboxes run`. See the [CLI mapping](#cli-mapping) below for examples.

<a id="pr-run" />

### PR Checks

Use **PR Checks** to configure automatic validation for pull requests or branch pushes. PR Checks deploy the services touched by a change into a deterministic sandbox, wire unchanged services to production, swap external integrations for API twins, and run tests compiled from the diff.

<Note>PR Checks require a Team or Paid plan.</Note>

<Info>
  **Setup required:** Per-PR sandboxes require the Arga team to configure service forks for your stack. [Book a call](https://cal.com/akiratong/30min?overlayCalendar=true) so we can understand which services you run and how they're deployed.
</Info>

**From the web app:**

1. Open **PR Checks** in the **Previews** section of the sidebar.
2. Choose the repository you want Arga to monitor.
3. Install the Arga GitHub App for that repository if prompted.
4. Choose whether to trigger on pull requests or branch pushes.
5. Configure PR comments and custom instructions.
6. Save the settings.

Arga publishes results back to GitHub as the **Arga Validation** check. You can review recent checks and runs from the PR Checks UI.

In the CLI, use `arga previews pr-checks run`. See the [CLI mapping](#cli-mapping) below for examples.

For more details, see [Per-PR sandboxes](/features/pr-validation).

***

## Supporting Primitives

These surfaces help you create repeatable validation workflows, but they do not execute validation on their own.

| I want to...                                                           | Use in the web app      |
| ---------------------------------------------------------------------- | ----------------------- |
| Save and edit deterministic browser-test definitions                   | [Tests](#tests)         |
| Reuse twin seed data across validation workflows                       | [Scenarios](#scenarios) |
| Spin up service twins without deploying app code or running validation | [Twins](#twins)         |

### Tests

Use **Tests** to manage saved browser-test definitions. Tests are empty until you save one from **Runs**.

From the **Tests** page you can:

* Review saved tests in a list, similar to Scenarios.
* Edit the test name, description, repository, CI toggle, credentials, parameters, and blocks.
* Attach a test to a repository so it can run as part of PR Checks.
* Delete tests that are no longer useful.

Saved credentials are encrypted. The UI shows credential keys after saving, but not the secret values.

In the CLI, use `arga test-runner tests ...`. Agents should edit saved tests through TestConfig JSON.

### Scenarios

Use **Scenarios** when you want reusable twin data. A scenario defines the seed state for one or more digital twins, such as Slack channels, GitHub repos, Stripe customers, or Jira issues.

Scenarios pair naturally with Test Runs and Sandboxes: provision twins with a scenario, deploy or point your app at those twins, then execute a validation workflow.

See [Custom scenarios](/features/custom-scenarios) for presets, API examples, and guidance on defining seed data.

In the CLI, use `arga test-runner scenarios ...`.

### Twins

Use **Twins** to spin up service twins without deploying app code or running validation. This mirrors the CLI quickstart flow: select the services your app uses, provision them, then point your local or staging app at the generated URLs and environment variables.

**From the web app:**

1. Open **Twins** in the **Previews** section of the sidebar.
2. Select one or more services.
3. Optionally choose a scenario to seed the twins.
4. Provision the twins.
5. Copy the base URLs and environment variables into your app.

For the CLI setup flow, see [Twins quickstart](/features/twins-quickstart).

In the CLI, use `arga previews twins provision`.

***

## CLI Mapping

Use this section when you want the terminal equivalent of a web workflow. For full flags and JSON output shapes, see [CLI](/cli-and-mcp).

### Validation workflows

Run a browser test against a live URL:

```bash theme={null}
arga test-runner runs url --url https://your-app.com --prompt "test the checkout and payment flow"
```

Provision twins before a URL run:

```bash theme={null}
arga test-runner runs url --twins slack,stripe --prompt "test the checkout and notification flow"
```

Deploy a sandbox preview:

```bash theme={null}
arga previews sandboxes run \
  --repo owner/repo \
  --branch feature/checkout \
  --twins slack,stripe \
  --scenario-id <scenario-id>
```

Run a PR check manually:

```bash theme={null}
arga previews pr-checks run --repo owner/repo --pr 182
```

### Supporting primitives

Manage saved tests:

```bash theme={null}
arga test-runner tests list --repo owner/repo
arga test-runner tests export <test-id> --output saved-test.json
arga test-runner tests edit <test-id>
arga test-runner tests run <test-id> --url https://preview.example.com
```

Validate and normalize agent-authored TestConfig JSON:

```bash theme={null}
arga test-runner tests config validate --file test_config.json
arga test-runner tests config summarize --file test_config.json
arga test-runner tests config normalize --file test_config.json --output test_config.json
```

Manage scenarios:

```bash theme={null}
arga test-runner scenarios list --include-presets
arga test-runner scenarios import --file scenario.json
arga test-runner scenarios export <scenario-id> --output scenario.json
```

Provision standalone twins:

```bash theme={null}
arga previews twins provision --twins slack,jira --ttl 60 --wait
arga previews twins status <run-id>
```