GhostQA

AI personas walk your app so real users don't trip.

SpecterQA sends AI personas through your application — they look at the screen, decide what to do, and interact like real humans. No test scripts. No selectors. You describe personas and journeys in YAML, and SpecterQA handles the rest.

$ specterqa run -p myapp ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ SpecterQA Run ┃ ┃ Product: myapp Budget: $5.00 Viewport: 1280x720 ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ✓ Step 1/4: Navigate to homepage PASS 3.2s $0.0081 ✓ Step 2/4: Click signup link PASS 2.1s $0.0043 ✓ Step 3/4: Fill registration form PASS 8.7s $0.0312 ✓ Step 4/4: Verify dashboard loads PASS 4.5s $0.0127 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ALL TESTS PASSED ┃ ┃ Steps: 4/4 Findings: 0 Duration: 18.5s Cost: $0.0563 ┃ ┃ Run ID: GQA-RUN-20260222-143052-a1b2 ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Traditional E2E tests are brittle. You write selectors, they break. You maintain scripts, they rot. SpecterQA takes a different approach: AI vision models look at your actual UI and navigate it the way a person would.

You definepersonas(who is using your app) andjourneys(what they're trying to do). SpecterQA's engine takes a screenshot, sends it to a Claude vision model, gets back a decision ("click this button", "fill this field"), executes it via Playwright, takes another screenshot, and repeats until the goal is achieved or something goes wrong.

When something goes wrong, you get evidence: screenshots, UX observations, cost breakdowns, and findings categorized by severity.

SpecterQA is distributed via PyPI and requires Python 3.10 or later.

After installing, download the Playwright browser binaries:

For macOS native app testing and iOS Simulator support, install the optionalnativeextra:

For MCP server support (integrating SpecterQA as a tool in Claude Desktop, Cursor, or other MCP clients):

You will also need an Anthropic API key to run tests:

specterqa --version specterqa init # scaffold a sample project specterqa run -p demo

pip install specterqa specterqa install # downloads Playwright browsers specterqa init # scaffolds .specterqa/ with sample configs specterqa run -p demo # runs the sample journey

That's it. Three commands and an API key.

screenshot --> vision model --> action decision --> execute --> repeat

- Screenshot-- Playwright captures the current page state as a PNG
- Decide-- A Claude vision model receives the screenshot + persona context + goal, returns a structured JSON action (click,fill,navigate,scroll,keyboard,wait,done, orstuck)
- Execute-- Playwright performs the action (click at coordinates, type text, navigate to URL, etc.)
- Repeat-- Loop until the goal is achieved, the agent gets stuck, or the budget runs out

The persona's profile shapes how the AI behaves. A "tech-savvy developer" explores differently than a "frustrated first-time user." Persona patience, tech comfort, and frustrations all influence the system prompt.

Model routingkeeps costs down. Simple actions (click, scroll) use Haiku. Complex actions (form filling, initial assessment) use Sonnet. You can also route simple actions to a local Ollama model (llava:13b) for zero API cost on straightforward navigation.

- Persona-based testing-- Define AI users with backgrounds, goals, frustrations, and tech comfort levels. They don't just follow scripts; they react to what they see.
- Vision-powered-- No selectors, no DOM queries. The AI interprets screenshots like a human would. Catches visual/layout issues that selector-based tests miss entirely.
- YAML-configured-- Products, personas, and journeys are all YAML files. PMs can read them. No code to maintain.
- Budget enforcement-- Per-run, per-day, and per-month cost caps. The engine hard-stops if you hit the limit. No surprise bills.
- JUnit XML output-- Drop--junit-xml results.xmland plug it into any CI system.
- Tiered model routing-- Haiku for cheap navigation, Sonnet for complex reasoning, optional local Ollama for zero-cost simple actions.
- Multi-platform-- Web apps (via Playwright), macOS native apps (via Accessibility API + pyobjc), iOS Simulator (via simctl). Same YAML format, different runners.
- Evidence collection-- Every run produces screenshots, a findings report, cost breakdown, and a structured JSON result. Everything is saved to an evidence directory.
- Stuck detection-- If the AI repeats the same action or the UI stops changing, the engine escalates to a stronger model, then aborts if nothing works. No infinite loops.
- Template variables-- Use{{persona.credentials.email}}in your journey steps. Variables resolve from persona configs at runtime.
- Precondition checks-- Verify services are up before running tests. Fail fast with clear errors instead of wasting API calls.

SpecterQA uses three types of YAML config files, all living in.specterqa/:

product: name: myapp display_name: "My Application" base_url: "http://localhost:3000" services: frontend: url: "http://localhost:3000" health_endpoint: / viewports: desktop: width: 1280 height: 720 mobile: width: 375 height: 812 cost_limits: per_run_usd: 5.00

Persona (personas/alex-developer.yaml)

persona: name: alex_developer display_name: "Alex Chen" role: "Full-Stack Developer" age: 28 tech_comfort: high patience: medium preferred_device: desktop goals: - "Evaluate the app from a developer's perspective" - "Check for common UX anti-patterns" frustrations: - "Unclear error messages" - "Missing loading indicators" credentials: email: "alex@example.com" password: "TestPass123!"

scenario: id: onboarding-happy-path name: "Onboarding Happy Path" description: "New user signs up, completes onboarding, reaches dashboard." tags: [onboarding, critical_path, smoke] personas: - ref: alex_developer role: primary preconditions: - service: frontend check: / expected_status: 200 steps: - id: visit_homepage mode: browser goal: "Navigate to the homepage and verify it loads" checkpoints: - type: text_present value: "Welcome" - id: navigate_signup mode: browser goal: "Find and click the signup link" - id: fill_signup_form mode: browser goal: "Complete the signup form with test credentials" - id: verify_dashboard mode: browser goal: "Verify signup succeeded and the dashboard loads"

Seedocs/configuration.mdfor the full reference.

# yaml-language-server: $schema=../../schemas/product.schema.json

# Basic CI run specterqa run -p myapp --junit-xml results.xml # Smoke test (runs first scenario only, fast) specterqa run -p myapp --level smoke --budget 2.00 # JSON output for programmatic consumption specterqa run -p myapp --output json > results.json

Seedocs/ci-integration.mdfor GitHub Actions, GitLab CI, and CircleCI examples.

export SPECTERQA_BUDGET=2.00 specterqa run -p myapp # uses $2.00 budget specterqa run -p myapp --budget 5.00 # uses $5.00 budget (CLI flag wins)

Seedocs/cost-guide.mdfor detailed cost breakdowns and budgeting strategies.

product: name: my-mac-app app_type: native_macos app_path: /Applications/MyApp.app bundle_id: com.example.myapp

product: name: my-ios-app app_type: ios_simulator bundle_id: com.example.myiosapp simulator_device: "iPhone 15 Pro" simulator_os: "17.2"

{ "passed": true, "run_id": "GQA-RUN-20260222-143052-a1b2", "step_reports": [ { "step_id": "visit_homepage", "passed": true, "duration_seconds": 12.3 } ], "findings": [], "cost_usd": 0.4521 }

from specterqa.config import SpecterQAConfig from specterqa.engine.orchestrator import SpecterQAOrchestrator config = SpecterQAConfig() config.project_dir = Path(".specterqa") config.products_dir = Path(".specterqa/products") config.personas_dir = Path(".specterqa/personas") config.journeys_dir = Path(".specterqa/journeys") config.evidence_dir = Path(".specterqa/evidence") config.anthropic_api_key = "sk-ant-..." config.budget = 5.00 config.headless = True orchestrator = SpecterQAOrchestrator(config) report_md, all_passed = orchestrator.run(product="myapp", level="smoke")

SpecterQA exposes aprotocols.pymodule with Python Protocol classes (AIDecider,ActionExecutor) that let you swap in your own AI model or action backend:

from specterqa.engine.protocols import AIDecider, Decision class MyCustomDecider: def decide(self, goal, screenshot_base64, kwargs) -> Decision: # Your logic here ...

Add to your MCP client config (claude_desktop_config.jsonor equivalent):

{ "specterqa": { "command": "specterqa-mcp", "args": [] } }

The complete API reference is available atspecterqa.synctek.io/docs.

export SPECTERQA_ALLOWED_DIRS="/home/user/projects:/ci/workspaces"

Command injection fix (v0.2.1):Thecheck_commandfield in product YAML service definitions has been removed. It was the source of a critical command injection vulnerability. Precondition checks are now limited to TCP connectivity and HTTP health endpoint checks, which are safe. SeeSECURITY_ADVISORY.mdfor full details.

Reporting vulnerabilities:Do not open public issues for security bugs. Emailinfo@synctek.ioor seeSECURITY.mdfor the full disclosure policy.

- Requires an Anthropic API key.No API key, no testing. There's no free tier built into SpecterQA itself.
- Costs money.Every run makes API calls. A typical 3-step journey costs $0.30-0.60. Budget enforcement prevents surprises, but the meter is always running.
- Vision models aren't perfect.The AI sometimes misreads small text, clicks the wrong element, or gets confused by complex layouts. It's good, not infallible. You'll occasionally see false positives and false negatives.
- Not a replacement for unit tests.SpecterQA tests behavioral UX flows. It doesn't test your business logic, data integrity, or edge case handling. Use it alongside your existing test suite, not instead of it.
- macOS native testing requires pyobjc.Thespecterqa[native]extra pulls in pyobjc packages (~200MB). Only needed for native macOS and iOS Simulator testing.
- Alpha software.Version 0.4.0. APIs may change. File structure may change. Expect rough edges.
- Single-persona per journey (for now).Multi-persona concurrent testing (e.g., simulating a chat between two users) is on the roadmap but not yet supported.
- Deterministic reproduction is hard.**Because the AI makes decisions at runtime, the exact sequence of actions varies between runs. Same journey, same persona, slightly different clicks. This is by design (it catches more issues) but makes exact reproduction tricky.

Contributions welcome. The repo is atgithub.com/SyncTek-LLC/specterqa.

git clone https://github.com/SyncTek-LLC/specterqa.git cd specterqa pip install -e ".[dev]" pytest

Open an issue before starting large PRs. We'd rather discuss the approach first.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent

ALAPI MCP Tools,Call hundreds of API interfaces via MCP

AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform

MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.

APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB