Skip to main content
Keep your tests beside your agent code. Each Markdown file describes one situation and the behaviors you expect from the agent. Before you write, read your agent’s prompt, tools, and startup code. Use the same tool names, response shapes, and context that the agent uses in production. The Egma skills can help you do this from your coding agent.

​
Choose a test suite

If this repository is new to Egma, follow the Skills and CLI guide first. Otherwise, pull the current project and list its personas:
Use an existing directory under egma/tests/, or create a suite:

​
Write one situation

Create egma/tests/appointment-booking/book-consultation.md. This example assumes a LiveKit agent with check_availability and book_appointment tools. Match the tool names and answers to your agent before running it. Both tools are mocked, so these calls use the test’s answers. Use a LiveKit voice connection with the Egma simulation hook configured for this example.
Use one clear claim per expected behavior. The grader checks each statement against the completed conversation. Three or four concrete checks are usually enough for one situation. Put an unrelated failure case in another test. The grader receives the transcript and tool names and arguments, but not tool return payloads. For a fixed mock, name the expected outcome in the behavior statement. Inspect the tool result in the transcript when you need to check what the backend returned.

​
Set Env

Env supplies context before the conversation starts. It does not set shell environment variables or store provider credentials. For LiveKit, the example’s job_dispatch_metadata is available as ctx.job.metadata. Parse that value as JSON in your worker and use the same field names your worker expects. For Retell, replace job_dispatch_metadata with retell_dynamic_variables. Every value must be a string, and variable names must match those used by your agent. Names starting with egma_ are reserved. Use realistic test data and keep secrets out of the file. Include only the provider field your agent needs. Omit ## Env when no startup context is needed. Omit ## Mock tools when no tools are mocked. Keep the remaining sections in the order shown above.

​
Push and run

Push checks the complete repository before it applies the changes. It writes the resolved persona IDs and synchronization fields back into your test files. Keep those fields when you edit an existing test. Do not invent version or identity_revision values for a new test. Start a run, read the individual behavior results, and inspect the cited conversation evidence before changing the test or the agent.
Tools not named in a test’s mock section run normally. Use a supported connection. Every LiveKit simulation requires the SDK’s simulation helper before the agent session starts, including tests without mocks. See Mock tool responses.