🧪 TestGenie AI

AI-powered CLI test generator that creates comprehensive test suites for your JavaScript/TypeScript projects in seconds.

Generate high-quality, maintainable test files using advanced AI models. TestGenie analyzes your code structure, detects patterns, and creates thorough test coverage automatically.

📚 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📋 Commands
• 🧪 Test Framework
• 🎨 Test Styles
• 🤖 AI Providers
• ⚙️ Configuration
• 🔧 Requirements
• 🎯 Examples
• ❓ FAQ
• 🤝 Contributing
• 📄 License
• 🙋‍♂️ Support

✨ Features

🤖 AI-Powered Intelligence

• Smart Code Analysis: Automatically detects functions, patterns, and dependencies
• Multi-Provider Support: OpenAI, Google Gemini, Anthropic Claude, or TestGenie API
• Comprehensive Test Generation: Creates thorough test suites with edge cases
• Advanced Async Analysis: Understands Promise flows, timing, and error handling
• React Component Intelligence: Detects JSX/TSX and generates proper React tests
• Behavioral Understanding: Analyzes component validation, form logic, and user flows

⚡ Developer Experience

• Lightning Fast: Generate complete test suites in seconds
• Multiple Test Styles: BDD, TDD, minimal, and verbose options
• Framework Support: Jest (Mocha and Vitest coming soon!)
• Git Integration: Generate tests for changed files or specific commits
• Automatic Setup: Auto-installs dependencies and creates Jest configuration
• React/JSX Support: Full React Testing Library integration with automatic detection

📊 Project Management

• Test Coverage Analysis: Scans projects and identifies untested code
• Flexible Configuration: Customize test directories, patterns, and coverage thresholds
• Audit & Recommendations: Comprehensive coverage reports with actionable insights
• Test Execution: Built-in test runner with multiple reporters and coverage options

🚀 Quick Start

Installation

npm install -g testgenie-ai
# or
yarn global add testgenie-ai
# or
pnpm add -g testgenie-ai
# or
bun add -g testgenie-ai

Initialize Configuration

testgenie init

This interactive setup will configure:

• Test Framework: Jest (currently supported)
• Test Style: BDD, TDD, minimal, or verbose
• AI Provider: Choose from multiple providers
• Test Directory: Where to generate test files
• Coverage Settings: Minimum coverage thresholds

Generate Tests

# Generate tests for a specific file
testgenie gen src/utils/helper.ts

# Generate tests for git changes
testgenie gen --diff

# Generate tests for changes since specific commit
testgenie gen --since HEAD~3

Run Tests

# Run all tests with automatic setup
testgenie test

# Run tests with coverage report
testgenie test --coverage

# Watch mode for development
testgenie test --watch

Help & Commands

testgenie --help

Get comprehensive help for all available commands and options.

Complete Workflow

# 1. Initialize project
testgenie init

# 2. Scan for files needing tests
testgenie scan

# 3. Generate tests for specific files
testgenie gen src/components/Button.tsx

# 4. Auto-generate tests for uncovered files
testgenie audit --fix

# 5. Run tests with automatic setup
testgenie test --coverage

# 6. Continuous development with watch mode
testgenie test --watch

📋 Commands

testgenie init

Initialize or update configuration file.

Options:

• --force, -f: Overwrite existing configuration

Example:

testgenie init --force

testgenie gen [file]

Generate comprehensive test files.

Arguments:

• file: Specific file to generate tests for

Options:

• --diff, -d: Generate tests for uncommitted git changes
• --since, -s <commit>: Generate tests for changes since commit
• --style <style>: Override test style (bdd, tdd, minimal, verbose)
• --output, -o <dir>: Override output directory

Examples:

# Generate tests for specific file
testgenie gen src/components/Button.tsx

# Generate tests for all changed files
testgenie gen --diff

# Generate tests since last commit
testgenie gen --since HEAD~1

# Use specific style
testgenie gen src/utils/math.js --style minimal

testgenie scan [path]

Analyze project for test coverage and discover files.

Arguments:

• path: Directory to scan (default: current directory)

Options:

• --output, -o <file>: Save results to file
• --format, -f <format>: Output format (json, csv, text)

Examples:

# Scan current directory
testgenie scan

# Scan specific directory with JSON output
testgenie scan src --format json --output coverage-report.json

# Quick scan of components
testgenie scan src/components

testgenie audit [path]

Comprehensive test coverage audit with recommendations.

Arguments:

• path: Directory to audit (default: current directory)

Options:

• --fix: Auto-generate tests for uncovered files
• --format, -f <format>: Report format (text, json, html)
• --deep: Enable deep analysis (file modification times, dependencies)

Examples:

# Basic audit
testgenie audit

# Auto-fix missing tests
testgenie audit --fix

# Deep analysis with JSON report
testgenie audit --deep --format json

testgenie test [pattern]

Execute tests in the configured test directory with automatic setup.

Arguments:

• pattern: Test file pattern to run (optional)

Options:

• --watch, -w: Watch mode for continuous testing
• --coverage, -c: Generate coverage reports
• --reporter, -r <format>: Test reporter format (default, json, verbose, minimal)
• --filter, -f <pattern>: Filter tests by name pattern
• --parallel, -p: Run tests in parallel (default: true)
• --bail, -b: Stop on first test failure
• --silent, -s: Suppress test output (show only results)
• --timeout, -t <ms>: Test timeout in milliseconds (default: 30000)

Examples:

# Run all tests with automatic setup
testgenie test

# Run tests with coverage
testgenie test --coverage

# Run specific test pattern
testgenie test --filter="Calculator"

# Watch mode with verbose output
testgenie test --watch --reporter=verbose

# Run tests in a specific directory
testgenie test src/components

# Minimal output for CI/CD
testgenie test --silent --reporter=minimal

Features:

• Automatic Setup: Detects and installs missing Jest dependencies
• Smart Configuration: Creates optimized Jest config for your project type
• React Support: Automatically detects and configures React Testing Library
• Multiple Reporters: Choose from default, JSON, verbose, or minimal output
• Pattern Matching: Run specific tests or test suites

testgenie config

Display current configuration.

Example:

testgenie config

🧪 Test Framework

Jest (Currently Supported)

TestGenie provides full Jest integration with automatic setup:

Test Generation:

• Modern ES6+ syntax and imports
• Comprehensive mocking strategies
• Async/await support
• TypeScript compatibility
• React Testing Library integration

Automatic Setup:

• Detects and installs missing Jest dependencies
• Creates optimized Jest configuration
• Configures TypeScript support when needed
• Sets up React Testing Library for JSX/TSX files
• Configures jsdom environment for React components

Test Execution:

• Built-in test runner with testgenie test
• Multiple output reporters (default, JSON, verbose, minimal)
• Coverage reporting and analysis
• Watch mode for continuous testing
• Pattern-based test filtering

Coming Soon:

• Mocha: Traditional Node.js testing framework
• Vitest: Fast Vite-native testing framework

🎨 Test Styles

Choose from multiple test generation styles:

BDD (Behavior Driven Development)

describe("Calculator", () => {
  describe("when adding numbers", () => {
    it("should return correct sum for positive numbers", () => {
      // test implementation
    });
  });
});

TDD (Test Driven Development)

suite("Calculator", () => {
  test("adds positive numbers correctly", () => {
    // test implementation
  });
});

Minimal

test("Calculator.add()", () => {
  // concise test implementation
});

Verbose

describe("Calculator utility class", () => {
  it("should correctly calculate the sum of two positive integers and return the expected result", () => {
    // detailed test implementation with extensive comments
  });
});

🤖 AI Providers

TestGenie API (Recommended)

• No API key required
• Optimized for test generation
• Best performance and quality

# Set during init or manually
testgenie init
# Select "TestGenie API"

OpenAI (GPT Models)

• Models: GPT-4o, GPT-4o-mini, GPT-4-turbo
• Setup: Set OPENAI_API_KEY environment variable

export OPENAI_API_KEY="your-api-key"

Google Gemini

• Models: Gemini-1.5-Pro, Gemini-1.5-Flash
• Setup: Set GOOGLE_GENERATIVE_AI_API_KEY environment variable

export GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"

Anthropic Claude

• Models: Claude-3.5-Sonnet, Claude-3-Haiku
• Setup: Set ANTHROPIC_API_KEY environment variable

export ANTHROPIC_API_KEY="your-api-key"

⚙️ Configuration

TestGenie uses testgenie.config.js in your project root:

export default {
  // Test framework (Jest only for now)
  framework: "jest",

  // Test generation style
  style: "bdd", // "bdd" | "tdd" | "minimal" | "verbose"

  // Test directory
  testDir: "__tests__",

  // AI provider configuration
  ai: {
    provider: "testgenie-api", // "testgenie-api" | "openai" | "gemini" | "claude"
    model: "auto", // or specific model name
  },

  // File patterns to include
  include: ["src/**/*.{js,ts,jsx,tsx}", "lib/**/*.{js,ts,jsx,tsx}"],

  // File patterns to exclude
  exclude: [
    "**/*.test.{js,ts,jsx,tsx}",
    "**/*.spec.{js,ts,jsx,tsx}",
    "**/node_modules/**",
  ],

  // Coverage settings
  coverage: {
    threshold: 80, // minimum coverage percentage
    includeUntested: true,
  },

  // Git integration
  git: {
    autoCommit: false,
    commitMessage: "test: add generated tests",
  },

  // Output preferences
  output: {
    emojis: true,
    verbose: false,
  },
};

🔧 Requirements

System Requirements

| Requirement | Version | Notes | | ------------------- | ----------------------- | ----------------------------------- | | Node.js | 16+ | LTS recommended | | Package Manager | npm, yarn, pnpm, or bun | Any modern package manager | | Git | Any | Optional, for diff-based generation | | Test Framework | Jest | Mocha/Vitest coming soon |

Required Dependencies

TestGenie automatically detects and installs missing dependencies when you run testgenie test:

For JavaScript projects:

• jest, @jest/globals
• @testing-library/react, @testing-library/jest-dom (for React)
• jest-environment-jsdom (for React components)

For TypeScript projects:

• @types/jest, ts-jest (additional to above)

Manual installation (optional):

# JavaScript
npm install --save-dev jest @jest/globals

# TypeScript
npm install --save-dev jest @jest/globals @types/jest ts-jest

# React projects (auto-detected and installed)
npm install --save-dev @testing-library/react @testing-library/jest-dom jest-environment-jsdom

🎯 Examples

Basic Function Testing

// src/utils/math.js
export function add(a, b) {
  return a + b;
}

export function multiply(a, b) {
  return a * b;
}

Generated test:

// __tests__/src/utils/math.test.js
import { describe, it, expect } from "@jest/globals";
import { add, multiply } from "../../../src/utils/math.js";

describe("add", () => {
  it("should return correct sum for positive numbers", () => {
    expect(add(2, 3)).toBe(5);
  });

  it("should handle negative numbers", () => {
    expect(add(-1, 1)).toBe(0);
  });

  it("should handle zero values", () => {
    expect(add(0, 5)).toBe(5);
  });
});

describe("multiply", () => {
  it("should return correct product", () => {
    expect(multiply(3, 4)).toBe(12);
  });

  it("should handle zero multiplication", () => {
    expect(multiply(5, 0)).toBe(0);
  });
});

Async Function Testing

// Generated test for async functions
describe("fetchUserData", () => {
  it("should fetch user data successfully", async () => {
    const mockUser = { id: 1, name: "John" };
    global.fetch = jest.fn().mockResolvedValue({
      ok: true,
      json: jest.fn().mockResolvedValue(mockUser),
    });

    const result = await fetchUserData(1);
    expect(result).toEqual(mockUser);
    expect(fetch).toHaveBeenCalledWith("/api/users/1");
  });
});

React Component Testing

TestGenie automatically detects React components and generates comprehensive tests:

# Generate tests for React component
testgenie gen src/components/UserForm.tsx

# Run React tests with automatic setup
testgenie test --coverage

Generated React test with automatic imports and setup:

import { describe, it, expect, jest, beforeEach } from "@jest/globals";
import React from "react";
import { render, fireEvent, screen } from "@testing-library/react";
import { UserForm } from "../../../src/components/UserForm";

beforeEach(() => {
  jest.clearAllMocks();
  window.alert = jest.fn();
});

describe("UserForm", () => {
  it("should submit form with valid data", () => {
    const onSubmit = jest.fn();
    render(<UserForm onSubmit={onSubmit} />);

    fireEvent.change(screen.getByLabelText("Name:"), {
      target: { value: "John Doe" },
    });
    fireEvent.change(screen.getByLabelText("Email:"), {
      target: { value: "[email protected]" },
    });
    fireEvent.submit(screen.getByRole("button", { name: /Submit/i }));

    expect(onSubmit).toHaveBeenCalledWith({
      name: "John Doe",
      email: "[email protected]",
      age: "",
    });
  });
});

❓ FAQ

Why are my tests not being generated?

Check that the file path is correct and that it's not excluded in exclude patterns in your config. Common issues include:

• File not found: Verify the file path exists and is accessible
• Excluded patterns: Check your testgenie.config.js exclude patterns
• Unsupported file type: Ensure the file has a supported extension (.js, .ts, .jsx, .tsx)
• AI provider issues: Verify your API keys are set correctly for external providers

How do I run tests after generating them?

TestGenie includes a built-in test runner with automatic setup:

# Basic test execution
testgenie test

# With coverage reports
testgenie test --coverage

# Watch mode for development
testgenie test --watch --reporter=verbose

The test command automatically:

• Detects and installs missing Jest dependencies
• Creates optimized Jest configuration
• Sets up React Testing Library for React projects
• Configures TypeScript support when needed

Can I use it with Mocha or Vitest?

Mocha and Vitest support is coming soon! Currently, only Jest is supported. We're actively working on expanding framework support:

• Jest: ✅ Full support
• Mocha: 🚧 Coming soon
• Vitest: 🚧 Coming soon

How do I set up different AI providers?

Each provider requires different setup:

TestGenie API (Recommended):

• No setup required
• Best performance for test generation

OpenAI:

export OPENAI_API_KEY="your-api-key"

Google Gemini:

export GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"

Anthropic Claude:

export ANTHROPIC_API_KEY="your-api-key"

What file types are supported?

TestGenie supports:

• JavaScript: .js, .jsx
• TypeScript: .ts, .tsx
• React Components: Both JS and TS
• Node.js modules: CommonJS and ES modules

How can I customize test output?

You can customize tests through your testgenie.config.js:

export default {
  style: "bdd", // or "tdd", "minimal", "verbose"
  testDir: "__tests__", // custom test directory
  output: {
    emojis: true, // enable/disable emojis
    verbose: false, // detailed output
  },
};

Can I generate tests for existing test files?

TestGenie automatically excludes existing test files (.test.js, .spec.js, etc.) to avoid conflicts. If you want to regenerate tests, either:

1. Delete the existing test file first
2. Use a different output directory with --output

How do I handle TypeScript configurations?

TestGenie automatically detects TypeScript projects and generates appropriate tests. Ensure you have:

npm install --save-dev @types/jest ts-jest

Your jest.config.js should include:

export default {
  preset: "ts-jest",
  testEnvironment: "node",
};

What's the difference between test styles?

• BDD: Descriptive, nested describe/it blocks
• TDD: Traditional test/suite structure
• Minimal: Concise, straightforward tests
• Verbose: Detailed with extensive comments

How accurate are the generated tests?

TestGenie uses advanced AI models specifically trained for test generation with enhanced behavioral analysis. The AI provides production-ready tests by:

Code Analysis:

• Analyzes your code structure, dependencies, and logic flow
• Understands React component validation and form behavior
• Traces async function execution and Promise handling
• Detects DOM interactions and browser API usage

Test Quality:

• Generates realistic test scenarios that match actual code behavior
• Includes comprehensive edge cases and error handling
• Follows testing best practices and framework conventions
• Creates proper mocks for FormData, console methods, and DOM elements

React & Async Expertise:

• Automatically imports React and React Testing Library for JSX components
• Handles form validation logic and user interaction flows
• Properly mocks browser APIs (window.alert, console.error)
• Understands Promise timing and rejection conditions

While tests are comprehensive and thoroughly analyzed, always review them before committing to ensure they meet your specific requirements.

Can I contribute or request features?

Absolutely! We welcome contributions and feature requests:

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 🤝 Contributions: See our Contributing section below

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🙋‍♂️ Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Happy Testing! 🧪✨