Automa

BDD-first web application test automation framework powered by LLM intelligence.

Overview

Automa transforms Gherkin feature files into fully executable browser tests with smart element resolution, self-healing selectors, and LLM-powered edge case suggestions. Write your tests in plain English — Automa handles the rest.

Features

• BDD-First Workflow — Write Gherkin scenarios, Automa generates page objects and step definitions
• Smart Element Resolution — 3-level resolution chain: registry lookup → DOM heuristics → LLM inference
• Self-Healing Tests — Automatically detects and repairs broken selectors during execution
• LLM Integration — Supports Claude, OpenAI, and Gemini for edge case suggestions and element inference
• 20 CLI Commands — Full lifecycle from automa init to automa report
• 13-Step Orchestrator — automa auto runs the complete pipeline with checkpoints and resume
• Cost Tracking — Per-run LLM cost ceiling enforcement
• Parallel Execution — Multi-worker test execution with configurable parallelism
• Allure Reporting — Rich HTML reports with screenshots and evidence

Quick Start

# Initialize a new project
npx automa init

# Check prerequisites
npx automa doctor

# Run the full pipeline
npx automa auto https://your-app.com

CLI Commands

| Phase | Commands | |-------|----------| | Setup | init, config, doctor | | Discovery | login, scan, discover, mappings, validate | | Generation | suggest, generate, steps, sync | | Execution | run, report, status, resume | | Maintenance | clean, ci-setup, migrate | | Orchestrator | auto |

Architecture

src/
├── browser/        # Browser adapter (Playwright)
├── cli/            # Commander CLI + TUI components
├── config/         # YAML config loader + Zod validation
├── core/
│   ├── checkpoint/ # Substep progress tracking
│   ├── discovery/  # Page scanning + link crawling
│   ├── executor/   # Test runner with self-healing + retries
│   ├── generator/  # Code generation (page objects, step defs)
│   ├── parser/     # Gherkin feature file parser
│   ├── registry/   # Step registry + strict mapping
│   ├── reporter/   # Allure + TUI summary
│   ├── resolution/ # Element resolution chain
│   ├── sync/       # Selector diff engine
│   └── validator/  # Dry-run validation engine
├── llm/            # LLM providers (Claude, OpenAI, Gemini)
├── steps/          # Built-in step library (40+ steps)
└── utils/          # Logger, helpers

Tech Stack

• Runtime: TypeScript 5.x, Node.js
• Browser: Playwright
• BDD: Cucumber / Gherkin
• LLM: Anthropic Claude, OpenAI, Google Gemini
• CLI: Commander, @clack/prompts, chalk, ora
• Testing: Vitest
• Reporting: Allure

Configuration

Automa uses automa.config.yml at the project root:

project:
  name: my-app
  base_url: https://staging.myapp.com
  stack: playwright-cucumber-ts

llm:
  provider: claude
  model: claude-sonnet-4-6
  max_cost_per_run: 1.00

browser:
  default: chromium
  headless: false

execution:
  retries: 2
  parallel: false
  self_heal: true

Development

# Install dependencies
npm install

# Run tests
npm test

# Type check
npx tsc --noEmit

License

MIT