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 flowstoobly-agentscenariocreate"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:
Creating Scenarios
Q: How do I create a new scenario?
A: Use scenario create with a descriptive name for your scenario.
Example:
Q: How do I create a scenario with a description?
A: Use the --description option to add context to your scenario.
Example:
Q: How do I create a scenario in a specific project?
A: Use the --project-key option to specify the project (remote features).
Example:
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:
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:
Listing Scenarios
Q: How do I view all scenarios?
A: Use scenario list to display all scenarios with pagination.
Example:
Q: How do I paginate through scenarios?
A: Use the --page and --size options to control pagination.
Example:
Q: How do I search for specific scenarios?
A: Use the --search option to filter scenarios by name or description.
Example:
Q: How do I sort scenarios?
A: Use --sort-by and --sort-order options to control sorting.
Example:
Q: How do I format the scenario list output?
A: Use the --format option to change output format.
Example:
Q: How do I select specific columns to display?
A: Use the --select option to choose which columns to show.
Example:
Viewing Scenario Details
Q: How do I view details about a specific scenario?
A: Use scenario show with the scenario key.
Example:
Q: How do I format scenario details output?
A: Use the --format option to control the display format.
Example:
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:
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:
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:
Q: How do I replay a scenario with a different scheme?
A: Use the --scheme option to change the protocol for all requests.
Example:
Q: How do I update a scenario and by adding new responses?
A: Use the --record flag to capture the replayed responses.
Example:
Q: How do I update a scenario and overwrite existing responses?
A: Use the --overwrite flag to replace stored responses (local mode only).
Example:
Q: How do I replay a scenario and save to history?
A: Use the --save flag to persist the replay session (local mode).
Example:
Q: How do I replay a scenario with custom lifecycle hooks?
A: Use the --lifecycle-hooks-path option to apply custom processing.
Example:
Q: How do I increase logging verbosity when replaying?
A: Use the --log-level option to see more details.
Example:
Q: How do I format the replay response output?
A: Use the --format option to control response display.
Example:
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:
Q: How do I validate alias values during scenario execution?
A: Use the --validate option to specify validation rules for aliases.
Example:
Q: How do I control alias resolution strategy?
A: Use the --alias-resolve-strategy option to specify how aliases are resolved.
Example:
Q: How do I repeat scenario execution for each alias value?
A: Use the --group-by option to iterate over alias values.
Example:
Q: How do I use an existing trace for scenario execution?
A: Use the --trace-id option to leverage a previous trace.
Example:
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:
Q: How do I delete a scenario snapshot?
A: Use the --action delete option with snapshot command.
Example:
Q: How do I snapshot a scenario with decoded response bodies?
A: Use the --decode flag to decode response bodies in the snapshot.
Example:
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:
Q: How do I force delete when resetting a scenario?
A: Use the --force flag to hard delete the scenario data.
Example:
Q: How do I share scenarios with my team via git?
A: Create snapshots and commit them to version control.
Example:
Deleting Scenarios
Q: How do I delete a scenario?
A: Use scenario delete with the scenario key.
Example:
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:
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:
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
Option 2: Replay an existing request and add it to the scenario
Option 3: Add multiple new requests to a scenario
Q: How do I test multiple scenarios in sequence?
A: Use a script to test scenarios one after another.
Example:
Advanced Scenario Operations
Q: How do I chain multiple scenarios?
A: Use a script to execute scenarios in sequence with dependency handling.
Example:
Q: How do I extract data from one scenario to use in another?
A: Use aliases and traces to pass data between scenarios.
Example:
Monitoring and Debugging
Q: How do I debug a failing scenario?
A: Increase log level and use verbose output.
Example:
Q: How do I identify which request in a scenario is failing?
A: Use detailed output and logging to track request execution.
Example:
Quick Reference
Q: What are the most common scenario commands?
A: Here's a quick reference of frequently used commands:
Example:
Best Practices
Q: How should I organize my scenarios?
A: Group related requests by user flow, feature area, or test type.
Example:
Q: How often should I snapshot scenarios?
A: Snapshot after significant changes or before releases.
Example:
Q: What's the recommended workflow for scenario management?
# First, create the scenario and note the key
stoobly-agent scenario create "User Login Flow"
# Output: Created scenario with key: <SCENARIO-KEY>
# Then record requests to that scenario
stoobly-agent record -X POST -d '{"username":"user","password":"pass"}' https://api.example.com/login --scenario-key "<SCENARIO-KEY>"
# Or replay and record to the scenario
stoobly-agent request replay "<REQUEST-KEY>" --record --scenario-key "<SCENARIO-KEY>"
stoobly-agent scenario list
# 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
# Search by name
stoobly-agent scenario list --search "login"
# Search by description
stoobly-agent scenario list --search "payment"
# 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
# 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
# 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
stoobly-agent scenario show "<SCENARIO-KEY>"
# JSON format for scripting
stoobly-agent scenario show "<SCENARIO-KEY>" --format json
# Table format for readability
stoobly-agent scenario show "<SCENARIO-KEY>" --format table
# Show all details including request count
stoobly-agent scenario show "<SCENARIO-KEY>"
# Select specific fields
stoobly-agent scenario show "<SCENARIO-KEY>" --select name --select request_count
# Record multiple endpoints and add them all to the same scenario
stoobly-agent record https://api.example.com/endpoint1 --scenario-key "<SCENARIO-KEY>"
stoobly-agent record https://api.example.com/endpoint2 --scenario-key "<SCENARIO-KEY>"
stoobly-agent record https://api.example.com/endpoint3 --scenario-key "<SCENARIO-KEY>"
#!/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!"
#!/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"
# 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]
# Debug with verbose logging
stoobly-agent scenario replay "<SCENARIO-KEY>" --log-level debug
# Replay with logging to see each request
stoobly-agent scenario replay "<SCENARIO-KEY>" --log-level info
# Replay with detailed logging
stoobly-agent scenario replay "<SCENARIO-KEY>" --log-level info
# This shows each request as it executes
# 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"
# After adding new requests
stoobly-agent scenario snapshot "<SCENARIO-KEY>" --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
# 1. Create scenario
stoobly-agent scenario create "Payment Flow"
# 2. Record requests
stoobly-agent record "<URL-1>" --scenario-key "<SCENARIO-KEY>"
# 3. Snapshot for version control
stoobly-agent scenario snapshot "<SCENARIO-KEY>" --decode
git add .stoobly/snapshots/ && git commit -m "Add payment flow"
# 4. Replay regularly
stoobly-agent scenario replay "<SCENARIO-KEY>"
# 5. Update when needed
stoobly-agent record "<URL-2>" --scenario-key "<SCENARIO-KEY>"
stoobly-agent scenario snapshot "<SCENARIO-KEY>" --decode
git commit -am "Update payment flow with new endpoints"
