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, github, stripe, etc.) 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 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 also 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.

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`	Repos, file contents, pull requests, issues, branches, labels, check runs, check suites, commit statuses, reviews, git references, branch protection, GitHub App configuration (`app_id`, `app_slug`, `app_name`, permissions, events), default token scopes, disabled scopes
`stripe`	Customers, products, prices, subscriptions, billing meters (with meter events)
`notion`	Pages, databases, blocks, workspace plan (`free`, `plus`, `business`, `enterprise`), disabled capabilities
`google_drive`	Folders, files, storage tier (`free`, `basic`, `premium`, `ai_pro`), disabled scopes
`google_calendar`	Calendars, events
`box`	Folders, files
`dropbox`	Folders, files, account tier (`basic`, `plus`, `professional`, `business`)

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.

Get started

Validate

Digital twins

SDKs

Setup

Reference

Preset scenarios

Functionality

Security

Edge cases

Using presets

Custom scenarios

From the web app

From the API

From the CLI

Managing scenarios

List

Update

Delete

Using scenarios in runs

Supported twins

Slack OAuth scope overrides

Slack workspace constraints

Tags

Get started

Validate

Digital twins

SDKs

Setup

Reference

Documentation Index

​Preset scenarios

​Functionality

​Security

​Edge cases

​Using presets

​Custom scenarios

​From the web app

​From the API

​From the CLI

​Managing scenarios

​List

​Update

​Delete

​Using scenarios in runs

​Supported twins

​Slack OAuth scope overrides

​Slack workspace constraints

​Tags

Preset scenarios

Functionality

Security

Edge cases

Using presets

Custom scenarios

From the web app

From the API

From the CLI

Managing scenarios

List

Update

Delete

Using scenarios in runs

Supported twins

Slack OAuth scope overrides

Slack workspace constraints

Tags