# Testing Livekit Agents

Writes turn-level tests for a LiveKit agent in the user''s normal test suite: pytest...

- Repository: https://github.com/fcakyon/claude-codex-settings (1195 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add fcakyon/claude-codex-settings --skill testing-livekit-agents -g -a claude-code -y`
Codex: `npx skills add fcakyon/claude-codex-settings --skill testing-livekit-agents -g -a codex -y`
Cursor: `npx skills add fcakyon/claude-codex-settings --skill testing-livekit-agents -g -a cursor -y`
Gemini CLI: `npx skills add fcakyon/claude-codex-settings --skill testing-livekit-agents -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add fcakyon/claude-codex-settings`

## Description

Writes turn-level tests for a LiveKit agent in the user''s normal test suite: pytest (Python) or Vitest (Node.js). Use when the user asks to "write tests for my agent", "add a test for this tool", "test the handoff", "pin this bug", "why does my agent test fail", or after building or changing agent behavior that needs regression coverage. Covers the SDK''s test session harness, assertions on messages, tool calls and handoffs, LLM judging of a reply against an intent, mocking tools, multi-turn tests, and judging whole conversations with the built-in judges. For interactive poking use debugging-livekit-agents. For grading whole conversations at scale use running-livekit-simulations.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Testing LiveKit agents

Turn-level tests are the cheapest lasting verification an agent can have. They run in the user's
existing suite, in text mode, and they're fast enough for every commit. The framework's helper
names and signatures change, so look them up with `reading-livekit-docs` before writing, and use
the testing docs page for every API detail this skill leaves out.

Every test has the same shape: start a test session with the agent under test, run one user turn,
and assert on the events that turn produced.

## What a test asserts on

A turn produces a sequence of events. A simple turn is one message. A more typical one is a tool
call, its output, maybe a handoff, and then a message. You write the test by walking that sequence
in order, asserting on each event, and then asserting the turn has nothing more.

There are three kinds of assertion, and most of this skill is knowing which one to use.

**Structural** assertions check message roles, that a tool was called, its arguments, what it
returned, and that a handoff to a specific agent happened. They're deterministic and fail for
exactly one reason, so prefer them.

**Judged** assertions use an LLM-judge helper that gives one message and an intent string to a
model and asks whether they match. Use them for the content of a reply, which you can't assert
exactly. Describe the intent by outcome ("tells the user the booking is confirmed and gives the
time"), not by wording.

**Whole-conversation** assertions use a judge-group helper that runs several built-in judges
concurrently over the whole chat history and aggregates their verdicts. The built-in judges cover
dimensions like grounding, relevance, safety, task completion, and tool use; the docs list the
current set. Use this when the question spans several turns.

Rules of thumb:

The rest: https://github.com/fcakyon/claude-codex-settings/blob/HEAD/plugins/livekit-skills/skills/testing-livekit-agents/SKILL.md