Local Testing - Runflow

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

cd my-agent/
rf test

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

The web interface will automatically open at:

http://localhost:PORT/agents/your-agent/test-monitor

Specify Port

# Start on specific port
rf test --port 4500

Access at: http://localhost:4500/agents/your-agent/test-monitor

Without Browser

# Start server without opening browser
rf test --no-browser

Then manually open: 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

Watched files:

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": {...}
  }
}

This allows you to:

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:

Error: No agent configuration found

Solution: Navigate to correct directory or run 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'

Solution:

npm install
# or
yarn install
# or
pnpm install

# Then try again
rf test

API Key Missing

rf test
# Error: No API key found

Solution:

# 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

Performance Tips

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

Identify and optimize slow components.

Next Steps

Agents

Deploy your tested agent

Knowledge Base

Test with knowledge base

Prompts

Test prompt changes

Observability

Learn about observability features

​Basic Usage

​Features

​Options

​Examples

​Start Test Server

​Specify Port

​Without Browser

​How It Works

​Live Reload

​Web Interface Features

​Testing Workflow

​Development Best Practices

​Rapid Iteration

​Testing with Knowledge Base

​Debugging

​Local Traces

​Troubleshooting

​Port Already in Use

​Agent Not Detected

​Browser Doesn’t Open

​Live Reload Not Working

​Dependencies Not Installed

​API Key Missing

​Traces Not Saving

​Advanced Usage

​Custom Port

​Multiple Agents

​CI/CD Testing

​Performance Tips

​Fast Iteration

​Debugging Slow Responses

​Next Steps

Agents

Knowledge Base

Prompts

Observability

Basic Usage

Features

Options

Examples

Start Test Server

Specify Port

Without Browser

How It Works

Live Reload

Web Interface Features

Testing Workflow

Development Best Practices

Rapid Iteration

Testing with Knowledge Base

Debugging

Local Traces

Troubleshooting

Port Already in Use

Agent Not Detected

Browser Doesn’t Open

Live Reload Not Working

Dependencies Not Installed

API Key Missing

Traces Not Saving

Advanced Usage

Custom Port

Multiple Agents

CI/CD Testing

Performance Tips

Fast Iteration

Debugging Slow Responses

Next Steps