The rf test command starts a local development server with a web interface for testing your agents. Features live reload, real-time monitoring, and zero configuration.
Basic Usage
Features
- ⚡ Zero configuration - Auto-detects agent from
.runflow/rf.json
- 🔄 Live reload - Automatically restarts on file changes
- 🌐 Web portal with real-time monitoring
- 🚀 Auto browser - Opens automatically at
http://localhost:PORT
- 📊 Traces storage - Saved locally in
.runflow/traces.json
- 🎯 Smart ports - Auto-selects available port (3000-4000)
Options
| Option | Description | Example |
|---|
-p, --port <port> | Specify port number | rf test --port 4500 |
--no-browser | Don’t open browser automatically | rf test --no-browser |
Examples
Start Test Server
# Start with default settings (auto-detects port, opens browser)
cd agent-name/
rf test
http://localhost:PORT/agents/your-agent/test-monitor
Specify Port
# Start on specific port
rf test --port 4500
http://localhost:4500/agents/your-agent/test-monitor
Without Browser
# Start server without opening browser
rf test --no-browser
http://localhost:PORT/agents/your-agent/test-monitor
How It Works
- Auto-detection: The CLI reads
.runflow/rf.json in the current directory to identify the agent
- Port Selection: Automatically finds an available port between 3000-4000
- Web Server: Starts a local server with full observability features
- Browser: Opens the test monitor interface automatically (unless
--no-browser is used)
- File Watcher: Monitors your code for changes
- Live Reload: Automatically restarts on file save
- Real-time Monitoring: See execution traces, costs, and performance metrics in real-time
- Local Storage: All traces are saved to
.runflow/traces.json for analysis
Live Reload
The test server automatically detects file changes and reloads:
cd my-agent/
rf test
# 1. Edit src/index.ts in your editor
# 2. Save the file
# 3. Server automatically detects changes
# 4. Agent reloads with new code
# 5. Test immediately in web interface
- All
.ts and .js files in src/
package.json.runflow/rf.json
No need to restart the server! Just save your files and test.
Web Interface Features
The local web portal provides:
- 📊 Real-time execution monitoring
- 💰 Cost tracking (tokens and costs per execution)
- ⏱️ Performance metrics (duration, latency)
- 🔍 Trace inspection (full execution details)
- 🧪 Interactive testing (send test messages)
- 📝 Execution history (stored locally)
- 🔄 Live reload status (shows when code changes)
Testing Workflow
# 1. Navigate to your agent directory
cd my-agent/
# 2. Start test server (opens browser automatically)
rf test
# → Server started at http://localhost:3847
# → Browser opened
# 3. Test your agent in web interface:
# - Send test messages
# - View real-time traces
# - Check costs and performance
# - Debug issues
# 4. Make changes to your code
# ... edit src/index.ts in your editor ...
# ... save file ...
# 5. Changes automatically reload (watch console)
# → File changed: src/index.ts
# → Reloading agent...
# → Agent reloaded
# 6. Test updated agent immediately (no restart needed)
# 7. Repeat steps 4-6 until satisfied
# 8. Stop server (Ctrl+C) and deploy
rf agents deploy
Development Best Practices
Rapid Iteration
# Terminal 1: Keep test server running
cd my-agent/
rf test
# Terminal 2 / IDE: Make changes
# Edit code → Save → Test
# Edit code → Save → Test
# Repeat...
Testing with Knowledge Base
# 1. Create and populate KB
rf kb create test-kb --embedding "OpenAI Small"
rf kb upload test-kb ./test-docs --yes
# 2. Update agent to use KB
# ... edit src/index.ts to reference 'test-kb' ...
# 3. Test with live reload
rf test
# → Make changes → Auto-reload → Test
Debugging
The web interface shows detailed traces:
Execution: exec_abc123
Duration: 2.4s
Cost: $0.0023
Status: Success
Traces:
└─ Agent Start
├─ KB Query: "user question"
│ └─ Results: 3 chunks (0.92, 0.87, 0.81)
├─ LLM Call: gpt-4
│ └─ Tokens: 450 in, 120 out
└─ Agent Complete
Local Traces
All execution traces are saved to .runflow/traces.json in a structured format:
{
"executionId_1": {
"traces": [...],
"summary": {...}
},
"executionId_2": {
"traces": [...],
"summary": {...}
}
}
- Analyze execution patterns
- Debug issues offline
- Track performance over time
- Compare different executions
Troubleshooting
Port Already in Use
If you see a port conflict error:
# Specify a different port
rf test --port 4500
# Or let it auto-select
rf test
# → Port 3847 in use, trying 3848...
Agent Not Detected
Make sure you’re in the agent directory with .runflow/rf.json:
# Check if file exists
ls .runflow/rf.json
# If not, you're in the wrong directory
cd path/to/my-agent/
rf test
Error: No agent configuration found
rf agents clone first.
Browser Doesn’t Open
If the browser doesn’t open automatically:
# Start without browser and open manually
rf test --no-browser
# Check terminal for URL
# Server started at http://localhost:3847
# Open manually in browser
open http://localhost:3847
Live Reload Not Working
If changes aren’t detected:
- Check file location - Only files in
src/ are watched
- Save file properly - Ensure file is actually saved
- Check console - Look for reload messages
- Restart server - Press Ctrl+C and run
rf test again
# Manual restart if needed
# Ctrl+C to stop
rf test
Dependencies Not Installed
rf test
# Error: Cannot find module 'some-package'
npm install
# or
yarn install
# or
pnpm install
# Then try again
rf test
API Key Missing
rf test
# Error: No API key found
# Login first
rf login
# Then test
rf test
Traces Not Saving
If traces aren’t saved to .runflow/traces.json:
- Check permissions - Ensure write access to
.runflow/
- Check disk space - Ensure sufficient space
- Check file -
cat .runflow/traces.json
# Fix permissions if needed
chmod -R 755 .runflow/
# Test again
rf test
Advanced Usage
Custom Port
# Use specific port (useful for consistent URLs)
rf test --port 3000
# Always accessible at same URL
# http://localhost:3000
Multiple Agents
# Terminal 1
cd agent-1/
rf test --port 3000
# Terminal 2
cd agent-2/
rf test --port 3001
# Terminal 3
cd agent-3/
rf test --port 3002
CI/CD Testing
#!/bin/bash
# Test agent in CI pipeline
cd my-agent/
rf test --no-browser --port 4000 &
TEST_PID=$!
# Wait for server to start
sleep 5
# Run automated tests against http://localhost:4000
curl http://localhost:4000/health
npm run test:integration
# Stop test server
kill $TEST_PID
Fast Iteration
- Keep server running - don’t restart
- Use live reload - save and test
- Monitor console for reload status
- Check traces for bottlenecks
Debugging Slow Responses
The web interface shows timing breakdown:
Execution Time: 5.2s
├─ KB Query: 1.2s
├─ LLM Call: 3.8s
└─ Other: 0.2s
Next Steps
