The intercept CLI allows you to dynamically configure the stoobly-agent after it's already running with stoobly-agent run. This enables you to change modes, policies, and strategies without restarting the agent.
Getting Started with Intercept
Q: What is the intercept feature?
A: Intercept is a feature that allows the stoobly-agent proxy to capture, modify, and control HTTP requests in real-time. You can enable/disable it and configure its behavior while the agent is running.
Example:
# Start the agentstoobly-agentrun# In another terminal, enable interceptstoobly-agentinterceptenable
Q: How do I check the current intercept configuration?
A: Use the intercept show command to display the current mode, policy, strategy, and status.
Example:
stoobly-agentinterceptshow# Output: Mock with policy: 'found', strategy: 'None', enabled
Enabling and Disabling Intercept
Q: How do I enable intercept mode?
A: Use stoobly-agent intercept enable to activate request interception on a running agent.
Example:
Q: How do I disable intercept mode?
A: Use stoobly-agent intercept disable to deactivate request interception without stopping the agent.
Example:
Q: Can I enable intercept when starting the agent?
A: Yes, use the --intercept flag when running the agent to enable it at startup.
Example:
Configuring Intercept Modes
Q: What intercept modes are available?
A: There are four intercept modes: mock, record, replay, and test (test requires remote features enabled).
Example:
Q: How do I switch from record mode to mock mode?
A: Use the intercept configure --mode command to change modes while the agent is running.
Example:
Q: What happens when I change the intercept mode?
A: When you change modes, intercept is automatically disabled, the mode is updated, and you need to re-enable intercept for the new mode to take effect.
Example:
Mock Mode Configuration
Q: What is mock mode?
A: Mock mode serves previously recorded responses instead of making real HTTP requests, useful for testing without external dependencies.
Example:
Q: What policies are available for mock mode?
A: Mock mode supports two policies: all (mock all requests) and found (only mock requests with recorded responses).
Example:
Q: How do I configure mock mode to only serve recorded responses?
A: Set the mock policy to found to only mock requests that have matching recorded responses.
Example:
Record Mode Configuration
Q: What is record mode?
A: Record mode captures HTTP requests and responses as they pass through the proxy, storing them for later replay or mocking.
Example:
Q: What policies are available for record mode?
A: Record mode supports four policies: all, api, found, and not_found.
Example:
Q: What recording strategies are available?
A: Record mode supports two strategies: full (capture complete request/response) and minimal (capture only essential data).
Example:
Q: What recording orders are available?
A: Record mode supports two orders: append (add new records) and overwrite (replace existing records).
Example:
Q: How do I configure record mode to only capture new requests?
A: Set the record policy to not_found to only record requests that haven't been captured before.
Example:
Q: How do I configure record mode to overwrite existing recordings?
A: Set the record order to overwrite to replace existing recordings with new captures.
Example:
Replay Mode Configuration
Q: What is replay mode?
A: Replay mode re-executes previously recorded requests, useful for testing and debugging.
Example:
Q: What policies are available for replay mode?
A: Replay mode currently supports the all policy to replay all intercepted requests.
Example:
Test Mode Configuration
Q: What is test mode?
A: Test mode validates responses against expected results, useful for automated testing and contract validation.
Example:
Q: What policies are available for test mode?
A: Test mode supports the found policy to only test requests with recorded responses.
Example:
Q: What test strategies are available?
A: Test mode supports four strategies: contract, custom, diff, and fuzzy.
Example:
Q: How do I set up contract testing?
A: Configure test mode with the contract strategy to validate responses against defined schemas.
Example:
Advanced Configuration
Q: Can I configure multiple options at once?
A: Yes, you can combine mode, policy, strategy, and order options in a single command.
Example:
Q: How do I configure intercept for a specific scenario?
A: First configure the mode and settings, then enable intercept. Use lifecycle hooks for scenario-specific logic.
Example:
Workflow Examples
Q: How do I set up a record-then-mock workflow?
A: Start by recording requests, then switch to mock mode to replay them. Optionally create a scenario before recording to organize your requests.
Example:
Q: How do I set up continuous recording with overwrite?
A: Configure record mode with overwrite order to always capture the latest responses.
Example:
Q: How do I set up automated testing with validation?
A: Configure test mode with your preferred validation strategy.
Example:
Troubleshooting
Q: What happens if I try to set an invalid policy for a mode?
A: The command will fail with an error message showing valid policies for that mode.
Example:
Q: Why does intercept get disabled when I change modes?
A: Changing modes requires reconfiguring the proxy behavior, so intercept is automatically disabled. You need to re-enable it after changing modes.
Example:
Q: How do I verify my intercept configuration is working?
A: Use intercept show to check the current configuration and status.
Example:
Q: Can I configure intercept before enabling it?
A: Yes, you can configure all settings first, then enable intercept to apply them.
Example:
Quick Reference
Q: What's a quick reference for common intercept commands?
A: Here are the most frequently used intercept commands:
Example:
Integration with Other Features
Q: How does intercept work with scenarios?
A: Intercept can be configured to work with specific scenarios for organized request management.
Example:
Q: Can I use intercept with lifecycle hooks?
A: Yes, intercept works seamlessly with lifecycle hooks for custom request/response processing.
stoobly-agent run --intercept --intercept-mode mock
# View available modes
stoobly-agent intercept configure --help
# Set to mock mode
stoobly-agent intercept configure --mode mock
# Set to record mode
stoobly-agent intercept configure --mode record
# Set to replay mode
stoobly-agent intercept configure --mode replay
# Set to test mode (if remote features enabled)
stoobly-agent intercept configure --mode test
# Currently in record mode, switch to mock
stoobly-agent intercept configure --mode mock
# Output: Updating intercept mode to mock
# Mock all requests
stoobly-agent intercept configure --mode mock --policy all
# Only mock requests that have recorded responses
stoobly-agent intercept configure --mode mock --policy found
stoobly-agent intercept configure --mode mock --policy found
stoobly-agent intercept enable
stoobly-agent intercept configure --mode record
stoobly-agent intercept enable
# Record all requests
stoobly-agent intercept configure --mode record --policy all
# Record only API requests
stoobly-agent intercept configure --mode record --policy api
# Record only requests with existing records
stoobly-agent intercept configure --mode record --policy found
# Record only new requests (not previously recorded)
stoobly-agent intercept configure --mode record --policy not_found
# Full recording (complete data)
stoobly-agent intercept configure --mode record --strategy full
# Minimal recording (essential data only)
stoobly-agent intercept configure --mode record --strategy minimal
# Append new recordings
stoobly-agent intercept configure --mode record --order append
# Overwrite existing recordings
stoobly-agent intercept configure --mode record --order overwrite
stoobly-agent intercept configure --mode record --policy not_found
stoobly-agent intercept enable
stoobly-agent intercept configure --mode record --order overwrite
stoobly-agent intercept enable
stoobly-agent intercept configure --mode replay --policy all
stoobly-agent intercept enable
stoobly-agent intercept configure --mode test
stoobly-agent intercept enable
stoobly-agent intercept configure --mode test --policy found
stoobly-agent intercept enable
# Contract testing (validate against schema)
stoobly-agent intercept configure --mode test --strategy contract
# Custom testing (use custom validation logic)
stoobly-agent intercept configure --mode test --strategy custom
# Diff testing (compare exact responses)
stoobly-agent intercept configure --mode test --strategy diff
# Fuzzy testing (allow minor variations)
stoobly-agent intercept configure --mode test --strategy fuzzy
stoobly-agent intercept configure --mode test --strategy contract --policy found
stoobly-agent intercept enable
# Configure record mode with all options
stoobly-agent intercept configure --mode record --policy not_found --strategy full --order append
# Configure test mode with strategy and policy
stoobly-agent intercept configure --mode test --strategy diff --policy found
# Configure for recording a specific API
stoobly-agent intercept configure --mode record --policy api --strategy full
stoobly-agent intercept enable
# Run your tests/requests
# ...
# Switch to mock mode for testing
stoobly-agent intercept configure --mode mock --policy found
stoobly-agent intercept enable
# Step 1: Start the agent
stoobly-agent run
# Step 2 (Optional): Create a scenario to organize requests
stoobly-agent scenario create "My User Flow"
# Output: Created scenario with key: <SCENARIO-KEY>
# Step 3: Configure and enable recording
stoobly-agent intercept configure --mode record --policy all --strategy full
stoobly-agent intercept enable
# Step 4: Make requests (they get recorded)
# ... perform your API calls ...
# Step 5: Switch to mock mode
stoobly-agent intercept configure --mode mock --policy found
stoobly-agent intercept enable
# Step 6: Run tests against mocked responses
# ... run your test suite ...
stoobly-agent run --intercept --intercept-mode record
# In another terminal
stoobly-agent intercept configure --mode record --order overwrite --policy all
# Start agent
stoobly-agent run
# Configure test mode with diff strategy
stoobly-agent intercept configure --mode test --strategy diff --policy found
stoobly-agent intercept enable
# Run your test suite - responses will be validated automatically
# This will fail if policy is invalid for the mode
stoobly-agent intercept configure --mode mock --policy not_found
# Output: Error: Valid policies for mock are ['all', 'found']
# Change mode (intercept disabled automatically)
stoobly-agent intercept configure --mode record
# Check status
stoobly-agent intercept show
# Output: Record with policy: 'all', strategy: 'full', disabled
# Re-enable intercept
stoobly-agent intercept enable
stoobly-agent intercept show
# Output: Mock with policy: 'found', strategy: 'None', enabled
# Configure first
stoobly-agent intercept configure --mode record --policy all --strategy full --order append
# Then enable
stoobly-agent intercept enable
# View current configuration
stoobly-agent intercept show
# Enable/disable intercept
stoobly-agent intercept enable
stoobly-agent intercept disable
# Switch modes
stoobly-agent intercept configure --mode mock
stoobly-agent intercept configure --mode record
stoobly-agent intercept configure --mode replay
stoobly-agent intercept configure --mode test
# Configure record mode
stoobly-agent intercept configure --mode record --policy all --strategy full --order append
# Configure mock mode
stoobly-agent intercept configure --mode mock --policy found
# Configure test mode
stoobly-agent intercept configure --mode test --strategy diff --policy found
# Complete workflow
stoobly-agent intercept configure --mode record --policy all
stoobly-agent intercept enable
# ... make requests ...
stoobly-agent intercept configure --mode mock --policy found
stoobly-agent intercept enable
# ... run tests ...
# Record requests to a scenario
stoobly-agent run --intercept --intercept-mode record --scenario-key "<SCENARIO-KEY>"
# Configure intercept for the scenario
stoobly-agent intercept configure --mode record --policy all
# Start with lifecycle hooks
stoobly-agent run --lifecycle-hooks-path ./hooks.py
# Configure intercept
stoobly-agent intercept configure --mode mock --policy found
stoobly-agent intercept enable
This comprehensive Q&A guide covers all aspects of the intercept CLI, providing users with clear examples for configuring and managing request interception dynamically while the agent is running.
