skill CX Codex

convex-test — Claude Code skill: what it does, how to install

Q: How to install convex-test in Claude Code?

Run `npx skills add convex/agent-skills --skill convex-test -a claude-code` in your project terminal.

Generates deterministic vitest tests for Convex backend functions using convex-test. Runs against an in-memory backend without live deployments.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓

npx skills add convex/agent-skills --skill convex-test -a claude-code

Open on GitHub

What convex-test does

This skill guides your coding agent to write tests for Convex functions with vitest. The test suite runs against an in-memory backend provided by convex-test, which eliminates the need for live deployments or network calls.

The workflow relies on convexTest(schema). Tests seed initial state via t.run, execute t.query or t.mutation, and assert expected outputs. The prompt enforces coverage for error cases, auth flows via withIdentity, and scheduled background jobs handled by t.finishInProgressScheduledFunctions.

Your project must have convex-test and vitest installed beforehand.

What it helps with

generate vitest test suites for Convex queries and mutations
test authentication logic using withIdentity mock identities
assert scheduled functions run correctly without real timers
validate database indexes and error paths in memory

Example prompts for the agent

Write convex-test vitest tests for our user profile mutation
Generate tests covering auth error paths using withIdentity for convex/tasks.ts
Create in-memory tests that verify scheduled functions finish with t.finishInProgressScheduledFunctions

How to install convex-test

1Skills CLI (Vercel)

npx skills add convex/agent-skills --skill convex-test -a claude-code

2Manually: put the files in place

~/.claude/skills/convex-test/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/convex-test/

1Skills CLI (Vercel)

npx skills add convex/agent-skills --skill convex-test -a codex

2Manually: put the files in place

.agents/skills/convex-test/SKILL.md

For all projects use ~/.agents/skills/

1Skills CLI (Vercel)

npx skills add convex/agent-skills --skill convex-test -a cursor

2Manually: put the files in place

.cursor/skills/convex-test/SKILL.md

Cursor also reads .agents/skills/ and .claude/skills/

1GitHub CLI

gh skill install convex/agent-skills convex-test

2Manually: put the files in place

.github/skills/convex-test/SKILL.md

1Skills CLI (Vercel)

npx skills add convex/agent-skills --skill convex-test -a gemini-cli

2Platform CLI

gemini skills install https://github.com/convex/agent-skills --path skills/convex-test

Manually: put the files in place

.devin/skills/convex-test/SKILL.md

The legacy .windsurf/skills/ path still works

Skills CLI (Vercel)

npx skills add convex/agent-skills --skill convex-test -a opencode

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about convex-test

How to install convex-test in Claude Code?

Run npx skills add convex/agent-skills --skill convex-test -a claude-code in your project terminal.

What does the convex-test skill do?

It prompts the assistant to produce deterministic in-memory tests for Convex functions. It handles args, returns, indexes, auth checks, and scheduled jobs.

Does convex-test require a running Convex deployment?

No, tests execute against an in-memory backend. You do not need network access or a live project.

Source text

SKILL.md · Apache-2.0

---
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

1. Install convex-test + vitest.
2. Write tests using convexTest(schema): seed via t.run, call t.query/t.mutation, assert.
3. Cover auth (withIdentity), error paths, and scheduled functions (t.finishInProgressScheduledFunctions).
4. 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).

Similar skills

Everything for Testing and QA →

api-test-suite-generator patricio0312rev Scans your route definitions and generates API test suites with Jest, Vitest or Supertest. Useful when the endpoints exist but the tests do not. CX Codex +1 303installs test-guard amElnagdy Reviews generated or edited test code against universal rules before commit or merge. It catches test bloat, over-mocking, and trivial tests in pytest, Jest, Vitest, Go, and PHPUnit suites. CX Codex +1 4,100installs test-coverage cognitedata A skill that finds coverage gaps in a Flows app and closes them: configures tooling, writes the missing tests, refactors code for testability. CX Codex +1 1,900installs unit-test-vue-pinia official github Writes and reviews unit tests for Vue 3, TypeScript, Vitest and Pinia code. Useful when your tests reach into component internals instead of behavior. 1,800installs test-migration kindlmann Migrates a test suite from Selenium, Cypress, Jest, Mocha or Protractor to Playwright and Vitest without quietly losing coverage. CX Codex +1 1,000installs parallel-test-fixing spencerpauly The skill runs your test suite and assigns each failing test file to a separate subagent for parallel fixes. It helps when multiple test files break simultaneously across a codebase. CX Codex +1 412installs

From the same set32

convex-backup Sets up Convex snapshot exports and runs a restore drill into a throwaway preview, so you find out whether recovery actually works. CX Codex +1 35,900installs convex-migrate-rehearse Runs a schema change and backfill on a snapshot-seeded preview deployment, then promotes the proven migration to prod. CX Codex +1 35,900installs convex-cost Analyzes Convex deployment spend, ranks functions driving read costs, and projects growth curves. Points out the cheapest code fix for each bottleneck. CX Codex +1 35,900installs convex-insights Queries logs and health for a running Convex deployment in natural language. Use it to investigate failures or check whether errors began after a deployment. CX Codex +1 35,900installs convex-agent Adds an AI agent backend to a Convex app: durable threads, message history, tool calls and vector search for RAG. CX Codex +1 35,900installs convex-sentinel Configures Sentinel error capture inside your own Convex deployment. Useful for tracking server failures and client React crashes without sending logs to third-party services. CX Codex +1 35,700installs convex-self-heal The skill takes a production error through triage, root cause and repair, certifies the fix on a preview, then opens a PR. A human merges. CX Codex +1 35,800installs convex-suggest The skill notices when you hand-roll something a ready Convex component already solves, and offers one match after your task is done. CX Codex +1 35,800installs