> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Testing

> Test agents locally with web interface and live reload

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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# Start on specific port
rf test --port 4500
```

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

### Without Browser

```bash theme={null}
# Start server without opening browser
rf test --no-browser
```

Then manually open: `http://localhost:PORT/agents/your-agent/test-monitor`

## How It Works

1. **Auto-detection**: The CLI reads `.runflow/rf.json` in the current directory to identify the agent
2. **Port Selection**: Automatically finds an available port between 3000-4000
3. **Web Server**: Starts a local server with full observability features
4. **Browser**: Opens the test monitor interface automatically (unless `--no-browser` is used)
5. **File Watcher**: Monitors your code for changes
6. **Live Reload**: Automatically restarts on file save
7. **Real-time Monitoring**: See execution traces, costs, and performance metrics in real-time
8. **Local Storage**: All traces are saved to `.runflow/traces.json` for analysis

## Live Reload

The test server automatically detects file changes and reloads:

```bash theme={null}
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`

<Info>
  No need to restart the server! Just save your files and test.
</Info>

## 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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`:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

1. **Check file location** - Only files in `src/` are watched
2. **Save file properly** - Ensure file is actually saved
3. **Check console** - Look for reload messages
4. **Restart server** - Press Ctrl+C and run `rf test` again

```bash theme={null}
# Manual restart if needed
# Ctrl+C to stop
rf test
```

### Dependencies Not Installed

```bash theme={null}
rf test
# Error: Cannot find module 'some-package'
```

**Solution:**

```bash theme={null}
npm install
# or
yarn install
# or
pnpm install

# Then try again
rf test
```

### API Key Missing

```bash theme={null}
rf test
# Error: No API key found
```

**Solution:**

```bash theme={null}
# Login first
rf login

# Then test
rf test
```

### Traces Not Saving

If traces aren't saved to `.runflow/traces.json`:

1. **Check permissions** - Ensure write access to `.runflow/`
2. **Check disk space** - Ensure sufficient space
3. **Check file** - `cat .runflow/traces.json`

```bash theme={null}
# Fix permissions if needed
chmod -R 755 .runflow/

# Test again
rf test
```

## Advanced Usage

### Custom Port

```bash theme={null}
# Use specific port (useful for consistent URLs)
rf test --port 3000

# Always accessible at same URL
# http://localhost:3000
```

### Multiple Agents

```bash theme={null}
# 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

```bash theme={null}
#!/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

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/cli/agents">
    Deploy your tested agent
  </Card>

  <Card title="Knowledge Base" icon="database" href="/cli/kb">
    Test with knowledge base
  </Card>

  <Card title="Prompts" icon="file-lines" href="/cli/prompts">
    Test prompt changes
  </Card>

  <Card title="Observability" icon="chart-line" href="/core-concepts/observability">
    Learn about observability features
  </Card>
</CardGroup>