> ## 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. # Scenarios > Pre-configured digital twin data for your validation runs 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:** ```bash theme={null} # 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:** ```bash theme={null} # Start a run with a preset arga test-runner runs url --url https://myapp.com --prompt "Test checkout" --scenario ``` 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: 1. **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"). 2. **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 1. Open **Scenarios** in the sidebar 2. Click **Create Scenario** 3. Enter a name and either a natural language prompt or raw JSON config 4. 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:** ```bash theme={null} curl -X POST https://api.argalabs.com/scenarios \ -H "Authorization: Bearer " \ -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:** ```bash theme={null} curl -X POST https://api.argalabs.com/scenarios \ -H "Authorization: Bearer " \ -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: ```bash theme={null} 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: ```bash theme={null} arga test-runner scenarios import --file scenario.json arga test-runner scenarios export --output scenario.json arga test-runner scenarios update --file scenario.json ``` Use a scenario in a URL run: ```bash theme={null} arga test-runner runs url --url https://myapp.com --prompt "Test checkout" --scenario ``` ## Managing scenarios ### List ```bash theme={null} curl https://api.argalabs.com/scenarios \ -H "Authorization: Bearer " ``` Filter by twin or tag: ```bash theme={null} curl "https://api.argalabs.com/scenarios?twin=slack&tag=billing" \ -H "Authorization: Bearer " ``` Include presets alongside your scenarios: ```bash theme={null} curl "https://api.argalabs.com/scenarios?include_presets=true" \ -H "Authorization: Bearer " ``` ### Update ```bash theme={null} curl -X PUT https://api.argalabs.com/scenarios/ \ -H "Authorization: Bearer " \ -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 ```bash theme={null} curl -X DELETE https://api.argalabs.com/scenarios/ \ -H "Authorization: Bearer " ``` ## Using scenarios in runs Attach a scenario to any validation run to seed twins before test execution. **Runs:** ```bash theme={null} curl -X POST https://api.argalabs.com/validate/url-run \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "url": "https://myapp.com", "prompt": "Test the checkout flow", "scenario_id": "" }' ``` **PR Checks:** ```bash theme={null} curl -X POST https://api.argalabs.com/validate/pr-run \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "repo": "acme/web-app", "branch": "feature/checkout", "scenario_id": "" }' ``` **CLI:** ```bash theme={null} arga test-runner runs url --url https://myapp.com --prompt "Test checkout" --scenario ``` 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-reference/post-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](/api-reference/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](/concepts/digital-twins#slack-twin-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. ```json theme={null} { "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](/concepts/digital-twins#slack-twin-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. ```json theme={null} { "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](/concepts/digital-twins#slack-twin-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. ```json theme={null} { "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-`. | | `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. ## Tags Organize scenarios with free-form tags for filtering: ```json theme={null} { "name": "Payment edge cases", "tags": ["billing", "edge-cases", "stripe"] } ``` Filter by tag in the API (`?tag=billing`) or web app.