altqa-cli 0.1.0

AI-powered QA automation CLI — tests your app from Jira tickets, reports bugs back automatically

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+

# With pip
pip install altqa

# With uv (recommended)
uv pip install altqa

Then initialize in your project directory:

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:

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