Levante

AI-powered end-to-end test pipeline for Playwright. Record interactions, transcribe narration, generate Playwright tests, self-heal failures, and produce QA documentation — all driven by LLM agents.

Installation

npm install -g levante
# or
bun add -g levante

Levante requires Playwright as a peer dependency:

npm install -D @playwright/test

Quick Start

# 1. Initialize config and agents
levante init

# 2. Run full pipeline for a test case
levante run --key PROJ-101

# Or step by step
levante record --key PROJ-101
levante transcribe --key PROJ-101
levante scenario --key PROJ-101
levante generate --key PROJ-101
levante refine --key PROJ-101
levante test --key PROJ-101
levante heal --key PROJ-101        # only if test fails
levante qa --key PROJ-101

Environment Variables

| Variable | Description | |----------|-------------| | OPENAI_API_KEY | OpenAI API key | | ANTHROPIC_API_KEY | Anthropic API key | | QAI_BASE_URL | QA Intelligence API base URL | | QAI_API_URL | Full push endpoint (overrides base URL) | | QAI_API_KEY | API key for authenticated push |

Commands

levante init

Initialize levante in your project. Generates .qai/levante/config.ts, copies agent templates, and optionally connects to QA Intelligence.

levante init
levante init --non-interactive   # skip prompts, use defaults

On re-run, preserves your existing config and context, and only updates agents.

After init:

1. Generate .qai/levante/context.md using the init-agent prompt in your AI tool, or via MCP (levante_scan_codebase)
2. Review the generated context
3. Start recording: levante record --key PROJ-101

levante record [session]

Launch Playwright codegen with optional voice narration recording.

levante record --key PROJ-101
levante record --key PROJ-101 --no-companion   # voice only, no companion UI
levante record --key PROJ-101 --no-voice       # codegen only, no audio

| Option | Description | |--------|-------------| | --no-companion | Disable companion UI (voice recording only) | | --no-voice | Disable voice recording entirely |

Output: codegen TypeScript file + .wav audio (if voice enabled)

levante transcribe [session]

Transcribe the .wav voice recording via OpenAI Whisper. If a live transcript from the recording session exists, Whisper is skipped.

levante transcribe --key PROJ-101
levante transcribe --key PROJ-101 --force   # re-transcribe even if transcript exists

Merges voice annotations (with timestamps) back into the codegen file as inline comments.

Output: *-transcript.json, *-transcript.md, annotated codegen file

levante scenario [session]

Generate a structured YAML scenario from codegen output and voice transcript.

levante scenario --key PROJ-101

Uses transcript-agent (if transcript available) to extract narrative and action intents, then scenario-agent to produce a YAML scenario with title, precondition, steps, and postcondition. Jira/Linear issue context is included automatically if --key is set.

Output: .yaml scenario file in e2e/tests/[key]/

levante generate [scenario]

Generate a Playwright .test.ts file from a YAML scenario.

levante generate --key PROJ-101

Uses playwright-generator-agent with scenario + project context. If Zephyr is configured, also generates a Zephyr test case export.

Output: [key].test.ts in e2e/tests/[key]/

levante refine [test]

Refactor a generated test with AI — replaces raw selectors, improves structure, applies project patterns.

levante refine --key PROJ-101

Uses refactor-agent. Rewrites the test file in-place.

levante test [test]

Run the Playwright test with trace, video, and screenshot capture.

levante test --key PROJ-101
levante test --key PROJ-101 --no-trace

Output: Test execution logs, trace files in e2e/traces/

levante heal [test]

Self-heal a failing test. Diagnoses the failure, patches the test, and re-runs — up to 3 retries.

levante heal --key PROJ-101

Each attempt uses self-healing-agent with test content + error output + trace data to produce:

• diagnosis (failure type, root cause, confidence)
• patchedTest (updated test file)
• changes (summary of what was fixed)

Exits with error if all 3 attempts fail.

levante qa [test]

Generate QA documentation from the test and scenario.

levante qa --key PROJ-101

Uses qa-testcase-agent with test + scenario + Jira context. Produces markdown and/or Zephyr export depending on outputTarget.

Output: qa/[testId].md and/or Zephyr JSON

levante run [session]

Run the full pipeline: record → transcribe → scenario → generate → refine → test → heal → qa.

levante run --key PROJ-101
levante run --key PROJ-101 --from generate     # resume from a specific step
levante run --key PROJ-101 --skip transcribe,heal
levante run --key PROJ-101 --no-voice          # skip recording + transcription

| Option | Description | |--------|-------------| | --from <step> | Start from a specific step (skips earlier steps) | | --skip <steps> | Comma-separated step names to skip | | --no-voice | Disable voice recording (skips transcription too) | | --no-trace | Disable trace capture |

Steps (in order): record → transcribe → scenario → generate → refine → test → heal → qa

levante auth

Manage authentication with QA Intelligence.

levante auth login    # open browser for OAuth sign-in
levante auth logout   # revoke CLI token
levante auth status   # show current auth status
levante auth switch   # re-authenticate with a different org/project/app

levante jira

Interactive Jira integration for issue discovery and workflow launch.

levante jira browse

Interactive browser — search, view, and select Jira issues to start a test workflow.

levante jira browse

Select an issue to:

• run — save context and launch levante run --key <KEY>
• save — save issue context without running
• view — display full issue details

levante jira search <query>

Search Jira issues by text or raw JQL.

levante jira search "login flow"
levante jira search --jql "project = QA AND status = 'In Progress'"
levante jira search "dashboard" --max 10

| Option | Description | |--------|-------------| | <query> | Text search query | | --jql <jql> | Use raw JQL instead of text search | | --max <n> | Maximum results to return (default: 20) |

levante jira show <issueKey>

Display full details for a Jira issue.

levante jira show PROJ-101
levante jira show PROJ-101 --save    # also save context for pipeline use

| Option | Description | |--------|-------------| | --save | Save issue context to .qai/levante/issues/[KEY].json |

levante mcp

Print MCP server setup instructions.

levante mcp

Claude Code:

claude mcp add levante -- levante-mcp              # project-scoped
claude mcp add levante -s user -- levante-mcp      # global

Claude Desktop / other clients:

{
  "mcpServers": {
    "levante": { "command": "levante-mcp" }
  }
}

Available MCP tools:

| Tool | Description | |------|-------------| | levante_plan_workflow | Get ordered step list with prerequisite checks | | levante_execute_step | Execute a single pipeline step | | levante_get_workflow_guide | Read the full workflow guide | | levante_scan_codebase | Scan project for test infrastructure | | levante_validate_context | Validate context.md completeness | | levante_read_agent | Load an agent prompt by name | | levante_get_example | Get an example context.md template | | levante_scan_ast | Run AST scanner | | levante_scan_ast_detail | Drill into routes/components/hooks | | levante_build_qa_map | Build and validate QA map | | levante_read_qa_map | Load existing QA map |

Global Options

-k, --key <KEY>        Issue key (e.g. PROJ-101, LIN-42)
--provider <provider>  LLM provider: openai | anthropic
--model <model>        LLM model override
--verbose              Verbose output
--no-voice             Disable voice recording
--no-trace             Disable trace capture
-v, --version          Show version
-h, --help             Show help

Configuration

Configuration lives in .qai/levante/config.ts (generated by levante init):

import { defineConfig } from 'levante';

export default defineConfig({
  inputSource: 'jira',            // 'none' | 'jira' | 'linear'
  outputTarget: 'both',           // 'markdown' | 'zephyr' | 'both'
  baseUrl: 'http://localhost:3000',

  llm: {
    provider: 'openai',           // 'openai' | 'anthropic'
    model: 'gpt-4o',
    agentModels: {                 // per-agent model overrides
      'scenario-agent': 'claude-sonnet-4-20250514',
    },
  },

  playwright: {
    browser: 'chromium',          // 'chromium' | 'firefox' | 'webkit'
    timeout: 120_000,
    retries: 0,
    traceMode: 'on',              // 'on' | 'off' | 'retain-on-failure'
  },

  voice: {
    enabled: true,
    engine: 'webspeech',          // 'webspeech' | 'whisper'
    language: 'en-US',
  },

  paths: {
    tests: 'e2e/tests',
    scenarios: 'e2e/scenarios',
    recordings: 'e2e/recordings',
    transcripts: 'e2e/transcripts',
    traces: 'e2e/traces',
    qaOutput: 'qa',
  },

  integrations: {
    jira: { /* Jira config */ },
    zephyr: { titlePrefix: 'UI Automation' },
  },

  push: {
    apiUrl: 'https://qaligent.space/api',
    apiKey: 'your-key',
  },
});

AI Agents

Levante ships with agents copied to .qai/levante/agents/ on init. Edit them to tune AI behavior for your project.

| Agent | Purpose | |-------|---------| | 0.init-agent | Generate project context.md | | 1_1.transcript-agent | Analyze voice transcript + codegen into narrative | | 1_2.scenario-agent | Generate YAML scenario from narrative and actions | | 2.playwright-generator-agent | Generate Playwright test from YAML scenario | | 3.refactor-agent | Refactor test code for quality and conventions | | 4.self-healing-agent | Diagnose and patch failing tests | | 5.qa-testcase-agent | Generate QA documentation and Zephyr export |

Add .qai/levante/context.md to inject project-specific context into every agent call.

Project Structure

your-project/
  .qai/levante/
    config.ts                  # Configuration
    context.md                 # Project context for AI agents
    agents/                    # Agent prompts (customizable)
    workflow.md                # Pipeline workflow guide
    issues/                    # Saved Jira issue contexts
  e2e/
    tests/{key}/               # Generated test files + scenario YAML
    recordings/                # Codegen + voice recordings
    transcripts/               # Transcription output
    traces/                    # Playwright traces
  qa/                          # QA documentation output

Interactive TUI

Running levante with no arguments launches an interactive terminal UI (requires TTY, ≥ 60×20).

levante

License

MIT