Skip to main content

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.

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 executeRuns
Deploy a branch into a preview environment with service twinsSandboxes
Validate PRs or branch pushes with repository-aware checksPR Checks

Test Runs

Start a live browser run from a prompt and URL, then watch frames, events, and editable blocks.

Sandboxes

Deploy a branch into an isolated preview environment with service twins.

PR Checks

Validate repository changes and publish results back to GitHub.

​
Validation Workflows

​
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.
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.
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 below for examples.

​
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.
Sandboxes require a Team or Paid plan.
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. In the CLI, use arga previews sandboxes run. See the CLI mapping below for examples.

​
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.
PR Checks require a Team or Paid plan.
Setup required: Per-PR sandboxes require the Arga team to configure service forks for your stack. Book a call so we can understand which services you run and how they’re deployed.
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 below for examples. For more details, see Per-PR sandboxes.

​
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 definitionsTests
Reuse twin seed data across validation workflowsScenarios
Spin up service twins without deploying app code or running validationTwins

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

​
Validation workflows

Run a browser test against a live URL: 
arga test-runner runs url --url https://your-app.com --prompt "test the checkout and payment flow"
Provision twins before a URL run: 
arga test-runner runs url --twins slack,stripe --prompt "test the checkout and notification flow"
Deploy a sandbox preview: 
arga previews sandboxes run \
  --repo owner/repo \
  --branch feature/checkout \
  --twins slack,stripe \
  --scenario-id <scenario-id>
Run a PR check manually: 
arga previews pr-checks run --repo owner/repo --pr 182

​
Supporting primitives

Manage saved tests: 
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: 
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: 
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: 
arga previews twins provision --twins slack,jira --ttl 60 --wait
arga previews twins status <run-id>