Skip to main content
Run the tests for the code you changed, not the whole suite. The full suites are large and CI runs them on every pull request. All commands run from the repository root.

What to run for your change

Why mise test:one and not plain pytest. It runs pytest exactly as CI does: the same markers, the same default filter and the same timeout, but on one process. Running the full API suite starts several worker processes that each load the whole app, which can exhaust a laptop’s memory. TypeScript tests use Vitest. Web end-to-end tests use Playwright and drive a real browser against your running stack. Set E2E_SIM=1 to include the scripted-chat test.

The API test tiers

API tests live in apps/api/tests/, one folder per tier. A tier is a level of realism: a unit test replaces everything around the code with fakes, a real-infra test talks to real databases. By default pytest deselects the tests marked composio, model_onboarding and schemathesis. Real-infra and contract tests skip themselves unless USE_REAL_SERVICES=1 is set. Broader runs, when you need them:

Writing a test

The full conventions, including the fixture catalog, are in apps/api/tests/CLAUDE.md. The rules that matter most:
  1. It must be able to fail. Delete the line of product code the test is about. If the test still passes, it tests nothing.
  2. Assert behavior, not implementation. Check the response, the stored data or the returned value, not which internal function was called.
  3. Mock the edges, never the code under test. Fake the database, HTTP client or model. Never patch the function you are testing.
  4. Cover the failure path. Test what happens when a dependency fails, not only the happy path.
  5. Never assert on text an AI model wrote. Assert on structure, tool calls and state.
  6. Fixing a bug? Write the test first and watch it fail. A test you never saw fail proves nothing. Mark it @pytest.mark.regression, and CI checks that it really fails without your fix.
Search the shared fixtures before writing your own: tests/conftest.py (an authenticated client, fake_user, fake_redis), tests/factories.py (make_user, make_conversation) and tests/helpers.py (create_fake_llm). To start a new file, copy a scaffold from tests/_template/. Tests never see your real keys: at the start of a run, the suite blanks every environment variable that looks like a credential, so a test can’t call a paid API by accident.

Next

Debugging and logs

Find out what the API did on a request, and why.