Metadata-Version: 2.4
Name: altqa-cli
Version: 0.1.0
Summary: AI-powered QA automation CLI — tests your app from Jira tickets, reports bugs back automatically
Project-URL: Homepage, https://gitlab.com/rohithyphen05/altqa
Project-URL: Repository, https://gitlab.com/rohithyphen05/altqa
Project-URL: Issues, https://gitlab.com/rohithyphen05/altqa/-/issues
Author-email: Rohit Jangral <rohitnishantjangral@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,automation,cli,jira,playwright,qa,testing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: agno>=2.0
Requires-Dist: anthropic>=0.20
Requires-Dist: httpx>=0.25
Requires-Dist: jira>=3.5
Requires-Dist: openai>=1.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: playwright>=1.40
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Description-Content-Type: text/markdown

# AltQA

**AI-powered QA automation from your terminal.** AltQA 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 altqa        # or: uv pip install altqa
altqa init               # one-time setup (asks for keys, crawls your app)
altqa run JIRA-123       # test a ticket end-to-end
```

---

## How It Works

```
altqa 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 altqa

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

Then initialize in your project directory:

```bash
cd your-project/
altqa 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 `altqa run JIRA-123` — that's it.

---

## Commands

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