Snapshot

Stoobly Snapshot CLI - Questions & Answers

The snapshot CLI manages version-controlled snapshots of requests and scenarios. Snapshots create committable files that enable team collaboration, historical tracking, and reproducible testing through version control systems like Git.

---

Understanding Snapshots

Q: What are snapshots in Stoobly?

A: Snapshots are version-controlled, file-based representations of requests and scenarios that can be committed to Git. They enable team collaboration and historical tracking of API tests.

Example:

# Create snapshot of a request
stoobly-agent request snapshot "<REQUEST-KEY>"

# Create snapshot of a scenario
stoobly-agent scenario snapshot "<SCENARIO-KEY>"

# Snapshots are stored in .stoobly/snapshots/
ls .stoobly/snapshots/requests/
ls .stoobly/snapshots/scenarios/

Q: Why should I use snapshots?

A: Snapshots enable version control of your tests, team collaboration through Git, reproducible testing across environments, and historical tracking of API changes.

Example:

# Create snapshots
stoobly-agent scenario snapshot user-login

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

# Team members get the tests
git pull
stoobly-agent snapshot apply  # Apply all snapshots

Q: What's the difference between requests in the database and snapshots?

A: Database requests are local and ephemeral, while snapshots are file-based, version-controlled, and shareable across the team.

Example:

# Database: Local only
stoobly-agent request list  # Shows local requests

# Snapshots: Shareable via Git
stoobly-agent snapshot list  # Shows version-controlled snapshots
git add .stoobly/snapshots/ && git commit -m "Share tests"

---

Listing Snapshots

Q: How do I view all snapshots?

A: Use snapshot list to display all snapshots.

Example:

stoobly-agent snapshot list

Q: How do I list only request snapshots?

A: Use the --resource option to filter by resource type.

Example:

# List request snapshots (default)
stoobly-agent snapshot list --resource request

# Show more results
stoobly-agent snapshot list --resource request --size 50

Q: How do I list only scenario snapshots?

A: Specify scenario as the resource type.

Example:

stoobly-agent snapshot list --resource scenario

Q: How do I search for specific snapshots?

A: Use the --search option with a regex pattern to filter snapshots. The search behavior depends on the resource type:

• For request snapshots (default): The regex matches from the start of the URL or the start of the path. For example, docs.stoobly.com will not match https://docs.stoobly.com because the search starts from the beginning of the URL. Use https://docs.stoobly.com or .*?docs.stoobly.com to match URLs containing the domain.

• For scenario snapshots (with --resource scenario): The regex matches from the start of the scenario name or the start of the scenario description.

Example:

# Search by URL path (matches from start of path)
stoobly-agent snapshot list --search "/api/users"

# Search by domain (use .*? to match anywhere in URL)
stoobly-agent snapshot list --search ".*?example.com"

# Search with regex (matches paths starting with /api/ and containing login)
stoobly-agent snapshot list --search "^/api/.*login"

# Search scenario names/descriptions (matches from start)
stoobly-agent snapshot list --resource scenario --search "^User.*"

Q: How do I filter snapshots by scenario name?

A: Use the --scenario option with a regex pattern.

Example:

# Filter by scenario name
stoobly-agent snapshot list --scenario "Login Flow"

# Filter with regex
stoobly-agent snapshot list --scenario "^User.*Flow$"

Q: How do I list pending (unprocessed) snapshots?

A: Use the --pending flag to show snapshots that haven't been applied yet.

Example:

stoobly-agent snapshot list --pending

Q: How do I limit the number of snapshots displayed?

A: Use the --size option to control the number of results.

Example:

# Show 20 snapshots
stoobly-agent snapshot list --size 20

# Show 50 snapshots
stoobly-agent snapshot list --size 50

Q: How do I format snapshot list output?

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

Example:

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

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

# CSV format
stoobly-agent snapshot 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 specific columns
stoobly-agent snapshot list --select uuid --select path --select method

# Minimal output
stoobly-agent snapshot list --select uuid --select snapshot --without-headers

---

Applying Snapshots

Q: How do I apply all snapshots?

A: Use snapshot apply without arguments to apply all available snapshots.

Example:

# Apply all snapshots from .stoobly/snapshots/
stoobly-agent snapshot apply

Q: How do I apply a specific snapshot?

A: Use snapshot apply with the snapshot UUID.

Example:

# Get UUID from list
stoobly-agent snapshot list

# Apply specific snapshot
stoobly-agent snapshot apply "<SNAPSHOT-UUID>"

Q: What happens when I apply a snapshot?

A: Applying a snapshot creates or updates the corresponding request or scenario in your local database from the snapshot file.

Example:

# Team member gets snapshots from git
git pull

# Apply snapshots to local database
stoobly-agent snapshot apply

# Now can replay/test the requests
stoobly-agent scenario replay user-login

Q: How do I force apply snapshots with hard delete?

A: Use the --force flag to hard delete existing resources when applying.

Example:

# Force apply all snapshots
stoobly-agent snapshot apply --force

# Force apply specific snapshot
stoobly-agent snapshot apply "<SNAPSHOT-UUID>" --force

Q: What's the difference between apply and reset?

A: snapshot apply creates/updates from snapshots, while request reset or scenario reset restores a specific resource from its snapshot.

Example:

# Apply all snapshots (bulk operation)
stoobly-agent snapshot apply

# Reset specific request (single operation)
stoobly-agent request reset "<REQUEST-KEY>"

# Reset specific scenario (single operation)
stoobly-agent scenario reset "<SCENARIO-KEY>"

---

Updating Snapshots

Q: How do I update an existing snapshot?

A: Use snapshot update with the snapshot UUID to create a new version.

Example:

# Get UUID from list
stoobly-agent snapshot list

# Update snapshot
stoobly-agent snapshot update "<SNAPSHOT-UUID>"-uuid

Q: How do I update a snapshot without verification?

A: Use the --no-verify flag to skip request verification.

Example:

stoobly-agent snapshot update "<SNAPSHOT-UUID>" --no-verify

Q: What does snapshot verification do?

A: Verification ensures the raw HTTP request format is valid and fixes any formatting issues before creating the snapshot.

Example:

# With verification (default) - fixes malformed requests
stoobly-agent snapshot update "<SNAPSHOT-UUID>"

# Without verification - takes request as-is
stoobly-agent snapshot update "<SNAPSHOT-UUID>" --no-verify

Q: How do I format the output when updating?

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

Example:

# JSON format
stoobly-agent snapshot update "<SNAPSHOT-UUID>" --format json

# Table format
stoobly-agent snapshot update "<SNAPSHOT-UUID>" --format table

---

Copying Snapshots

Q: How do I copy snapshots to a different directory?

A: Use snapshot copy with the destination path to copy snapshots between data directories.

Example:

# Copy request snapshot to different directory
stoobly-agent snapshot copy /path/to/other/project --request-key "<REQUEST-KEY>"

# Copy scenario snapshot
stoobly-agent snapshot copy /path/to/other/project --scenario-key "<SCENARIO-KEY>"

Q: How do I copy multiple requests at once?

A: Use multiple --request-key options to copy several requests.

Example:

stoobly-agent snapshot copy /path/to/destination \
  --request-key "<REQUEST-KEY-1>" \
  --request-key "<REQUEST-KEY-2>" \
  --request-key "<REQUEST-KEY-3>"

Q: How do I copy multiple scenarios at once?

A: Use multiple --scenario-key options to copy several scenarios.

Example:

stoobly-agent snapshot copy /path/to/destination \
  --scenario-key "<SCENARIO-KEY-1>" \
  --scenario-key "<SCENARIO-KEY-2>" \
  --scenario-key "<SCENARIO-KEY-3>"

Q: How do I copy both requests and scenarios together?

A: Combine both --request-key and --scenario-key options.

Example:

stoobly-agent snapshot copy /path/to/destination \
  --request-key "<REQUEST-KEY-1>" \
  --request-key "<REQUEST-KEY-2>" \
  --scenario-key "<SCENARIO-KEY-1>" \
  --scenario-key "<SCENARIO-KEY-2>"

Q: Why would I copy snapshots to a different directory?

A: Copying snapshots is useful for moving tests between projects, creating backups, or setting up separate test environments.

Example:

# Copy production tests to staging environment
stoobly-agent snapshot copy /path/to/staging \
  --scenario-key "<SCENARIO-KEY-1>" \
  --scenario-key "<SCENARIO-KEY-2>"

# In staging directory
cd /path/to/staging
stoobly-agent snapshot apply

---

Pruning Snapshots

Q: How do I clean up deleted snapshots?

A: Use snapshot prune to remove snapshot files for deleted resources.

Example:

stoobly-agent snapshot prune

Q: How do I preview what will be pruned without deleting?

A: Use the --dry-run flag to see what would be deleted.

Example:

# Preview prune operation
stoobly-agent snapshot prune --dry-run

# Actually prune
stoobly-agent snapshot prune

Q: When should I prune snapshots?

A: Prune after deleting scenarios or requests to keep your snapshot directory clean and your Git repository size manageable.

Example:

# Delete a scenario
stoobly-agent scenario delete old-scenario

# Clean up its snapshots
stoobly-agent snapshot prune

# Commit the cleanup
git add .stoobly/snapshots/
git commit -m "Remove old scenario snapshots"

---

Migrating Snapshots

Q: How do I migrate snapshots with custom transformations?

A: Use snapshot migrate with a lifecycle hooks script to transform snapshots during migration.

Example:

# Create migration script
cat > migrate.py << 'EOF'
def before_migrate(snapshot_migration):
    # Access snapshot data
    request = snapshot_migration.request_snapshot
    
    # Transform data (e.g., update host)
    raw_request = request.request
    if raw_request:
        raw_request = raw_request.replace('old-host.com', 'new-host.com')
        request.write_raw(raw_request)
    
    # Return False to continue, True to stop
    return False
EOF

# Run migration
stoobly-agent snapshot migrate migrate.py

Q: How do I migrate snapshots for a specific scenario only?

A: Use the --scenario-key option to limit migration scope.

Example:

stoobly-agent snapshot migrate migrate.py --scenario-key "<SCENARIO-KEY>"

Q: What can I do in a migration script?

A: Migration scripts can modify requests, update headers, change hosts, transform response data, or apply any custom logic to snapshots.

Example:

# Create advanced migration script
cat > migrate.py << 'EOF'
def before_migrate(snapshot_migration):
    request = snapshot_migration.request_snapshot
    raw_request = request.request
    
    if raw_request:
        # Update authentication tokens
        raw_request = raw_request.replace('old-token', 'new-token')
        
        # Update API version in path
        raw_request = raw_request.replace('/v1/', '/v2/')
        
        # Update host
        raw_request = raw_request.replace('api.old.com', 'api.new.com')
        
        # Save changes
        request.write_raw(raw_request)
    
    return False
EOF

stoobly-agent snapshot migrate migrate.py

Q: How do I debug migration scripts?

A: Add print statements or use Python debugging in your migration script.

Example:

cat > migrate.py << 'EOF'
def before_migrate(snapshot_migration):
    request = snapshot_migration.request_snapshot
    
    # Debug output
    print(f"Processing snapshot: {request.uuid}")
    print(f"Snapshot path: {request.path}")
    
    raw_request = request.request
    if raw_request:
        print(f"Request preview: {raw_request[:100]}")
        # Apply transformations...
    
    return False
EOF

stoobly-agent snapshot migrate migrate.py

---

Version Control Workflows

Q: How do I set up snapshots for Git?

A: Create snapshots and add the .stoobly/snapshots/ directory to Git.

Example:

# Create scenario with requests
stoobly-agent scenario create "User Login"
# ... add requests ...

# Create snapshot
stoobly-agent scenario snapshot user-login --decode

# Add to Git
git add .stoobly/snapshots/
git commit -m "Add user login test scenario"
git push

Q: How do team members use snapshots from Git?

A: Pull the repository and apply snapshots to get the tests.

Example:

# Clone or pull repository
git clone <repo-url>
cd <repo>

# Apply all snapshots
stoobly-agent snapshot apply

# Use the tests
stoobly-agent scenario list
stoobly-agent scenario test user-login

Q: How do I update existing snapshots in Git?

A: Re-create the snapshot and commit the changes.

Example:

# Make changes to scenario (add/remove requests)
stoobly-agent record <new-request> --scenario-key "<SCENARIO-KEY>"

# Update snapshot
stoobly-agent scenario snapshot user-login --decode

# Commit changes
git add .stoobly/snapshots/
git commit -m "Update user login with new endpoint"
git push

Q: How do I handle merge conflicts in snapshots?

A: Resolve conflicts manually in snapshot files or re-create snapshots from one version.

Example:

# Conflict occurs during merge
git merge feature-branch

# Option 1: Manual resolution
# Edit conflicted snapshot files in .stoobly/snapshots/
git add .stoobly/snapshots/
git commit

# Option 2: Re-create from one version
git checkout --theirs .stoobly/snapshots/scenarios/<SNAPSHOT-UUID>
stoobly-agent snapshot apply "<SNAPSHOT-UUID>"
# Test and verify
git add .stoobly/snapshots/
git commit

Q: Should I commit snapshot files or the database?

A: Commit snapshot files in .stoobly/snapshots/, NOT the database files in .stoobly/db/. Add .stoobly/db/ to .gitignore.

Example:

# .gitignore
.stoobly/db/
.stoobly/logs/
.stoobly/tmp/

# DO commit:
# .stoobly/snapshots/

---

Advanced Snapshot Operations

Q: How do I export snapshots for backup?

A: Copy the .stoobly/snapshots/ directory or use snapshot copy.

Example:

# Option 1: Direct copy
tar -czf snapshots-backup-$(date +%Y%m%d).tar.gz .stoobly/snapshots/

# Option 2: Use snapshot copy
stoobly-agent snapshot copy /backup/location \
  --scenario-key "<SCENARIO-KEY-1>" \
  --scenario-key "<SCENARIO-KEY-2>"

Q: How do I share snapshots across projects?

A: Use snapshot copy to move snapshots between project directories.

Example:

# In project A
stoobly-agent snapshot copy /path/to/project-b \
  --scenario-key "<SCENARIO-KEY>"

# In project B
cd /path/to/project-b
stoobly-agent snapshot apply

Q: How do I create snapshots in CI/CD?

A: Record requests during CI, create snapshots, and commit them back if needed.

Example:

#!/bin/bash
# CI/CD snapshot creation

# Run application and record tests
stoobly-agent run --intercept --intercept-mode record &
AGENT_PID=$!

# Run test suite (gets recorded)
npm test

# Stop agent
kill $AGENT_PID

# Create snapshots
for scenario in $(stoobly-agent scenario list --format json | jq -r '.[].key'); do
  stoobly-agent scenario snapshot $scenario --decode
done

# Check if snapshots changed
if git diff --exit-code .stoobly/snapshots/; then
  echo "No snapshot changes"
else
  echo "Snapshots updated"
  # Optionally commit back to repo
fi

Q: How do I validate snapshots in CI/CD?

A: Apply snapshots and run tests to ensure they're valid.

Example:

#!/bin/bash
# CI/CD snapshot validation

# Apply all snapshots
if ! stoobly-agent snapshot apply; then
  echo "Failed to apply snapshots"
  exit 1
fi

# List applied snapshots
stoobly-agent snapshot list

# Test scenarios from snapshots
for scenario in $(stoobly-agent scenario list --format json | jq -r '.[].key'); do
  echo "Testing scenario: $scenario"
  if ! stoobly-agent scenario test $scenario --strategy diff; then
    echo "Failed: $scenario"
    exit 1
  fi
done

echo "All snapshot scenarios validated"

---

Troubleshooting

Q: What do I do if snapshot apply fails?

A: Check for errors, use force option, or manually inspect the snapshot files.

Example:

# Try with force
stoobly-agent snapshot apply --force

# List pending snapshots to see what's not applied
stoobly-agent snapshot list --pending

# Check for specific errors
stoobly-agent snapshot apply "<SNAPSHOT-UUID>"

Q: How do I verify snapshot integrity?

A: Use snapshot update to verify and fix snapshot formatting.

Example:

# Verify and fix single snapshot
stoobly-agent snapshot update "<SNAPSHOT-UUID>"

# List all snapshots and update each
for uuid in $(stoobly-agent snapshot list --format json | jq -r '.[].uuid'); do
  stoobly-agent snapshot update $uuid
done

Q: How do I find which snapshot corresponds to a request?

A: List snapshots with search or match request keys to UUIDs.

Example:

# Search by path
stoobly-agent snapshot list --search "/api/users"

# List with specific format
stoobly-agent snapshot list --select uuid --select path --select snapshot

---

Best Practices

Q: When should I create snapshots?

A: Create snapshots after recording important test flows, before releases, and when sharing tests with the team.

Example:

# After recording a critical flow
stoobly-agent record <requests> --scenario-key "<SCENARIO-KEY>"
stoobly-agent scenario snapshot "<SCENARIO-KEY>" --decode
git add .stoobly/snapshots/ && git commit -m "Add checkout flow"

# Before release
./create-all-snapshots.sh
git tag -a v1.0.0 -m "Release 1.0.0 with test snapshots"

Q: How often should I prune snapshots?

A: Prune after deleting old tests or periodically to keep the repository clean.

Example:

# Monthly cleanup
stoobly-agent snapshot prune --dry-run  # Preview
stoobly-agent snapshot prune            # Execute
git add .stoobly/snapshots/
git commit -m "Prune deleted snapshots"

Q: When should I decode snapshots?

A: Use --decode when creating snapshots for better Git diffs and readability.

Example:

# Always use --decode for version control
stoobly-agent scenario snapshot "<SCENARIO-KEY>" --decode
stoobly-agent request snapshot "<REQUEST-KEY>" --decode

---

Quick Reference

Q: What are the most common snapshot commands?

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

Example:

# List snapshots
stoobly-agent snapshot list
stoobly-agent snapshot list --resource scenario
stoobly-agent snapshot list --search "/api/users"
stoobly-agent snapshot list --pending

# Apply snapshots
stoobly-agent snapshot apply              # Apply all
stoobly-agent snapshot apply "<SNAPSHOT-UUID>"       # Apply specific
stoobly-agent snapshot apply --force      # Force apply

# Update snapshots
stoobly-agent snapshot update "<SNAPSHOT-UUID>"
stoobly-agent snapshot update "<SNAPSHOT-UUID>" --no-verify

# Copy snapshots
stoobly-agent snapshot copy /path/to/dest --scenario-key "<SCENARIO-KEY>"
stoobly-agent snapshot copy /path/to/dest --request-key "<REQUEST-KEY>"

# Prune snapshots
stoobly-agent snapshot prune --dry-run
stoobly-agent snapshot prune

# Migrate snapshots
stoobly-agent snapshot migrate migrate.py
stoobly-agent snapshot migrate migrate.py --scenario-key "<SCENARIO-KEY>"

---

Integration Examples

Q: How do I automate snapshot creation?

A: Use a script to create snapshots for all scenarios.

Example:

#!/bin/bash
# Create snapshots for all scenarios

for scenario in $(stoobly-agent scenario list --format json | jq -r '.[].key'); do
  echo "Creating snapshot for: $scenario"
  stoobly-agent scenario snapshot $scenario --decode
done

echo "All snapshots created"

Q: How do I sync snapshots across environments?

A: Use Git to sync and snapshot copy for different data directories.

Example:

# Development: Create and push snapshots
stoobly-agent scenario snapshot critical-tests --decode
git add .stoobly/snapshots/ && git commit -m "Update tests" && git push

# Staging: Pull and apply
git pull
stoobly-agent snapshot apply

# Production: Copy from staging
stoobly-agent snapshot copy /production/path --scenario-key "<SCENARIO-KEY>"