Scenarios

Scenarios let you start validation runs with realistic, pre-populated twin data instead of empty services. A scenario defines what data each digital twin should contain — Slack channels with message history, Stripe customers with subscriptions, GitHub repos with open PRs, and more. When you attach a scenario to a run, Arga provisions the selected twins and seeds them with the scenario’s data before executing any test steps.

Preset scenarios

Arga ships with 10 built-in scenario templates covering common testing patterns. These are available to all users and can be cloned to customize.

Functionality

Scenario	Twins	What’s inside
E-commerce Checkout	Stripe, Slack	3 customers on free/pro/enterprise plans, #orders channel with purchase confirmations, #support with billing questions
SaaS Billing & Upgrades	Stripe, Slack, Notion	Trial user expiring in 2 days, free/pro/enterprise customers, monthly+annual pricing, #billing alerts, pricing docs
DevOps CI/CD Pipeline	GitHub, Slack, Discord	2 repos (passing and failing CI), merged and open PRs, #deploys and #incidents channels, #dev-alerts Discord
Customer Support Portal	Slack, Stripe, Notion	#support-tier1 with 8 open tickets, #support-escalated with 2 critical issues, disputed charges, knowledge base articles
Document Collaboration	Google Drive, Slack, Notion	Q2 Planning shared folder with 4 docs, #team-docs with file share notifications, project wiki pages

Security

Scenario	Twins	What’s inside
Payment Fraud & Edge Cases	Stripe, Slack	Declined cards (insufficient funds, expired, stolen), $500 chargeback, partial refunds, #fraud-alerts channel
Access Control & Auth Boundaries	GitHub, Slack, Notion	Protected branches, outside contributor PRs, confidential issues, admin/member/guest Slack roles, mixed-permission Notion pages

Edge cases

Scenario	Twins	What’s inside
High Volume Messaging	Slack, Discord	50+ messages in #general, 20 threaded discussions, 5 DM conversations, 30+ Discord messages per channel with embeds
Internationalization & Unicode	Slack, Stripe, Notion	Messages in Japanese/Arabic/Portuguese, emoji-heavy content, international addresses (JP, DE, BR), multi-currency (USD/EUR/JPY), RTL text
Calendar Scheduling Conflicts	Google Calendar, Slack	Overlapping meetings, back-to-back events, all-day events across timezones, cancelled-but-visible meetings, #scheduling channel

Using presets

From the web app: Open Scenarios in the sidebar. Preset templates appear at the top — click Use in Run to start a validation run with that scenario, or Clone to copy it into your own scenarios for customization. From the API:

# List all presets
curl https://api.argalabs.com/scenarios/presets

# Filter presets by twin
curl "https://api.argalabs.com/scenarios/presets?twin=stripe"

From the CLI:

# Start a run with a preset
arga test-runner runs url --url https://myapp.com --prompt "Test checkout" --scenario <preset-id>

You can list presets and manage custom scenarios with arga test-runner scenarios ....

Custom scenarios

Create your own scenarios tailored to your application. There are two ways to define the twin data:

Natural language — describe what you want and Arga generates the seed configuration automatically
Explicit config — provide the exact JSON for each twin

When you use a natural-language prompt, Arga runs a two-pass pipeline to generate the seed configuration:

Twin selection — a classifier reads your prompt and picks the single most relevant twin. It always prefers provider-specific twins (slack, discord, notion, gmail, google_drive, google_calendar, stripe, github, gitlab, dropbox, box, jira, salesforce, linear, postgres, unstructured) over unified. The unified twin is only selected when the prompt explicitly mentions “unified” or “unified.to”. Multiple twins are selected only when the prompt explicitly names more than one provider (for example, “a GitHub repo AND a Slack workspace”).
Config generation — a second pass generates the seed JSON scoped to the selected twin(s). Any secondary details that don’t map to the chosen twin’s schema are either mapped to the closest available field or omitted.

If you need full control over which twins are included, pass the twins array explicitly alongside your seed_config.

From the web app

Open Scenarios in the sidebar
Click Create Scenario
Enter a name and either a natural language prompt or raw JSON config
Save — Arga generates and stores the twin configuration

You can also save scenarios from validation runs: after configuring twins in the run wizard, click Save as Scenario to reuse that configuration later.

From a twin dashboard

Browser-facing twin UIs (Box, Discord, Dropbox, GitHub, GitLab, Gmail, Google Calendar, Google Drive, Linear, LinkedIn, Notion, Slack, Stripe, Unified, Unstructured) include a Save scenario button in the dashboard header. Clicking it captures the twin’s current state as a seed_config payload and hands it off to the Arga web app, which opens the scenario creation flow pre-filled with that configuration. Use it to turn a hand-crafted twin state into a reusable scenario without copying JSON manually.

From the API

With a natural language prompt:

curl -X POST https://api.argalabs.com/scenarios \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce checkout",
    "description": "Stripe with test customers and Slack with support channel",
    "prompt": "A Stripe account with 3 customers on different plans and a Slack workspace with a #support channel containing 10 recent messages about billing issues"
  }'

With explicit config:

curl -X POST https://api.argalabs.com/scenarios \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding flow",
    "twins": ["slack", "stripe"],
    "seed_config": {
      "slack": {
        "channels": [
          {"name": "general", "messages": [{"text": "Welcome to the team!", "user": "admin"}]}
        ]
      },
      "stripe": {
        "customers": [{"name": "Test User", "email": "test@example.com"}]
      }
    }
  }'

From the CLI

Create a scenario from a prompt:

arga test-runner scenarios create \
  --name "E-commerce checkout" \
  --prompt "Stripe with 3 customers and Slack with #support billing messages" \
  --twin stripe \
  --twin slack \
  --tag checkout

Import or export explicit seed JSON for agent-authored scenarios:

arga test-runner scenarios import --file scenario.json
arga test-runner scenarios export <scenario-id> --output scenario.json
arga test-runner scenarios update <scenario-id> --file scenario.json

Use a scenario in a URL run:

arga test-runner runs url --url https://myapp.com --prompt "Test checkout" --scenario <scenario-id>

Managing scenarios

List

curl https://api.argalabs.com/scenarios \
  -H "Authorization: Bearer <api-key>"

Filter by twin or tag:

curl "https://api.argalabs.com/scenarios?twin=slack&tag=billing" \
  -H "Authorization: Bearer <api-key>"

Include presets alongside your scenarios:

curl "https://api.argalabs.com/scenarios?include_presets=true" \
  -H "Authorization: Bearer <api-key>"

Update

curl -X PUT https://api.argalabs.com/scenarios/<scenario-id> \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Updated description of the data I want"}'

If you update the prompt without providing a new seed_config, Arga regenerates the configuration from the updated prompt.

Delete

curl -X DELETE https://api.argalabs.com/scenarios/<scenario-id> \
  -H "Authorization: Bearer <api-key>"

Using scenarios in runs

Attach a scenario to any validation run to seed twins before test execution. Runs:

curl -X POST https://api.argalabs.com/validate/url-run \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com",
    "prompt": "Test the checkout flow",
    "scenario_id": "<scenario-id>"
  }'

PR Checks:

curl -X POST https://api.argalabs.com/validate/pr-run \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "acme/web-app",
    "branch": "feature/checkout",
    "scenario_id": "<scenario-id>"
  }'

CLI:

arga test-runner runs url --url https://myapp.com --prompt "Test checkout" --scenario <scenario-id>

When you provide scenario_id without a prompt, the scenario’s own prompt is used. If you supply both, your prompt takes precedence. For Runs started through /validate/url-run, the scenario’s twins list is used as a default when you don’t pass an explicit twins array. This means a request with just url and scenario_id provisions exactly the twins the scenario declares instead of falling back to the default profile. If you pass your own twins array, it takes precedence over the scenario’s list.

PR Checks derive their twin selection from the repository and branch context, so the scenario’s twin list is not used as a fallback for PR Checks.

Reusing scenarios with twins

To reuse a scenario with fresh twins, pass both twins and scenario_id to the Provision twins API. Arga provisions a new twin environment and seeds it from the scenario before the status becomes ready.

Long-lived scenario twin environment endpoints are not present in the current validation-server checkout. See Availability notes for the current API gap.

Supported twins

Twin	What you can seed
`slack`	Channels, messages, threads, users, OAuth bot scopes, OAuth user scopes, custom tokens, tier (`free`, `pro`, `business_plus`, `enterprise`), disabled scopes, workspace constraints (file upload toggle, storage quotas, rate limits, message history limits, app install limits, workflow toggle)
`discord`	Guilds, channels, messages, members, boost level, file upload and emoji limits. Seed results include `guild_id` and `channel_ids` for referencing created resources.
`github`	Users, orgs, repos, files, branches, pull requests, merged PR refs, issues, labels, CI/status data, reviews, git references, branch protection, GitHub App configuration, default token scopes, disabled scopes
`gitlab`	Groups, projects, repository files, branches, issues, merge requests, pipelines, and hooks
`stripe`	Customers, products, prices, subscriptions, billing meters (with meter events)
`notion`	Pages, databases, blocks, workspace plan (`free`, `plus`, `business`, `enterprise`), disabled capabilities
`gmail`	Labels, messages, threads, and drafts
`google_drive`	Folders, files, storage tier (`free`, `basic`, `premium`, `ai_pro`), disabled scopes
`google_calendar`	Calendars, events
`jira`	Projects, issues, comments, worklogs, and webhooks
`salesforce`	Accounts, contacts, cases, and email templates
`box`	Folders, files
`dropbox`	Folders, files, account tier (`basic`, `plus`, `professional`, `business`)
`linear`	Teams, projects, cycles, issues, labels, and comments
`salesforce`	Accounts, contacts, cases, email templates, and email messages
`postgres`	Raw SQL statements applied to the mirrored data plane

Slack OAuth scope overrides

The Slack twin enforces OAuth scope requirements on API calls. You can customize the scopes granted to bot and user tokens by including oauth_bot_scopes, oauth_user_scopes, or tokens in the Slack seed configuration. This is useful for testing how your app handles missing permissions.

{
  "slack": {
    "channels": [{"name": "general"}],
    "oauth_bot_scopes": ["chat:write", "channels:read"],
    "oauth_user_scopes": ["search:read", "channels:read"],
    "tokens": [
      {
        "token": "xoxb-custom-token",
        "user_id": "UTWINBOT",
        "scopes": ["chat:write", "channels:read", "files:write"],
        "is_bot": true
      }
    ]
  }
}

Bot tokens always receive chat:write and files:write as minimum scopes, even if your configuration specifies a narrower set. See configurable token scopes for the full list of available scopes and their corresponding API methods.

Slack workspace constraints

You can configure workspace-level settings in the Slack seed to test how your app handles restricted environments — disabled file uploads, storage quotas, and rate limits.

{
  "slack": {
    "channels": [{"name": "general"}],
    "file_uploads_enabled": false,
    "max_storage_bytes": 5368709120,
    "storage_used_bytes": 5000000000,
    "rate_limiting_enabled": true,
    "rate_limits": {
      "files.getUploadURLExternal": {
        "window_seconds": 60,
        "max_requests": 5,
        "retry_after_seconds": 30
      }
    }
  }
}

Field	Type	Default	Description
`file_uploads_enabled`	`boolean`	`true`	Set to `false` to simulate a workspace with file uploads disabled. Returns a `file_uploads_disabled` error on upload attempts.
`max_storage_bytes`	`integer \| null`	`null`	Workspace storage quota in bytes. When set, uploads that would exceed the quota return a `storage_limit_reached` error.
`storage_used_bytes`	`integer`	`0`	Pre-existing storage usage in bytes. Combine with `max_storage_bytes` to simulate a nearly-full workspace.
`rate_limiting_enabled`	`boolean`	`false`	Whether per-method rate limiting is active.
`rate_limits`	`object`	`{}`	Map of Slack API method names to rate limit rules. Each rule specifies `window_seconds`, `max_requests`, and `retry_after_seconds`.

See workspace constraints for the full reference and error response shapes.

GitHub repository seed config

Each entry in the GitHub seed’s repos array creates one repository in the twin. You can describe the files inline with files, or clone a public GitHub repository to pre-populate the twin with its tracked files.

{
  "github": {
    "repos": [
      {
        "owner": "scenario-org",
        "name": "my-app",
        "repo_url": "https://github.com/octocat/Hello-World",
        "source_ref": "main",
        "branches": [{"name": "feature", "from": "main"}],
        "issues": [{"title": "Bug report", "body": "Something broke"}]
      }
    ]
  }
}

Field	Type	Description
`owner`	`string`	Org or user login that owns the seeded repo. When the owner matches a seeded org, the repo is created under that org; otherwise it is created under the authenticated user.
`name`	`string`	Repository name. If omitted, the name is derived from `repo_url` when a clone source is provided, otherwise it falls back to `repo-<index>`.
`repo_url`	`string`	Public HTTPS `github.com` repository URL or `owner/repo` shorthand. The runner shallow-clones the repo and seeds its tracked files into the twin. Aliases: `public_repo_url`, `clone_url`, `source_repo_url`.
`source_ref`	`string`	Branch or tag to clone from the public source repo. Falls back to `ref` when not set. Defaults to the source repo’s default branch.
`files`	`array`	Inline files to seed after any cloned files. When `repo_url` is set, `files` is only used if the field is explicitly present in the spec.
`branches`	`array`	Additional branches to create on the seeded repo.
`issues`	`array`	Issues to seed on the repo.
`private`, `default_branch`, `language`, `description`	various	Standard repository metadata.

When cloning from repo_url, the runner enforces these limits per repository to keep seeding fast and bounded:

Only public HTTPS github.com URLs are accepted. Credentialed URLs are rejected.
Up to 1,000 tracked files are copied.
Each file must be 1 MiB or smaller; symlinks are skipped.
The total cloned payload is capped at 25 MiB. Files beyond the limit are skipped.

Get started

Validate

Digital twins

Setup

Integrations

Resources

Preset scenarios

Functionality

Security

Edge cases

Using presets

Custom scenarios

From the web app

From a twin dashboard

From the API

From the CLI

Managing scenarios

List

Update

Delete

Using scenarios in runs

Reusing scenarios with twins

Supported twins

Slack OAuth scope overrides

Slack workspace constraints

GitHub repository seed config

Tags

​Preset scenarios

​Functionality

​Security

​Edge cases

​Using presets

​Custom scenarios

​From the web app

​From a twin dashboard

​From the API

​From the CLI

​Managing scenarios

​List

​Update

​Delete

​Using scenarios in runs

​Reusing scenarios with twins

​Supported twins

​Slack OAuth scope overrides

​Slack workspace constraints

​GitHub repository seed config

​Tags

Preset scenarios

Functionality

Security

Edge cases

Using presets

Custom scenarios

From the web app

From a twin dashboard

From the API

From the CLI

Managing scenarios

List

Update

Delete

Using scenarios in runs

Reusing scenarios with twins

Supported twins

Slack OAuth scope overrides

Slack workspace constraints

GitHub repository seed config

Tags