How to use the Convex Test Writer agent skill

What the convex-test skill makes the agent do

When the skill is installed, the agent follows a fixed workflow for testing a Convex app. It uses convex-test together with vitest to call your queries and mutations against an in-memory backend, so the tests do not touch a live deployment.

The skill's workflow has four steps: install convex-test and vitest, write tests using convexTest(schema) by seeding data with t.run and calling t.query or t.mutation, cover auth with withIdentity, error paths and scheduled functions via t.finishInProgressScheduledFunctions, then run vitest and keep the tests deterministic.

• Checks argument and return values of functions
• Covers auth paths using withIdentity
• Covers error paths, not only the happy path
• Tests indexes and scheduled functions
• Avoids real time and network access inside tests

Install the convex-test skill

The skill is a single file, SKILL.md. Download the ZIP from the item page on this site and unzip it into one of these locations: ~/.claude/skills/ for all your projects, or .claude/skills/ inside a specific project folder.

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before you start

The skill assumes you already have a Convex project with a schema. It also needs Node.js and npm, plus the convex-test and vitest packages. The skill's workflow includes installing those two packages, so you do not need to add them by hand first, but you do need Node.js and npm on your machine.

• Node.js and npm
• A Convex project with a schema
• convex-test and vitest packages (installed by the workflow)

Trigger the skill with a natural request

You do not need a special command. Describe the functions you want tested and mention Convex tests. The agent should pick up the skill when your request matches its description, which is to generate convex-test tests for the app's Convex functions.

Name the functions or the behaviour you care about. Asking for auth and error cases in the same request helps, because the skill's rules require them and not only the happy path.

• "Write convex-test tests for the messages mutations in convex/messages.ts."
• "Add vitest tests for my Convex queries, including the case where the user is not signed in."
• "Test the scheduled cleanup function in my Convex app with convex-test."

What a generated test looks like

Following the skill, the agent creates a test that builds the backend with convexTest(schema), seeds the data it needs with t.run, calls the function through t.query or t.mutation, and asserts the result. For authenticated paths it uses withIdentity to simulate a signed-in user.

The exact code depends on your schema and functions. The skill's source gives the pattern rather than a full example file, so review what the agent writes against your own code.

• Seed data with t.run before calling the function
• Simulate a user with withIdentity for auth tests
• Run scheduled work with t.finishInProgressScheduledFunctions

Run the tests and keep them deterministic

Run the tests with vitest. The skill asks for deterministic tests, meaning no real clock reads and no network calls, so the same test gives the same result each run.

If a test depends on time or an external service, ask the agent to stub or remove that dependency rather than letting the test reach the outside world.

• Run vitest after the tests are written
• Ask for changes if a test relies on real time or network calls