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 replay a scenario and record new responses?

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

Example:

stoobly-agent scenario replay abc123 --record

Q: How do I replay 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

Testing Scenarios

Q: How do I test a scenario to validate responses?

A: Use scenario test with the scenario key to replay and validate all requests.

Example:

stoobly-agent scenario test abc123-scenario-key

Q: What test strategies are available for scenarios?

A: Four strategies: diff (exact match), contract (schema validation), fuzzy (flexible match), and custom (custom logic).

Example:

# Diff testing (exact comparison, default)
stoobly-agent scenario test abc123 --strategy diff

# Contract testing (schema validation)
stoobly-agent scenario test abc123 --strategy contract

# Fuzzy testing (allows minor variations)
stoobly-agent scenario test abc123 --strategy fuzzy

# Custom testing (use lifecycle hooks)
stoobly-agent scenario test abc123 --strategy custom --lifecycle-hooks-path ./test-hooks.py

Q: How do I continue testing even if a request fails?

A: Use the --aggregate-failures flag to continue execution on failure.

Example:

stoobly-agent scenario test abc123 --aggregate-failures

Q: How do I control which test results are displayed?

A: Use the --output-level option to filter results.

Example:

# Show all tests (passed, failed, skipped, default)
stoobly-agent scenario test abc123 --output-level passed

# Show only failed tests
stoobly-agent scenario test abc123 --output-level failed

# Show only skipped tests
stoobly-agent scenario test abc123 --output-level skipped

Q: How do I filter which properties are tested?

A: Use the --filter option to selectively test properties.

Example:

# Test all properties (default)
stoobly-agent scenario test abc123 --filter all

# Test only alias properties
stoobly-agent scenario test abc123 --filter alias

# Test only link properties
stoobly-agent scenario test abc123 --filter link

Q: How do I test a scenario with mock dependencies?

A: Use --response-fixtures-path or --public-directory-path to provide mock responses.

Example:

# Use response fixtures
stoobly-agent scenario test abc123 --response-fixtures-path ./fixtures/responses.yml

# Use public directory for static files
stoobly-agent scenario test abc123 --public-directory-path ./public

# Use both
stoobly-agent scenario test abc123 \
  --response-fixtures-path ./fixtures/responses.yml \
  --public-directory-path ./public

Q: How do I save test results to a report?

A: Use the --report-key option to add results to a report (remote features).

Example:

stoobly-agent scenario test abc123 --report-key report-xyz789

Q: How do I save test results?

A: Use the --save flag to persist test results (remote features).

Example:

stoobly-agent scenario test abc123 --save

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 test abc123 --validate "userId=?int"

# Validate multiple aliases
stoobly-agent scenario test 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 test 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.

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 test abc123   # Test 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. Test the complete flow
stoobly-agent scenario test checkout-abc123

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

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

Example:

# Add new request to existing scenario
stoobly-agent record https://api.example.com/new-endpoint --scenario-key abc123

# Or replay an existing request and add to scenario
stoobly-agent request replay xyz789 --record --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
# Test multiple scenarios

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

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

echo "All scenarios passed!"

Environment-Specific Scenarios

Q: How do I run the same scenario against different environments?

A: Use the --host option to target different environments.

Example:

# Test against local
stoobly-agent scenario test abc123 --host localhost:8080

# Test against staging
stoobly-agent scenario test abc123 --host staging.example.com

# Test against production
stoobly-agent scenario test abc123 --host api.example.com

Q: How do I create environment-specific scenarios?

A: Create separate scenarios for each environment or use the same scenario with different hosts.

Example:

# Option 1: Separate scenarios
stoobly-agent scenario create "Login Flow - Local"
stoobly-agent scenario create "Login Flow - Staging"
stoobly-agent scenario create "Login Flow - Production"

# Option 2: One scenario, different hosts
stoobly-agent scenario create "Login Flow"
# Use with different hosts:
stoobly-agent scenario test login-flow --host localhost:8080
stoobly-agent scenario test login-flow --host staging.example.com

CI/CD Integration

Q: How do I use scenarios in CI/CD pipelines?

A: Test scenarios as part of your automated test suite.

Example:

#!/bin/bash
# CI/CD test script

# Test critical scenarios
scenarios=(
  "user-registration"
  "user-login"
  "checkout-flow"
  "admin-operations"
)

failed=0
for scenario in "${scenarios[@]}"; do
  echo "Testing: $scenario"
  if ! stoobly-agent scenario test $scenario --strategy diff --output-level failed; then
    ((failed++))
    echo "❌ Failed: $scenario"
  else
    echo "✅ Passed: $scenario"
  fi
done

if [ $failed -gt 0 ]; then
  echo "Failed $failed scenario(s)"
  exit 1
fi

echo "All scenarios passed!"

Q: How do I generate test reports from scenario tests?

A: Use JSON format and process the output.

Example:

#!/bin/bash
# Generate test report

timestamp=$(date +%Y%m%d_%H%M%S)
report_file="test-report-${timestamp}.json"

# Run tests and capture output
stoobly-agent scenario test abc123 --format json > "$report_file"

# Process results
passed=$(jq '[.results[] | select(.status=="passed")] | length' "$report_file")
failed=$(jq '[.results[] | select(.status=="failed")] | length' "$report_file")

echo "Test Report: $passed passed, $failed failed"
echo "Full report: $report_file"

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 test scenario
stoobly-agent scenario test main-flow --strategy diff
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]

Q: How do I conditionally execute scenarios?

A: Use scripts with conditional logic based on scenario results.

Example:

#!/bin/bash
# Conditional scenario execution

# Run smoke tests first
if stoobly-agent scenario test smoke-tests --output-level failed; then
  echo "Smoke tests passed, running full suite"
  stoobly-agent scenario test full-test-suite
else
  echo "Smoke tests failed, skipping full suite"
  exit 1
fi

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 test abc123 --log-level debug --output-level failed

# 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:

# Test with all output levels
stoobly-agent scenario test abc123 --output-level passed --log-level info

# This shows each request as it executes and its result

Q: How do I monitor scenario health over time?

A: Set up periodic scenario testing with result tracking.

Example:

#!/bin/bash
# Monitoring script

while true; do
  timestamp=$(date +%Y-%m-%d_%H:%M:%S)
  
  if stoobly-agent scenario test health-check --strategy fuzzy; then
    echo "$timestamp - HEALTHY"
  else
    echo "$timestamp - UNHEALTHY - ALERT SENT"
    # Send alert (email, Slack, PagerDuty, etc.)
  fi
  
  sleep 300  # Check every 5 minutes
done

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

# Test scenarios
stoobly-agent scenario test abc123
stoobly-agent scenario test abc123 --strategy diff
stoobly-agent scenario test abc123 --strategy contract --output-level failed

# 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-based testing?

A: Create → Record → Snapshot → Test → 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. Test regularly
stoobly-agent scenario test payment-flow --strategy diff

# 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 3 days 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 replay a scenario and record new responses?

Q: How do I replay 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?

Testing Scenarios

Q: How do I test a scenario to validate responses?

Q: What test strategies are available for scenarios?

Q: How do I continue testing even if a request fails?

Q: How do I control which test results are displayed?

Q: How do I filter which properties are tested?

Q: How do I test a scenario with mock dependencies?

Q: How do I save test results to a report?

Q: How do I save test results?

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?

Environment-Specific Scenarios

Q: How do I run the same scenario against different environments?

Q: How do I create environment-specific scenarios?

CI/CD Integration

Q: How do I use scenarios in CI/CD pipelines?

Q: How do I generate test reports from scenario tests?

Advanced Scenario Operations

Q: How do I chain multiple scenarios?

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

Q: How do I conditionally execute scenarios?

Monitoring and Debugging

Q: How do I debug a failing scenario?

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

Q: How do I monitor scenario health over time?

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-based testing?