Scenario

Stoobly Scenario CLI - Questions & Answers

The scenario CLI enables you to manage collections of related HTTP requests as scenarios. Scenarios help organize test flows, user journeys, and API workflows that involve multiple requests executed in sequence.

Understanding Scenarios

Q: What is a scenario in Stoobly?

A: A scenario is a collection of related HTTP requests that represent a user flow, test case, or API workflow. Scenarios execute requests in sequence and can validate responses.

Example:

# Create a scenario for user login flow
stoobly-agent scenario create "User Login Flow"

# The scenario will contain multiple requests:
# 1. GET /api/csrf-token
# 2. POST /api/login
# 3. GET /api/user/profile

Q: Why should I use scenarios?

A: Scenarios help organize related requests, enable end-to-end testing, support workflow validation, and make it easy to share test cases with your team via version control.

Example:

# Instead of managing 10 individual requests
stoobly-agent request replay req1
stoobly-agent request replay req2
# ... (8 more)

# Use a scenario
stoobly-agent scenario replay user-checkout-flow

Creating Scenarios

Q: How do I create a new scenario?

A: Use scenario create with a descriptive name for your scenario.

Example:

stoobly-agent scenario create "User Login Flow"

Q: How do I create a scenario with a description?

A: Use the --description option to add context to your scenario.

Example:

stoobly-agent scenario create "API Integration Test" --description "Tests all critical API endpoints for the mobile app"

Q: How do I create a scenario in a specific project?

A: Use the --project-key option to specify the project (remote features).

Example:

stoobly-agent scenario create "Payment Flow" --project-key proj-abc123

Q: How do I format the output when creating a scenario?

A: Use the --format option to control how the created scenario is displayed.

Example:

# JSON format
stoobly-agent scenario create "Checkout Flow" --format json

# Table format
stoobly-agent scenario create "User Registration" --format table

# CSV format
stoobly-agent scenario create "Admin Panel" --format csv

Q: How do I add requests to a scenario?

A: Record or replay requests with the --scenario-key option to add them to a scenario.

Example:

# First, create the scenario and note the key
stoobly-agent scenario create "User Login Flow"
# Output: Created scenario with key: abc123

# Then record requests to that scenario
stoobly-agent record -X POST -d '{"username":"user","password":"pass"}' https://api.example.com/login --scenario-key abc123

# Or replay and record to the scenario
stoobly-agent request replay xyz789 --record --scenario-key abc123

Listing Scenarios

Q: How do I view all scenarios?

A: Use scenario list to display all scenarios with pagination.

Example:

stoobly-agent scenario list

Q: How do I paginate through scenarios?

A: Use the --page and --size options to control pagination.

Example:

# Show first 10 scenarios (default)
stoobly-agent scenario list --page 0 --size 10

# Show next 20 scenarios
stoobly-agent scenario list --page 1 --size 20

# Show 50 scenarios per page
stoobly-agent scenario list --page 0 --size 50

Q: How do I search for specific scenarios?

A: Use the --search option to filter scenarios by name or description.

Example:

# Search by name
stoobly-agent scenario list --search "login"

# Search by description
stoobly-agent scenario list --search "payment"

Q: How do I sort scenarios?

A: Use --sort-by and --sort-order options to control sorting.

Example:

# Sort by creation date (newest first, default)
stoobly-agent scenario list --sort-by created_at --sort-order desc

# Sort by creation date (oldest first)
stoobly-agent scenario list --sort-by created_at --sort-order asc

# Sort by name alphabetically
stoobly-agent scenario list --sort-by name --sort-order asc

Q: How do I format the scenario list output?

A: Use the --format option to change output format.

Example:

# Table format (default)
stoobly-agent scenario list --format table

# JSON format
stoobly-agent scenario list --format json

# CSV format
stoobly-agent scenario list --format csv

Q: How do I select specific columns to display?

A: Use the --select option to choose which columns to show.

Example:

# Show only specific columns
stoobly-agent scenario list --select id --select name --select created_at

# Show key and name only
stoobly-agent scenario list --select key --select name --without-headers

Viewing Scenario Details

Q: How do I view details about a specific scenario?

A: Use scenario show with the scenario key.

Example:

stoobly-agent scenario show abc123-scenario-key

Q: How do I format scenario details output?

A: Use the --format option to control the display format.

Example:

# JSON format for scripting
stoobly-agent scenario show abc123 --format json

# Table format for readability
stoobly-agent scenario show abc123 --format table

Q: How do I get the request count for a scenario?

A: View scenario details or use the show command with specific column selection.

Example:

# Show all details including request count
stoobly-agent scenario show abc123

# Select specific fields
stoobly-agent scenario show abc123 --select name --select request_count

Replaying Scenarios

Q: How do I replay all requests in a scenario?

A: Use scenario replay with the scenario key to execute all requests in sequence.

Example:

stoobly-agent scenario replay abc123-scenario-key

Q: How do I replay a scenario to a different host?

A: Use the --host option to override the request host for all requests.

Example:

# Replay to localhost
stoobly-agent scenario replay abc123 --host localhost:8080

# Replay to staging environment
stoobly-agent scenario replay abc123 --host staging.example.com

Q: How do I replay a scenario with a different scheme?

A: Use the --scheme option to change the protocol for all requests.

Example:

# Force HTTP
stoobly-agent scenario replay abc123 --scheme http

# Force HTTPS
stoobly-agent scenario replay abc123 --scheme https

Q: How do I update a scenario and by adding new responses?

A: Use the --record flag to capture the replayed responses.

Example:

stoobly-agent scenario replay abc123 --record

Q: How do I update a scenario and overwrite existing responses?

A: Use the --overwrite flag to replace stored responses (local mode only).

Example:

stoobly-agent scenario replay abc123 --overwrite

Q: How do I replay a scenario and save to history?

A: Use the --save flag to persist the replay session (local mode).

Example:

stoobly-agent scenario replay abc123 --save

Q: How do I replay a scenario with custom lifecycle hooks?

A: Use the --lifecycle-hooks-path option to apply custom processing.

Example:

stoobly-agent scenario replay abc123 --lifecycle-hooks-path ./hooks.py

Q: How do I increase logging verbosity when replaying?

A: Use the --log-level option to see more details.

Example:

# Debug level (most verbose)
stoobly-agent scenario replay abc123 --log-level debug

# Info level
stoobly-agent scenario replay abc123 --log-level info

Q: How do I format the replay response output?

A: Use the --format option to control response display.

Example:

# JSON format with full details
stoobly-agent scenario replay abc123 --format json

Working with Aliases

Q: How do I replay a scenario with assigned alias values?

A: Use the --assign option to set alias values before replay.

Example:

# Assign single alias
stoobly-agent scenario replay abc123 --assign userId=12345

# Assign multiple aliases
stoobly-agent scenario replay abc123 --assign userId=12345 --assign token=abc123

Q: How do I validate alias values during scenario execution?

A: Use the --validate option to specify validation rules for aliases.

Example:

# Validate userId is an integer
stoobly-agent scenario replay abc123 --validate "userId=?int"

# Validate multiple aliases
stoobly-agent scenario replay abc123 --validate "userId=?int" --validate "email=?string"

Q: How do I control alias resolution strategy?

A: Use the --alias-resolve-strategy option to specify how aliases are resolved.

Example:

# No alias resolution (default)
stoobly-agent scenario replay abc123 --alias-resolve-strategy none

# First-in-first-out resolution
stoobly-agent scenario replay abc123 --alias-resolve-strategy fifo

# Last-in-first-out resolution
stoobly-agent scenario replay abc123 --alias-resolve-strategy lifo

Q: How do I repeat scenario execution for each alias value?

A: Use the --group-by option to iterate over alias values.

Example:

# Execute scenario once for each userId value
stoobly-agent scenario replay abc123 --group-by userId

Q: How do I use an existing trace for scenario execution?

A: Use the --trace-id option to leverage a previous trace.

Example:

stoobly-agent scenario replay abc123 --trace-id trace-xyz789

Snapshots and Version Control

Q: How do I create a snapshot of a scenario?

A: Use scenario snapshot to create committable files for the scenario (local mode only).

Example:

stoobly-agent scenario snapshot abc123-scenario-key

Q: How do I delete a scenario snapshot?

A: Use the --action delete option with snapshot command.

Example:

stoobly-agent scenario snapshot abc123 --action delete

Q: How do I snapshot a scenario with decoded response bodies?

A: Use the --decode flag to decode response bodies in the snapshot.

Example:

stoobly-agent scenario snapshot abc123 --decode

Q: How do I reset a scenario to its snapshot state?

A: Use scenario reset to restore a scenario from its snapshot.

This command reverts the scenario to the last committed snapshot. It does not merge new requests. If you need to incorporate new traffic, record or replay with --scenario-key instead of resetting.

Example:

stoobly-agent scenario reset abc123-scenario-key

Q: How do I force delete when resetting a scenario?

A: Use the --force flag to hard delete the scenario data.

Example:

stoobly-agent scenario reset abc123 --force

A: Create snapshots and commit them to version control.

Example:

# Create snapshot
stoobly-agent scenario snapshot abc123 --decode

# Commit to git
git add .stoobly/snapshots/scenarios/
git commit -m "Add user login scenario snapshot"
git push

# Team member pulls and uses
git pull
stoobly-agent scenario reset abc123  # Restore from snapshot
stoobly-agent scenario replay abc123 # Replay the scenario

Deleting Scenarios

Q: How do I delete a scenario?

A: Use scenario delete with the scenario key.

Example:

stoobly-agent scenario delete abc123-scenario-key

Q: What happens to requests when I delete a scenario?

A: The scenario is deleted but the individual requests remain in storage unless explicitly deleted.

Example:

# Delete scenario (requests remain)
stoobly-agent scenario delete abc123

# To also delete requests, delete them individually
stoobly-agent request delete req1
stoobly-agent request delete req2

Scenario Workflows

Q: How do I create a complete user flow scenario?

A: Create the scenario, then record or add requests in the correct sequence.

Example:

# 1. Create scenario
stoobly-agent scenario create "Complete Checkout Flow"
# Output: Created scenario with key: checkout-abc123

# 2. Record requests in sequence
stoobly-agent record https://api.example.com/cart --scenario-key checkout-abc123
stoobly-agent record -X POST -d '{"items":[]}' https://api.example.com/cart/add --scenario-key checkout-abc123
stoobly-agent record -X POST https://api.example.com/checkout --scenario-key checkout-abc123
stoobly-agent record -X POST https://api.example.com/payment --scenario-key checkout-abc123

# 3. Replay the complete flow
stoobly-agent scenario replay checkout-abc123

Q: How do I update a scenario with new requests?

A: To update a scenario, record or replay new requests while specifying the scenario key with the --scenario-key option. This adds the new requests to the scenario.

Option 1: Record a new request and add it to the scenario

stoobly-agent record https://api.example.com/new-endpoint --scenario-key abc123

Option 2: Replay an existing request and add it to the scenario

stoobly-agent request replay xyz789 --record --scenario-key abc123

Option 3: Add multiple new requests to a scenario

# Record multiple endpoints and add them all to the same scenario
stoobly-agent record https://api.example.com/endpoint1 --scenario-key abc123
stoobly-agent record https://api.example.com/endpoint2 --scenario-key abc123
stoobly-agent record https://api.example.com/endpoint3 --scenario-key abc123

Q: How do I test multiple scenarios in sequence?

A: Use a script to test scenarios one after another.

Example:

#!/bin/bash
# Replay multiple scenarios

scenarios=("login-flow" "checkout-flow" "admin-panel")

for scenario in "${scenarios[@]}"; do
  echo "Replaying scenario: $scenario"
  if ! stoobly-agent scenario replay $scenario; then
    echo "Failed: $scenario"
    exit 1
  fi
done

echo "All scenarios completed!"

Advanced Scenario Operations

Q: How do I chain multiple scenarios?

A: Use a script to execute scenarios in sequence with dependency handling.

Example:

#!/bin/bash
# Chain scenarios with dependencies

# Setup scenario
stoobly-agent scenario replay setup-data --save
if [ $? -ne 0 ]; then
  echo "Setup failed"
  exit 1
fi

# Main scenario
stoobly-agent scenario replay main-flow --save
if [ $? -ne 0 ]; then
  echo "Main flow failed"
  exit 1
fi

# Cleanup scenario
stoobly-agent scenario replay cleanup --save

echo "All scenarios completed"

Q: How do I extract data from one scenario to use in another?

A: Use aliases and traces to pass data between scenarios.

Example:

# First scenario creates data and assigns aliases
stoobly-agent scenario replay create-user \
  --save \
  --trace-id shared-trace \
  --assign [email protected]

# Second scenario uses the trace and aliases
stoobly-agent scenario replay login-user \
  --trace-id shared-trace \
  --assign [email protected]

Monitoring and Debugging

Q: How do I debug a failing scenario?

A: Increase log level and use verbose output.

Example:

# Debug with verbose logging
stoobly-agent scenario replay abc123 --log-level debug

# Replay with logging to see each request
stoobly-agent scenario replay abc123 --log-level info

Q: How do I identify which request in a scenario is failing?

A: Use detailed output and logging to track request execution.

Example:

# Replay with detailed logging
stoobly-agent scenario replay abc123 --log-level info

# This shows each request as it executes

Quick Reference

Q: What are the most common scenario commands?

A: Here's a quick reference of frequently used commands:

Example:

# Create scenarios
stoobly-agent scenario create "My Scenario"
stoobly-agent scenario create "API Flow" --description "Tests API endpoints"

# List scenarios
stoobly-agent scenario list
stoobly-agent scenario list --search "login"
stoobly-agent scenario list --format json

# View scenario details
stoobly-agent scenario show abc123

# Replay scenarios
stoobly-agent scenario replay abc123
stoobly-agent scenario replay abc123 --host staging.example.com
stoobly-agent scenario replay abc123 --record

# Snapshots
stoobly-agent scenario snapshot abc123
stoobly-agent scenario snapshot abc123 --decode
stoobly-agent scenario reset abc123

# Delete scenarios
stoobly-agent scenario delete abc123

Best Practices

Q: How should I organize my scenarios?

A: Group related requests by user flow, feature area, or test type.

Example:

# By user flow
stoobly-agent scenario create "User Registration Flow"
stoobly-agent scenario create "User Login Flow"
stoobly-agent scenario create "User Profile Update Flow"

# By feature area
stoobly-agent scenario create "Shopping Cart - Add Items"
stoobly-agent scenario create "Shopping Cart - Checkout"
stoobly-agent scenario create "Shopping Cart - Order History"

# By test type
stoobly-agent scenario create "Smoke Tests"
stoobly-agent scenario create "Integration Tests"
stoobly-agent scenario create "E2E Tests"

Q: How often should I snapshot scenarios?

A: Snapshot after significant changes or before releases.

Example:

# After adding new requests
stoobly-agent scenario snapshot abc123 --decode
git add .stoobly/snapshots/
git commit -m "Update scenario with new endpoints"

# Before release
./snapshot-all-scenarios.sh
git tag -a v1.2.0 -m "Release 1.2.0 with scenario snapshots"
git push --tags

Q: What's the recommended workflow for scenario management?

A: Create → Record → Snapshot → Replay → Update cycle.

Example:

# 1. Create scenario
stoobly-agent scenario create "Payment Flow"

# 2. Record requests
stoobly-agent record <requests> --scenario-key payment-flow

# 3. Snapshot for version control
stoobly-agent scenario snapshot payment-flow --decode
git add .stoobly/snapshots/ && git commit -m "Add payment flow"

# 4. Replay regularly
stoobly-agent scenario replay payment-flow

# 5. Update when needed
stoobly-agent record <new-requests> --scenario-key payment-flow
stoobly-agent scenario snapshot payment-flow --decode
git commit -am "Update payment flow with new endpoints"

PreviousE2E Testing NextSnapshot

Last updated 1 day ago

Was this helpful?

Stoobly Scenario CLI - Questions & Answers

Understanding Scenarios

Q: What is a scenario in Stoobly?

Q: Why should I use scenarios?

Creating Scenarios

Q: How do I create a new scenario?

Q: How do I create a scenario with a description?

Q: How do I create a scenario in a specific project?

Q: How do I format the output when creating a scenario?

Q: How do I add requests to a scenario?

Listing Scenarios

Q: How do I view all scenarios?

Q: How do I paginate through scenarios?

Q: How do I search for specific scenarios?

Q: How do I sort scenarios?

Q: How do I format the scenario list output?

Q: How do I select specific columns to display?

Viewing Scenario Details

Q: How do I view details about a specific scenario?

Q: How do I format scenario details output?

Q: How do I get the request count for a scenario?

Replaying Scenarios

Q: How do I replay all requests in a scenario?

Q: How do I replay a scenario to a different host?

Q: How do I replay a scenario with a different scheme?

Q: How do I update a scenario and by adding new responses?

Q: How do I update a scenario and overwrite existing responses?

Q: How do I replay a scenario and save to history?

Q: How do I replay a scenario with custom lifecycle hooks?

Q: How do I increase logging verbosity when replaying?

Q: How do I format the replay response output?

Working with Aliases

Q: How do I replay a scenario with assigned alias values?

Q: How do I validate alias values during scenario execution?

Q: How do I control alias resolution strategy?

Q: How do I repeat scenario execution for each alias value?

Q: How do I use an existing trace for scenario execution?

Snapshots and Version Control

Q: How do I create a snapshot of a scenario?

Q: How do I delete a scenario snapshot?

Q: How do I snapshot a scenario with decoded response bodies?

Q: How do I reset a scenario to its snapshot state?

Q: How do I force delete when resetting a scenario?

Q: How do I share scenarios with my team via git?

Deleting Scenarios

Q: How do I delete a scenario?

Q: What happens to requests when I delete a scenario?

Scenario Workflows

Q: How do I create a complete user flow scenario?

Q: How do I update a scenario with new requests?

Q: How do I test multiple scenarios in sequence?

Advanced Scenario Operations

Q: How do I chain multiple scenarios?

Q: How do I extract data from one scenario to use in another?

Monitoring and Debugging

Q: How do I debug a failing scenario?

Q: How do I identify which request in a scenario is failing?

Quick Reference

Q: What are the most common scenario commands?

Best Practices

Q: How should I organize my scenarios?

Q: How often should I snapshot scenarios?

Q: What's the recommended workflow for scenario management?