@your-username/polyglot-ai-testgen

A multi-language AI test generation CLI. Install it into any existing repository, let it scan your source code, and have an LLM write unit tests for every supported file.

Milestone 1 (this release) — scanner, language detector, and blueprint generator.
Milestone 2 — LLM test generation with verification loop and retry logic.

Supported languages

| Language | Extensions | |------------|--------------------| | TypeScript | .ts, .tsx | | JavaScript | .js, .jsx | | Python | .py | | Go | .go | | Rust | .rs | | C# | .cs | | Java | .java |

Installation

Global install

npm install -g @your-username/polyglot-ai-testgen
ai-testgen --help

Per-project (npx, no install needed)

npx @your-username/polyglot-ai-testgen --scan-only

Quick start

# 1. Navigate to the root of the repository you want to test
cd /path/to/your/project

# 2. Create a config file (optional but recommended)
npx ai-testgen --init

# 3. Scan the codebase and generate the blueprint
npx ai-testgen --scan-only

# 4. (Milestone 2) Generate tests — requires an LLM API key
AI_TESTGEN_API_KEY=sk-... npx ai-testgen --generate

CLI flags

| Flag | Description | |------|-------------| | --init | Write a default ai-testgen.config.json to the current directory | | --scan-only | Scan source files and produce tests_generated/codebase-blueprint.json | | --generate | Generate tests with the configured LLM (Milestone 2) | | --run-tests | Run generated tests after generation (Milestone 2) | | --max-files <n> | Process at most n source files | | --target <path> | Restrict scanning to a subdirectory (e.g. src/services) | | --dry-run | Show what would be done without writing any files |

Example commands

npx ai-testgen --init
npx ai-testgen --scan-only
npx ai-testgen --scan-only --target src/services
npx ai-testgen --scan-only --max-files 50 --dry-run
npx ai-testgen --generate
npx ai-testgen --generate --run-tests

Configuration

Running ai-testgen --init creates ai-testgen.config.json with these defaults:

{
  "projectRoot": "./",
  "outputDir": "tests_generated",
  "targetCoverage": 90,
  "maxRetries": 3,
  "model": "openai/gpt-4o-mini",
  "baseUrl": "https://openrouter.ai/api/v1",
  "ignore": [
    "node_modules", ".git", "dist", "build",
    "coverage", ".next", "vendor", "tests_generated"
  ],
  "testCommands": {
    "typescript": "npm test",
    "javascript": "npm test",
    "python": "pytest",
    "go": "go test ./...",
    "csharp": "dotnet test",
    "java": "mvn test",
    "rust": "cargo test"
  }
}

Config reference

| Key | Type | Description | |-----|------|-------------| | projectRoot | string | Root path to scan (relative to cwd) | | outputDir | string | Where generated tests and reports are written | | targetCoverage | number | Desired coverage % (informational) | | maxRetries | number | Max LLM regeneration retries per file | | model | string | LLM model identifier | | baseUrl | string | LLM API base URL | | ignore | string[] | Folder names to skip during scanning | | testCommands | Record<string,string> | Shell commands to run tests per language |

Environment variables

Set these before running --generate (never put them in config files):

export AI_TESTGEN_API_KEY="sk-..."          # required for generation
export AI_TESTGEN_BASE_URL="https://..."    # optional — overrides config
export AI_TESTGEN_MODEL="gpt-4o"           # optional — overrides config

API keys are never written to any file or printed in logs.

Output files

All output is confined to tests_generated/ (or your configured outputDir).

tests_generated/
├── codebase-blueprint.json   ← parsed structure of every source file
├── report.json               ← scan summary and (Milestone 2) test results
├── typescript/
│   └── myService.test.ts     ← generated test (Milestone 2)
├── python/
│   └── test_utils.py
└── go/
    └── handler_test.go

The tool never:

• modifies production source files
• deletes any file
• commits or pushes to version control
• exposes API keys in logs
• processes .env files

Safety

Add tests_generated/ to your .gitignore until you have reviewed the generated tests:

tests_generated/

Development

git clone https://github.com/your-username/polyglot-ai-testgen
cd polyglot-ai-testgen
npm install
npm run build    # compile TypeScript → dist/
npm run lint     # ESLint
npm test         # Jest
npm run dev      # ts-node (no build step)

Project structure

bin/
  cli.js            ← shebang entry point
src/
  types.ts          ← shared TypeScript interfaces
  config.ts         ← config loader and --init helper
  scanner.ts        ← recursive file system scanner + framework detector
  parser.ts         ← regex-based multi-language AST extractor
  generator.ts      ← blueprint serialiser + test file naming (M1)
  report.ts         ← report builder
  test-runner.ts    ← test execution stub (Milestone 2)
  index.ts          ← Commander CLI entry point

Publishing to npm

1. Choose a name — update name in package.json:

   "name": "@your-username/polyglot-ai-testgen"

2. Build:

   npm run build

3. Login:

   npm login

4. Publish (scoped packages require --access public):

   npm publish --access public

5. Update:

   npm version patch   # or minor / major
   npm publish --access public

License

MIT