4.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

GhostQA - AI-powered visual GUI testing via natural language

GhostQA enables testing of desktop GUI applications (PyQt, GTK, etc.) using AI vision agents. Instead of writing brittle UI test scripts, describe expected behavior in natural language and let AI verify it visually.

How It Works

┌─────────────────────────────────────┐
│ Docker Container                    │
│ ┌─────────────┐   ┌──────────────┐ │
│ │ Target App  │──▶│ Xvfb + noVNC │──┼──▶ Public URL (Cloudflare)
│ └─────────────┘   └──────────────┘ │
└─────────────────────────────────────┘
                                       │
                          ┌────────────▼────────────┐
                          │ AI Agent                │
                          │ (ChatGPT, Claude, etc.) │
                          │                         │
                          │ "Click Projects,        │
                          │  verify 5 items shown"  │
                          └─────────────────────────┘

Core Components

Docker Base Image - Pre-configured with Xvfb, x11vnc, noVNC for headless GUI
Test Runner - Orchestrates containers and AI agent interactions
Test Specs - YAML/Markdown files describing tests in natural language
Results Reporter - Captures screenshots, AI observations, pass/fail status

Example Test Spec

name: Dashboard displays project list
app: development-hub
steps:
  - action: wait_for_window
    timeout: 10s
  - action: verify
    prompt: "Is there a list of projects visible on the left side?"
    expected: true
  - action: click
    prompt: "Click on the first project in the list"
  - action: verify
    prompt: "Does the right panel show a dashboard with todos and goals?"
    expected: true

Development Commands

# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Build the base Docker image
docker build -t ghostqa-base -f docker/Dockerfile.base .

# Run an app in test mode
ghostqa run --app development-hub --expose 6080

Architecture

src/ghostqa/
├── __init__.py
├── __main__.py           # CLI entry point
├── docker/
│   ├── base.py           # Base image builder
│   └── runner.py         # Container orchestration
├── agents/
│   ├── base.py           # Abstract AI agent interface
│   ├── chatgpt.py        # ChatGPT agent mode (via browser automation)
│   └── claude.py         # Claude computer-use API
├── specs/
│   ├── parser.py         # Parse test spec YAML/MD
│   └── models.py         # Test spec data models
├── runner.py             # Test execution engine
└── reporter.py           # Results and screenshots

Key Modules

Module	Purpose
`docker.runner`	Build and manage Docker containers with noVNC
`agents.base`	Abstract interface for AI vision agents
`specs.parser`	Parse natural language test specifications
`runner`	Execute tests, coordinate agents and containers
`reporter`	Generate test reports with screenshots

Key Paths

Source code: src/ghostqa/
Tests: tests/
Docker files: docker/
Example specs: examples/
Documentation: docs/ (symlink to project-docs)

Supported AI Agents

Agent	Method	Notes
ChatGPT Agent Mode	Browser automation to chat.openai.com	Included in Plus/Pro subscription
Claude Computer Use	API with vision + actions	Per-token pricing
Open source (browser-use)	Local LLM or API	Flexible, self-hosted

Documentation

Documentation lives in docs/ (symlink to centralized docs system).

Before updating docs, read docs/updating-documentation.md for full details on visibility rules and procedures.

Quick reference:

Edit files in docs/ folder
Use public: true frontmatter for public-facing docs
Deploy: ~/PycharmProjects/project-docs/scripts/build-public-docs.sh ghostqa --deploy

4.5 KiB Raw Blame History