agent-recorder-fixtures

Overview

Use AgentRecorder to capture real provider payloads and generate paste-ready Swift fixtures for tests using ReplayHTTPClient. This is the fastest loop for keeping SwiftAgent’s unit tests (and agent-loop behavior) in sync with real OpenAI/Anthropic traffic.

Workflow

1. Pick the right scenario

• Existing scenarios live in AgentRecorder/AgentRecorder/Scenarios/ (grouped by provider + one file per scenario).
• List them quickly with AgentRecorder --list-scenarios.
• If no scenario matches your test, add one (keep it small and deterministic).

2. Set API keys

• Preferred: use a local Secrets.plist in the repo root (not committed).
  • Run with --secrets-plist Secrets.plist
  • Plist keys: OpenAI_API_Key_Debug / Anthropic_API_Key_Debug

Optional:

• Env vars fallback (useful for CI or quick runs): OPENAI_API_KEY, ANTHROPIC_API_KEY
• AGENT_RECORDER_SECRETS_PLIST is also supported (fallback if env vars are missing).

Legacy:

• If you already have Secrets.plist under Examples/Example App/ExampleApp/Secrets.plist, either move/symlink it to the repo root or pass the full path via --secrets-plist.

3. Run the recorder (Xcode or Terminal)

• Xcode: select AgentRecorder scheme, set env vars, Run → copy stdout from Debug console.
• Terminal:

# Run from repo root.
# Apple Silicon: add `arch=arm64` to avoid “multiple matching destinations” warnings.
xcodebuild -workspace SwiftAgent.xcworkspace -scheme AgentRecorder -destination "platform=macOS,arch=arm64" -derivedDataPath .tmp/DerivedData build -quiet
./.tmp/DerivedData/Build/Products/Debug/AgentRecorder --list-scenarios
./.tmp/DerivedData/Build/Products/Debug/AgentRecorder --secrets-plist Secrets.plist --provider openai --scenario openai/streaming-tool-calls/weather --no-include-headers

4. Paste fixtures into tests

• Output is already formatted for ReplayHTTPClient(recordedResponses:).
• Paste into the relevant test file (common locations):
  • Tests/SwiftAgentTests/OpenAISession/...
  • Tests/SwiftAgentTests/AnthropicSession/...

5. Run tests

• xcodebuild -workspace SwiftAgent.xcworkspace -scheme SwiftAgentTests -testPlan SwiftAgentTests test -quiet

Notes

• Headers may include secrets. HTTPReplayRecorder redacts common auth header fields, but always review before committing.
• Prefer --no-include-headers unless you’re explicitly testing header handling.
• Always pass -quiet to xcodebuild to keep logs readable.
• xcodebuild may print noisy destination warnings; ignore if the build succeeds.
• Streaming fixtures are raw text/event-stream. If the SDK stops consuming early, the recorded payload may be partial (this is usually fine for replaying the SDK’s behavior).
• If you need request bodies for debugging, re-run with --include-requests.
• OpenAI scenarios: keep models pinned/stable (scenario-defined). Change only when you’re updating fixtures/tests.
• Cleanup: if you used .tmp/DerivedData (and/or wrote capture files like .tmp/AgentRecorderOutput/*.txt), delete them after you’ve pasted fixtures into tests.