# AntiQA

**AI-powered QA automation from your terminal.** AntiQA reads Jira tickets, runs browser tests, detects bugs, and reports them back to Jira — like having an autonomous QA engineer on your team.

```
pip install antiqa        # or: uv pip install antiqa
antiqa init               # one-time setup (asks for keys, crawls your app)
antiqa run JIRA-123       # test a ticket end-to-end
```

---

## How It Works

```
antiqa run PROJ-42
```

1. Fetches the Jira ticket
2. Checks for attached test case files (Excel/CSV) — **these always take priority**
3. If no test cases attached, falls back to AI analysis of the ticket description
4. AI converts test cases into executable browser flows
5. Launches a real browser and runs every step
6. Monitors for console errors, API failures, JS exceptions, and memory leaks
7. Analyses failures with AI and generates detailed bug reports
8. Creates sub-task bug tickets on Jira with screenshots as proof
9. Cleans up screenshots from your project after upload

---

## Installation

**Requirements:** Python 3.11+

```bash
# With pip
pip install antiqa

# With uv (recommended)
uv pip install antiqa
```

Then initialize in your project directory:

```bash
cd your-project/
antiqa init
```

The wizard will:
1. Ask for your app URL (e.g. `http://localhost:3000`)
2. Ask for LLM provider & API key (OpenAI, Anthropic, or Ollama for local)
3. Ask for Jira credentials (base URL, project key, email, API token)
4. Ask for browser preference (Chromium, Firefox, or WebKit)
5. Install the Playwright browser binary automatically
6. Crawl your application and build a navigation graph
7. Auto-generate starter test flows from discovered pages

After init, you just run `antiqa run JIRA-123` — that's it.

---

## Commands

| Command | Description |
|---|---|
| `antiqa init` | Interactive setup wizard |
| `antiqa run JIRA-123` | Full pipeline: fetch ticket, test, report bugs |
| `antiqa run JIRA-123 --dry-run` | Show the test plan without executing |
| `antiqa run-local file.xlsx` | Run tests from local Excel/CSV files (no Jira) |
| `antiqa crawl` | Discover app routes and build navigation graph |
| `antiqa run-flow login` | Execute a specific YAML test flow |
| `antiqa flows list` | List all available flows |
| `antiqa generate-flows` | Auto-generate YAML flows from the navigation graph |
| `antiqa generate-flows --ai` | AI-powered flow generation (happy paths + edge cases) |
| `antiqa test "login and add a product"` | Generate and run a test from plain English |
| `antiqa chat` | Interactive AI QA session (REPL) |
| `antiqa audit` | AI accessibility audit (WCAG compliance) |
| `antiqa config show` | Display current configuration |

---

## AI-Powered Features

### Core Pipeline
- **Jira-aware testing** — reads ticket descriptions and attached test case files (Excel/CSV)
- **AI test interpretation** — converts human-written test steps into browser actions
- **AI failure analysis** — generates bug reports with root cause, fix suggestions, and regression tests
- **Automatic bug filing** — creates Jira sub-tasks with screenshots and detailed descriptions

### Runtime Health Monitoring
- Console errors and JS exceptions
- API failures and network errors
- Memory leaks and performance issues
- Page crashes and security warnings

### Advanced AI Features
- **Plain-text testing** — `antiqa test "login with wrong password and verify error"`
- **Visual AI review** — screenshot analysis for UI/layout bugs using vision models
- **AI flow generation** — generates comprehensive test flows from your app's navigation graph
- **Smart selector healing** — auto-fixes broken CSS selectors when elements change
- **Conversational QA** — `antiqa chat` for interactive testing sessions
- **AI test data generation** — realistic form data (valid, invalid, edge cases, security payloads)
- **Root cause clustering** — groups test failures by probable root cause
- **Accessibility audit** — WCAG compliance checking across your app
- **Enhanced bug descriptions** — AI-generated fix suggestions, user impact analysis, and regression tests
- **Natural language assertions** — write assertions in plain English in your YAML flows

---

## YAML Test Flows

Define reusable test flows:

```yaml
name: login
description: Log in with valid credentials
steps:
  - action: navigate
    url: "{{app_url}}/login"
  - action: fill
    selector: "#username"
    value: "{{username}}"
  - action: fill
    selector: "#password"
    value: "{{password}}"
  - action: click
    selector: "button[type=submit]"
  - action: wait_for
    selector: ".dashboard"
assertions:
  - type: url_contains
    value: "/dashboard"
```

Supports variable interpolation (`{{var}}`), flow includes, and natural language assertions.

---

## Architecture

```
CLI (Typer + Rich)
  |
  +-- Config (Pydantic schemas, antiqa.json)
  +-- AI Agents (Agno framework, multi-provider LLM)
  +-- Flow Engine (YAML parser, variable resolver, assertions)
  +-- Browser (Playwright — deterministic actions, not AI-controlled)
  +-- Crawler (BFS discovery, navigation graph)
  +-- Jira Integration (issue CRUD, attachments, comments)
  +-- Pipeline Orchestrator (ties everything together)
```

**Design principle:** Browser actions are deterministic (click, fill, navigate). AI handles *intelligence* — planning, analysis, and reporting. This avoids flaky, non-reproducible tests.

---

## Supported LLM Providers

| Provider | Models | Notes |
|---|---|---|
| OpenAI | gpt-4o, gpt-4o-mini, o1, etc. | Best overall experience |
| Anthropic | claude-sonnet-4-20250514, claude-3.5-haiku, etc. | Great for analysis |
| Ollama | llama3, mistral, codellama, etc. | Fully local, no API key |

---

## License

MIT
