@allen_minus/comments-tests

An AI agent that writes and maintains tests for your code. Annotate functions with @ai-test comments describing what to test, and the agent generates a full test suite.

// @ai-test: handle negative numbers and zero
// @ai-test: handle null inputs
function multiply(a, b) {
    return a * b;
}

Run ai-test generate and get a complete test file with cases for negatives, zero, nulls, and more — no boilerplate writing required.

Install

npm install -g @allen_minus/comments-tests

You'll need an Anthropic API key. Add it to a .env file in your project root:

ANTHROPIC_API_KEY=sk-ant-...

Usage

Generate tests

Scan your source files and generate tests for every @ai-test annotated function:

ai-test generate            # scan all configured source directories
ai-test generate src/math.js  # scan a specific file

Watch mode

Automatically regenerate tests when source files change:

ai-test watch

Help

ai-test help

Annotations

Add @ai-test comments directly above any function. Each comment becomes a directive — the agent will generate test cases for each one.

Free-form directives

Describe what you want tested in plain English:

// @ai-test: handle negative numbers and zero
// @ai-test: ensure the output is always uppercase
// @ai-test: throw an error when input is not a string
function greet(name) {
    return name.toUpperCase() + "!";
}

Structured directives

Use key:value syntax for more precise control:

// @ai-test: type:fuzz range:[-1000,1000] iterations:50
// @ai-test: type:invariant assert:result >= 0
// @ai-test: type:edge-case inputs:[null,undefined,NaN,Infinity,""]
// @ai-test: type:property assert:multiply(a,b) === multiply(b,a)
function multiply(a, b) {
    return a * b;
}

| Type | What it does | |------|-------------| | fuzz | Generates randomized input tests with edge cases | | invariant | Property-based assertions that must always hold | | edge-case | Boundary values, nulls, empty inputs, type coercion | | property | Mathematical/logical properties of the function |

You can mix free-form and structured directives on the same function.

Configuration

Create an ai-test.config.json in your project root to customize behavior:

{
  "sourceGlobs": ["./src"],
  "testDir": "./__tests__",
  "testFramework": "jest",
  "model": "claude-sonnet-4-20250514",
  "extensions": [".js", ".ts", ".jsx", ".tsx"]
}

| Option | Default | Description | |--------|---------|-------------| | sourceGlobs | ["./src"] | Directories to scan for source files | | testDir | ./__tests__ | Where generated tests are written | | testFramework | jest | Test framework (jest, vitest, or mocha) | | model | claude-sonnet-4-20250514 | Anthropic model to use | | extensions | [".js", ".ts", ".jsx", ".tsx"] | File extensions to scan | | envFile | .env | Path to your .env file |

Also supports .aitestrc and .aitestrc.json as config filenames.

How it works

1. Scan — Parses your source files using Babel, walks the AST, and finds functions with @ai-test comments
2. Cache — Hashes each function's code + directives. If nothing changed since last run, the function is skipped
3. Generate — Sends the function source and directives to Claude, which produces a test file
4. Write — Saves the test to __tests__/{filename}_{functionName}.test.js

The cache (.ai-test-cache.json) avoids unnecessary API calls. Only functions whose code or directives changed get regenerated.

Supported languages

JavaScript and TypeScript (including JSX/TSX). Both function declarations and arrow functions are supported:

// @ai-test: works on declarations
function add(a, b) { return a + b; }

// @ai-test: works on arrow functions too
const subtract = (a, b) => a - b;

License

MIT