Tutorials / CI and the command line

Teach your AI coding agent Test Junkie

Left alone, an agent writes def test_x() functions that Test Junkie never finds. Two small files fix that: a snippet for your project's AGENTS.md with the rules that matter, and a skill with the full guide.

1. Add the snippet to AGENTS.md

AGENTS.md is the file most coding agents read at the start of a session. From the root of your project, append the snippet (this creates the file if you don't have one):

curl -fsSL https://www.test-junkie.com/static/agents/AGENTS-snippet.md >> AGENTS.md

It adds a short Test Junkie section that tells the agent:

• that a test is a method marked @test() on a class marked @Suite(), and a test fails by raising;
• to run tests with tj run -s <tests> and what the exit codes mean;
• to narrow a run by test name, tag or feature, and to never edit a test just to make a failing run pass;
• to load the test-junkie skill before writing or changing a test.

If your agent reads a different file (CLAUDE.md, for one), append the snippet there instead. Open the file and keep what is relevant: it is plain markdown, yours to edit.

2. Install the skill

The skill is the long form: how to write suites and tests, hooks, parameters, tags, retries, listeners, every tj flag that matters, and the mistakes agents make most. Agents that support skills load it only when the task needs it, so it costs nothing in other conversations. For Claude Code, save it in your project's skills folder:

mkdir -p .claude/skills/test-junkie
curl -fsSL https://www.test-junkie.com/static/agents/test-junkie/SKILL.md -o .claude/skills/test-junkie/SKILL.md

Use ~/.claude/skills/test-junkie/ instead to have it in every project on your machine. Commit the project copy, so the whole team's agents get it.

3. Ask for a test and run it

Start a new agent session in the project (agents read these files when a session starts) and ask for a test in plain words:

Write Test Junkie tests for the cart total in app/cart.py: a few prices, a discount, an empty cart and a negative price.

What you should see: a file under tests/ with a class marked @Suite(), methods marked @test() with assert statements, imports from test_junkie.decorators, and no def test_... functions. Then run them yourself, the way the agent should:

tj run -s tests
echo $?

Exit code 0 means every test that ran passed. 1 means a test failed, or nothing ran: if you see that for a file the agent just wrote, check for plain functions or a missing @Suite(. The snippet teaches the agent this, but it is the first thing to look at.

4. Keep them current

The skill was checked against Test Junkie 0.9a8, and says so. After you upgrade (tj version shows the version), run the same two download commands again to replace them. If something in a file disagrees with your version, the agent is told to trust tj run -h and the documentation.