@ldanh270/aatest

Generate, validate, and repair Jest tests for JavaScript and TypeScript Node.js projects from the command line.

@ldanh270/aatest provides the aatest CLI. The CLI reads a source file with Babel AST analysis, sends structured context to an OpenAI-compatible Chat Completions endpoint, writes the generated test, and validates it in the target project. When healing is enabled, each failure is diagnosed before the model rewrites the test.

Highlights

• JavaScript and TypeScript source analysis
• Export, import, class-method, and Express-route context extraction
• OpenAI-compatible providers, including local 9Router instances
• Safe replacement with timestamped backups
• Lint-first validation followed by isolated Jest execution
• Root-cause analysis before every repair
• Early exit as soon as validation passes
• npm, pnpm, Yarn, and Bun project detection

Requirements

• Node.js 18 or newer
• A target Node.js package containing package.json
• An OpenAI-compatible Chat Completions endpoint, API key, and model ID
• Jest-compatible source code; Express/Supertest projects are the primary use case

Security first

aatest sends source code and failure diagnostics to the provider configured in your environment. It also executes generated code with Jest inside your target project. Review provider privacy terms, use a restricted test environment, and never commit API keys. See Security before using the CLI on sensitive code.

Quick start

Run these commands from the package that owns the source file:

cd path/to/your-node-project
npm install --save-dev @ldanh270/aatest
npx aatest init

Generate a test:

npx aatest unit src/controllers/user.controller.ts

Generate and automatically repair failures, up to ten repair attempts:

npx aatest unit src/controllers/user.controller.ts --auto-heal --retries 10

Preview the prompt and model response without writing the generated test:

npx aatest unit src/controllers/user.controller.ts --dry-run --verbose

--dry-run prevents test-file writes and validation, but environment and dependency checks happen first. Confirm prompts carefully because setup may install test dependencies or update project test configuration.

Use with 9Router

9Router exposes a local OpenAI-compatible endpoint that can route requests across connected providers.

npm install --global 9router
9router

In the dashboard at http://localhost:20128:

1. Open Providers and connect a provider.
2. Copy the API key displayed by 9Router.
3. Copy a model ID from the dashboard, for example kr/claude-sonnet-4.5 when available. Then return to the Node.js project where @ldanh270/aatest is installed and run the interactive initializer:

npx aatest init

Enter http://localhost:20128/v1 as the base URL, then paste the API key and model ID copied from the dashboard. Choose the generated-test directory and maximum repair attempts when prompted. The initializer writes the corresponding AATEST_* settings for you.

For CI or other non-interactive environments, see the manual environment configuration in Provider setup.

Keep 9Router running while aatest generates or repairs tests. See Provider setup for the complete walkthrough and generic OpenAI-compatible configuration.

Configuration

aatest init writes configuration to .env in the directory where it is run. If .env already exists and you choose not to append, it writes .env.aatest instead.

| Variable | Required | Default | Purpose | |---|---:|---|---| | AATEST_API_KEY | Yes | — | Provider or proxy API key | | AATEST_BASE_URL | No | https://api.openai.com/v1 | OpenAI-compatible API root | | AATEST_MODEL | Yes | — | Provider-specific model ID | | AATEST_SOURCE_DIR | Yes* | — | Generated-test output directory | | AATEST_MAX_RETRIES | No | 10 | Maximum repair attempts |

* --source can supply the output directory for one invocation.

Older TEST_GEN_* variables are read only for backward compatibility.

Precedence is CLI option, canonical AATEST_* variable, legacy TEST_GEN_* variable, then built-in default. .env is loaded first; .env.aatest fills only values that are still missing. See Configuration.

CLI

aatest init
aatest unit <file> [options]

| Option | Description | |---|---| | -s, --source <dir> | Override the generated-test directory | | -H, --auto-heal | Repair failures without asking for confirmation | | -r, --retries <n> | Set a positive maximum number of repair attempts | | --dry-run | Print prompts and model output without writing the test | | -v, --verbose | Print token usage and stack traces |

--auto-heal does not enable validation—validation always runs after a test is written. It only skips the repair confirmation prompt after a failure. See the CLI reference.

Output and backups

With this configuration:

AATEST_SOURCE_DIR=./src/__tests__

this source file:

src/controllers/user.controller.ts

produces:

src/__tests__/controllers/user.controller.spec.ts

If the test already exists, it is copied to a timestamped .bak file before being replaced. Failed healing logs are written under <sourceDir>/.aatest-errors/.

Validation and self-healing

After generation, aatest:

1. Runs the first available static check: local ESLint, local Biome, the package lint script, or the package typecheck script.
2. Ignores project-wide static failures only when they do not reference the generated test.
3. Runs the generated file with Jest in-band and a 60-second timeout.
4. Stops immediately when validation passes.
5. On failure, asks the model for a root-cause analysis and then a complete corrected test file.

Each failed repair attempt can make two model calls: one diagnosis and one rewrite. See Self-healing for limits and failure modes.

Documentation

• Getting started
• Provider setup
• Configuration
• CLI reference
• Self-healing
• Troubleshooting
• Local development
• Architecture
• Documentation index

Contributing

See CONTRIBUTING.md for the development workflow and coding standards. Bug reports and focused pull requests are welcome.

License

Licensed under the Apache License 2.0.