127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
# 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
|
|
|
|
1. **Docker Base Image** - Pre-configured with Xvfb, x11vnc, noVNC for headless GUI
|
|
2. **Test Runner** - Orchestrates containers and AI agent interactions
|
|
3. **Test Specs** - YAML/Markdown files describing tests in natural language
|
|
4. **Results Reporter** - Captures screenshots, AI observations, pass/fail status
|
|
|
|
### Example Test Spec
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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`
|