Getting Started

Installation

uv (recommended)pip

uv tool install voicetest

Or add to a project:

uv add voicetest

pip install voicetest

Quick start with the demo

The fastest way to see voicetest in action — a healthcare receptionist agent with 8 test cases:

# Set up an API key (free, no credit card at https://console.groq.com)
export GROQ_API_KEY=gsk_...

# Load demo and start interactive shell
voicetest demo

# Or load demo and start web UI
voicetest demo --serve

No API key? Use Claude Code

If you have Claude Code installed, skip API key setup and use claudecode/sonnet as your model. See Claude Code Passthrough.

The demo includes test cases covering appointment scheduling, identity verification, and more.

Interactive shell

# Launch interactive shell
voicetest

# In the shell:
> agent tests/fixtures/retell/sample_config.json
> tests tests/fixtures/retell/sample_tests.json
> set agent_model ollama_chat/qwen2.5:0.5b
> run

Web UI

Start the server and open http://localhost:8000:

voicetest serve

The web UI provides agent import, graph visualization, test execution with real-time streaming transcripts, run history, and more. See Features for the full list.

Running tests from the CLI

# Run all tests against an agent definition
voicetest run --agent agent.json --tests tests.json --all

# Chat with an agent interactively
voicetest chat -a agent.json --model openai/gpt-4o

See the CLI Reference for all commands.

Live voice calls

For live voice calls (not just simulated tests), you need infrastructure services. The up command starts LiveKit, Whisper STT, and Kokoro TTS via Docker:

# Start infrastructure + backend server
voicetest up

# Stop when done
voicetest down

If you only need simulated tests, voicetest serve is sufficient and does not require Docker.

CI/CD

Run voice agent tests in GitHub Actions to catch regressions before production:

name: Voice Agent Tests
on:
  push:
    paths: ["agents/**"]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install voicetest
      - run: voicetest run --agent agents/receptionist.json --tests agents/tests.json --all
        env:
          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}

Next steps

• Core Concepts — Understand agent graphs, node types, and test cases
• Configuration — Set up LLM models, settings, and platform credentials
• Features — Format conversion, diagnosis, audio evaluation, and more
• CLI Reference — All commands and options