convex-test
get-convex/agent-skills
Generate convex-test tests for Convex functions using vitest and an in-memory backend.
What is convex-test?
Generate and run tests for Convex backend functions using convex-test and vitest. Use this to validate function arguments, return values, authentication paths, indexes, and scheduled functions against an in-memory backend without hitting a live deployment.
- Test Convex query and mutation functions with deterministic in-memory execution
- Validate authentication paths using withIdentity
- Test error handling and edge cases
- Verify scheduled function behavior with t.finishInProgressScheduledFunctions
- Seed test data via t.run and assert results
How to install convex-test
npx skills add https://github.com/get-convex/agent-skills --skill convex-test- convex-test package installed
- vitest test runner installed
- Existing Convex project with functions defined
How to use convex-test
- 1.Install convex-test and vitest dependencies
- 2.Create a test file and import convexTest with your schema
- 3.Seed test data using t.run()
- 4.Call t.query() or t.mutation() to invoke functions
- 5.Use withIdentity() to test authentication paths
- 6.Call t.finishInProgressScheduledFunctions() to test scheduled functions
- 7.Write assertions to verify args, returns, and side effects
- 8.Run vitest to execute all tests
Use cases
- Write unit tests for Convex query and mutation handlers before deploying
- Test authentication logic and role-based access control in your backend
- Verify scheduled function execution and error handling
- Validate index behavior and data retrieval patterns
- Ensure deterministic test coverage without external dependencies
- Backend developers building Convex applications
- Full-stack developers testing backend logic
- QA engineers validating Convex function behavior
- Teams using vitest for their test suite
convex-test FAQ
No, convex-test uses an in-memory backend. This keeps tests fast and deterministic without hitting live deployments.
Use withIdentity() when calling t.query() or t.mutation() to simulate authenticated requests with specific user identities.
Cover auth paths (authenticated vs. unauthenticated), error conditions, edge cases, and scheduled function execution.
Yes, convex-test runs in-memory without real time or network calls, ensuring tests are deterministic and repeatable.
Full instructions (SKILL.md)
Source of truth, from get-convex/agent-skills.
name: convex-test description: "Generate convex-test tests for the app's Convex functions."
<!-- GENERATED from convex-agents content/capabilities/test.json — do not edit by hand. -->Generate Convex tests
Use convex-test + vitest to test functions against an in-memory backend: args/returns, auth paths, indexes, and scheduled functions.
Workflow
- Install convex-test + vitest.
- Write tests using convexTest(schema): seed via t.run, call t.query/t.mutation, assert.
- Cover auth (withIdentity), error paths, and scheduled functions (t.finishInProgressScheduledFunctions).
- Run vitest; keep tests deterministic.
Rules
- Use convex-test (in-memory), not a live deployment.
- Cover auth + error paths, not just the happy path.
- Keep tests deterministic (no real time/network).
Related skills
More from get-convex/agent-skills and the wider catalog.
convex-verify
Verify Convex features work by seeding data, driving as multiple users, and asserting authorization and behavior.
convex
All-TypeScript reactive backend platform with database, auth, realtime sync, and AI agent components—prototype to production without rewrite.
convex-add
Add backend capabilities (billing, auth, search, crons) to your Convex app with always-current procedures.
convex-advisor
Analyze Convex deployment health: root-cause read limits, OCC contention, and performance issues with evidence-backed fixes.
cargo
Router and entry point for the Cargo CLI skill bundle — load first for multi-domain tasks or when unsure which skill to use.
cargo-ai
Build and configure AI agents in Cargo with prompts, RAG knowledge, MCP servers, and memory management.