CLI Reference

Mock Server extends the Robo CLI with commands for testing and server management.

Development Mode

robo dev --mock

Start your bot connected to Mock Server:

npx robo dev --mock

This:

1. Detects if a standalone mock server is already running
2. If yes: connects to the existing server and creates a new session
3. If no: starts an embedded mock server in the same process
4. Creates a test session and connects your bot
5. Opens Stage UI in your browser

Your bot receives events from Mock Server instead of Discord.

Options

npx robo dev --mock [session-id]

When no value is provided, auto-detection runs: if a standalone server is running it connects to it, otherwise it starts an embedded server. Pass a session ID or "new" to explicitly connect to an external server.

Examples

# Start fresh (auto-detect mode)
npx robo dev --mock

# Connect to existing session on external server
npx robo dev --mock sess_abc123xyz

# Create new session on external server
npx robo dev --mock new

Test Mode

robo mock test

Run integration tests with the mock Discord server:

npx robo mock test

This:

1. Starts a standalone Mock Server on port 6625
2. Auto-detects the test runner (Jest or Node)
3. Runs the test suite
4. Displays results in terminal and Stage UI
5. Keeps the server running for inspection (default behavior)

Options

npx robo mock test [options]

Test Runner Detection

When --runner is not specified, the test runner is auto-detected:

1. Check for Jest config files (jest.config.js, .ts, .mjs, .cjs, .json)
2. Check for jest key in package.json
3. Check if the test script uses node --test
4. Default to Jest if nothing else matches

Examples

# Run all tests (auto-detect runner)
npx robo mock test

# Use a specific port
npx robo mock test --port 4000

# Use Node test runner instead of Jest
npx robo mock test --runner node

# Run with verbose output
npx robo mock test --verbose

# Exit immediately after tests complete
npx robo mock test --no-watch

# Set a 60-second timeout
npx robo mock test --timeout 60

Standalone Server

robo mock start

Start Mock Server without a bot:

npx robo mock start

Useful for:

• Running tests from external processes
• Developing Stage UI
• Manual testing via Stage UI
• Connecting multiple bots to the same server

Options

npx robo mock start [options]

Examples

# Default port (6625)
npx robo mock start

# Custom port
npx robo mock start --port 4000

# Silent mode for CI
npx robo mock start --silent

# Verbose for debugging
npx robo mock start --verbose

# Don't open browser
npx robo mock start --no-browser

Terminal Commands

During robo dev --mock, the interactive terminal provides /mock commands for inspecting and managing the mock environment.

/mock

Show available subcommands:

/mock

/mock status

Display the mock session dashboard:

/mock status

Shows:

• Session ID, name, creation time
• Bot user and connection count
• Entity counts (guilds, channels, users, messages, commands, roles)
• Recorded action count
• Feature toggles (rate limit simulation, loop protection)

/mock stage

Open the Stage UI in your browser:

/mock stage

Opens the Stage UI for the currently targeted session.

/mock actions

List recorded bot actions:

/mock actions

# Show last 5 actions
/mock actions --limit 5

# Filter by type
/mock actions --type interaction_response

# Clear all actions
/mock actions --clear

/mock reset

Reset the session state:

/mock reset

Clears entities, actions, and voice servers while preserving the bot user identity and connections.

/mock command

Invoke a slash command as if a user typed it:

/mock command <name>

# Invoke /ping
/mock command ping

# Invoke in a specific channel
/mock command help --channel general

/mock sessions

List all active sessions:

/mock sessions

Displays a table of all sessions with their ID, name, creation time, connection count, guild count, and action count. The currently targeted session is marked with >.

/mock use

Switch which session subsequent commands target:

/mock use <session-id>

# Switch to a specific session
/mock use sess_abc123

# Show current target
/mock use

# Revert to dev session
/mock use --reset

When multiple sessions are active and no explicit selection has been made, commands show a hint suggesting /mock sessions.

Session Management

Via REST API

Sessions are managed through the control API:

# Create session
curl -X POST http://localhost:6625/api/control/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "my-test"}'

# List sessions
curl http://localhost:6625/api/control/sessions

# Get session details
curl http://localhost:6625/api/control/sessions/sess_xxx

# Dispatch an event to a session
curl -X POST http://localhost:6625/api/control/sessions/sess_xxx/dispatch \
  -H "Content-Type: application/json" \
  -d '{"event": "MESSAGE_CREATE", "data": {"channel_id": "123", "content": "Hello"}}'

When the mock server is running as a plugin (embedded mode), the control API is prefixed. For example: http://localhost:3000/mock/api/control/sessions.

Environment Variables

Set these before running commands:

# Enable mock mode explicitly
ROBO_MOCK_MODE=true npx robo dev

# Override port for standalone server
ROBO_MOCK_PORT=4000 npx robo mock start

# Test run ID for grouping
ROBO_MOCK_TEST_RUN_ID=run_123 npx robo mock test

Integration with npm Scripts

Add to package.json:

// package.json
{
  "scripts": {
    "dev:mock": "robo dev --mock",
    "test": "robo mock test",
    "test:quick": "robo mock test --no-watch",
    "mock:server": "robo mock start"
  }
}

Run with:

npm run dev:mock
npm test
npm run test:quick

Exit Codes

CI systems interpret these codes for pass/fail status.

Debugging

Verbose Mode

Enable debug logging:

npx robo mock test --verbose
npx robo mock start --verbose

Log File

Redirect logs to file:

npx robo mock test 2>&1 | tee test.log

Next Steps