# 🚀 TestGen AI

> **The Autonomous QA Agent from Your CLI**

[![PyPI version](https://img.shields.io/pypi/v/testgen-ai.svg)](https://pypi.org/project/testgen-ai/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Docs](https://img.shields.io/badge/docs-live-brightgreen.svg)](https://JayPatil165.github.io/TestGen-AI/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

TestGen AI is a CLI tool that automatically generates, runs, and reports on test suites for your code using LLMs. Point it at a directory, set an API key, and let it handle the rest.

---

## 📦 Installation

```bash
pip install testgen-ai
```

Verify:

```bash
testgen --version
```

---

## ⚡ Quick Start

### 1. Set your API key (one-time)

```bash
# Google Gemini (default — has a free tier)
testgen config set GEMINI_API_KEY AIza...

# OpenAI
testgen config set OPENAI_API_KEY sk-...

# Anthropic / Claude
testgen config set ANTHROPIC_API_KEY sk-ant-...

# Ollama (local, no key needed)
testgen config set LLM_PROVIDER ollama
```

Keys are saved globally to `~/.testgen/.env` and apply to every project automatically.

### 2. Generate tests

```bash
testgen generate ./src
```

### 3. Run tests

```bash
testgen test
```

### 4. Generate a report

```bash
testgen report
```

### 5. Or do everything in one shot

```bash
testgen auto ./src
```

---

## ✨ Features

- 🤖 **AI-Powered Generation** — Uses GPT-4, Claude, Gemini, or local Ollama to write real test cases, not boilerplate
- 🌍 **14 Languages** — Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, C++, HTML, CSS
- 👀 **Watch Mode** — Detects file saves and regenerates tests in real time (`--watch`)
- 📊 **Terminal Dashboard** — Color-coded test matrix with pass/fail/skip/duration per test
- 📈 **HTML Reports** — Professional reports with metrics, coverage insights, and execution distributions
- ⚡ **Smart Context** — AST-based extraction sends only relevant code to the LLM, keeping token costs low
- 🔄 **One-command Workflow** — `testgen auto` runs the full generate → execute → report pipeline

---

## 🎯 The AGER Architecture

TestGen AI operates on a 4-step loop:

```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Analyze  │────▶│ Generate │────▶│ Execute  │────▶│ Report   │
│ (Scanner)│     │ (Brain)  │     │ (Runner) │     │ (Visuals)│
└──────────┘     └──────────┘     └──────────┘     └──────────┘
```

| Phase | What happens |
|-------|-------------|
| **Analyze** | Scans your directory, extracts function signatures and docstrings to build minimal context |
| **Generate** | Sends context to your LLM and receives executable test code |
| **Execute** | Runs the generated tests via the appropriate framework (pytest, Jest, cargo test, etc.) |
| **Report** | Renders a live terminal matrix and compiles an HTML report |

---

## 🎨 CLI Commands

| Command | What it does |
|---------|-------------|
| `testgen generate <path>` | Generate tests for all source files in `<path>` |
| `testgen generate <path> --watch` | Watch mode — regenerate on every save |
| `testgen test` | Run all generated tests |
| `testgen test --verbose` | Run with full output |
| `testgen report` | Build an HTML test report |
| `testgen auto <path>` | Full pipeline: generate → test → report |
| `testgen config set KEY VALUE` | Save a config value globally |
| `testgen config show` | Print current global config |

---

## 📊 Terminal Output

```
╔══════════════════════════════════════════════════════════════════╗
║                    TEST EXECUTION MATRIX                         ║
╠═══════════════════════════════╦══════════╦══════════╦════════════╣
║ Test Name                     ║ Status   ║ Duration ║ Details    ║
╠═══════════════════════════════╬══════════╬══════════╬════════════╣
║ test_user_login               ║ ✔ PASS   ║ 0.24s    ║            ║
║ test_user_registration        ║ ✔ PASS   ║ 0.31s    ║            ║
║ test_password_validation      ║ ✘ FAIL   ║ 0.12s    ║ AssertionE…║
║ test_database_connection      ║ ✔ PASS   ║ 5.01s    ║ [SLOW]     ║
║ test_api_endpoint_users       ║ ✔ PASS   ║ 0.89s    ║            ║
╚═══════════════════════════════╩══════════╩══════════╩════════════╝

Summary: 4 passed, 1 failed, 0 skipped | Total: 6.57s
```

---

## 🌍 Supported Languages

| Language | Test Framework Used |
|----------|-------------------|
| Python | pytest |
| JavaScript | Jest |
| TypeScript | Jest |
| Go | go test |
| Rust | cargo test |
| Java | JUnit |
| C# | NUnit / xUnit |
| Ruby | RSpec |
| PHP | PHPUnit |
| Swift | XCTest |
| Kotlin | JUnit |
| C++ | Google Test |
| HTML | Custom HTML validator |
| CSS | Custom CSS linter |

> The target language's runtime (Node, Go, JDK, etc.) must be installed on your machine. `pip install testgen-ai` only installs the TestGen AI tool itself.

---

## ⚙️ Configuration

Config can be set globally (persists across all projects):

```bash
testgen config set GEMINI_API_KEY AIza...
testgen config set LLM_MODEL gemini-2.0-flash
testgen config set LLM_PROVIDER gemini
```

Or per-project via a `.env` file in the project root (overrides global):

```env
OPENAI_API_KEY=sk-project-key
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
TEST_OUTPUT_DIR=./tests
MAX_CONTEXT_TOKENS=8000
```

### Supported Providers

| Provider | Key name | Default model |
|----------|---------|---------------|
| Google Gemini | `GEMINI_API_KEY` | `gemini-2.0-flash` |
| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
| Anthropic | `ANTHROPIC_API_KEY` | `claude-3-5-sonnet` |
| Ollama (local) | *(none)* | `llama3` |

---

## 🔧 Optional: Browser / UI Testing

For Playwright-based UI test generation:

```bash
pip install testgen-ai[browser]
playwright install
```

The `playwright install` step downloads browser binaries and is a one-time setup per machine.

---

## 🛠️ Technology Stack

| Component | Technology |
|-----------|-----------|
| Language | Python 3.10+ |
| CLI Framework | Typer |
| Terminal UI | Rich |
| AI Layer | LiteLLM (model-agnostic) |
| Validation | Pydantic |
| File Watching | Watchdog |
| Testing Core | pytest |
| UI Testing | Playwright (optional) |
| Reporting | Jinja2 |

---

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make your changes
4. Run tests: `pytest`
5. Commit: `git commit -m "Add my feature"`
6. Push: `git push origin feature/my-feature`
7. Open a Pull Request

---

## 📚 Documentation

Full documentation: **[JayPatil165.github.io/TestGen-AI](https://JayPatil165.github.io/TestGen-AI/)**

---

## 📧 Contact

- **Author**: Jay Ajitkumar Patil
- **Email**: [patiljay32145@gmail.com](mailto:patiljay32145@gmail.com)
- **GitHub**: [@JayPatil165](https://github.com/JayPatil165)
- **LinkedIn**: [jay-patil-4ab857326](https://www.linkedin.com/in/jay-patil-4ab857326/)
- **Issues**: [GitHub Issues](https://github.com/JayPatil165/TestGen-AI/issues)

---

<p align="center">
  <strong>⭐ Star this repo if TestGen AI saves you time! ⭐</strong><br>
  Made with ❤️ by developers, for developers
</p>
