{"id":48355062,"url":"https://github.com/kznr02/OpenTester","last_synced_at":"2026-04-21T01:01:20.163Z","repository":{"id":341013552,"uuid":"1165568791","full_name":"kznr02/OpenTester","owner":"kznr02","description":"AI-Drived end-to-end test platform","archived":false,"fork":false,"pushed_at":"2026-03-07T03:26:56.000Z","size":686,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T09:48:38.925Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kznr02.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T09:59:36.000Z","updated_at":"2026-03-07T02:06:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kznr02/OpenTester","commit_stats":null,"previous_names":["kznr02/opentester"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kznr02/OpenTester","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kznr02%2FOpenTester","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kznr02%2FOpenTester/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kznr02%2FOpenTester/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kznr02%2FOpenTester/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kznr02","download_url":"https://codeload.github.com/kznr02/OpenTester/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kznr02%2FOpenTester/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32072323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T11:00:25.772Z","updated_at":"2026-04-21T01:01:20.146Z","avatar_url":"https://github.com/kznr02.png","language":"TypeScript","funding_links":[],"categories":["Software"],"sub_categories":["Test Automation Frameworks"],"readme":"# OpenTester\n\n**MCP-First Testing Execution Infrastructure**\n\n[![PyPI version](https://badge.fury.io/py/opentester.svg)](https://badge.fury.io/py/opentester)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![kznr02/OpenTester MCP server](https://glama.ai/mcp/servers/kznr02/open-tester/badges/score.svg)](https://glama.ai/mcp/servers/kznr02/open-tester)\n\nOpenTester is a testing execution engine designed for AI coding tools (Claude Code, Cursor, OpenCode, etc.). It provides a unified DSL format and MCP interface, enabling Agents to generate, execute, and manage test cases, achieving an automated \"code-test-fix\" workflow.\n\n[![kznr02/OpenTester MCP server](https://glama.ai/mcp/servers/kznr02/open-tester/badges/card.svg)](https://glama.ai/mcp/servers/kznr02/open-tester)\n\n## Core Positioning\n\n```\n┌─────────────────────────────────────────┐\n│  AI Agent (Claude Code / Cursor / ...)  │\n│  ├─ Generate DSL test cases             │\n│  ├─ Decide testing strategies           │\n│  └─ Analyze failure reasons             │\n├─────────────────────────────────────────┤\n│  OpenTester (MCP Server)                │\n│  ├─ Validate DSL syntax                 │\n│  ├─ Execute tests (CLI/Web)             │\n│  ├─ Store cases/projects                │\n│  └─ Return structured results           │\n├─────────────────────────────────────────┤\n│  Web UI (Auxiliary Observation Panel)   │\n│  ├─ View execution progress             │\n│  ├─ Debug cases (create/edit)           │\n│  └─ View history reports                │\n└─────────────────────────────────────────┘\n```\n\n**Design Principles**:\n- **Agent Intelligence**: Test generation and failure analysis are handled by the Agent\n- **OpenTester Execution**: Focuses on DSL validation and test execution\n- **MCP-First**: All core features exposed through MCP\n- **Web UI Auxiliary**: Visual monitoring and debugging, not required\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install opentester\n\n# Or with uv\nuv pip install opentester\n```\n\n### Option 2: Install from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/kznr02/OpenTester.git\ncd OpenTester\n\n# Install backend\nuv pip install ./backend\n\n# Install frontend dependencies (optional)\ncd frontend\nnpm install\n```\n\n### Option 3: Direct Run (Development)\n\n```bash\ncd backend\nuv run opentester start\n```\n\n## Quick Start\n\n### Start Services\n\n```bash\n# Start both FastAPI + MCP (foreground mode with prefixed logs)\nopentester start\n\n# Daemon mode (detached background with log files)\nopentester start --daemon\n\n# Start only API\nopentester start --api\n\n# Start only MCP\nopentester start --mcp\n\n# Custom ports\nopentester start --api-port 8080 --mcp-port 8081\n\n# Check status\nopentester status\n\n# Stop services\nopentester stop\n\n# Environment check\nopentester doctor\n```\n\n**Foreground Mode Log Output:**\n```\n[API] INFO:     Started server process [12345]\n[API] INFO:     Waiting for application startup.\n[MCP] INFO:     Started MCP server on port 8001\n[API] INFO:     Application startup complete.\n```\n\n### Configure Claude Code (Streamable HTTP)\n\nAdd MCP configuration in `.claude/settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"opentester\": {\n      \"url\": \"http://localhost:8001/mcp\"\n    }\n  }\n}\n```\n\n\u003e **Note**: Current runtime transport is Streamable HTTP.\n\n### Usage Example\n\nConversation with Claude Code:\n\n```\nYou: Help me test the login functionality\n\nClaude: I'll create tests for the login feature...\n        [Generate DSL test case]\n        [Call MCP: validateDSL] ✓ Validation passed\n        [Call MCP: createProject] ✓ Project created\n        [Call MCP: saveCase] ✓ Case saved\n        [Call MCP: runCase]\n        Executing...\n        ✓ All passed\n```\n\n## Project Structure\n\n```\nOpenTester/\n├── backend/              # FastAPI + Python\n│   ├── opentester/\n│   │   ├── api/         # REST API (for Web UI)\n│   │   ├── core/        # Execution engine, storage\n│   │   ├── models/      # Pydantic models (DSL, Project)\n│   │   └── mcp/         # MCP Server (core)\n│   └── pyproject.toml\n├── frontend/            # React + TypeScript + Vite\n│   └── src/             # Web UI (observation panel)\n├── docs/\n│   ├── SKILL_PROMPT.md  # Agent Skill Prompt template\n│   ├── DSL_SPEC.md      # DSL syntax specification\n│   └── MCP.md           # MCP interface documentation\n├── README.md            # This document\n└── LICENSE              # MIT License\n```\n\n## Core Features\n\n### 1. DSL Validation\n\nAfter Agent generates DSL, OpenTester validates syntax correctness:\n\n```yaml\nversion: \"1.0\"\nmeta:\n  name: \"Login Test\"\nsteps:\n  - action: exec\n    command: \"curl http://localhost:3000/login\"\n  - action: assert\n    assertion:\n      type: stdout_contains\n      expected: \"token\"\n```\n\n### 2. Test Execution\n\nSupports execution targets:\n- **CLI**: subprocess command execution (implemented)\n- **WEB**: Playwright-based browser automation (implemented)\n- **GUI**: experimental executor routing (disabled by default)\n- **TUI**: experimental executor routing (disabled by default)\n\n### 3. Web Testing MVP + AI DOM Analysis\n\n- Web actions are executed by `WebExecutor` (Playwright)\n- Browser console, page errors, and failed requests are normalized into `diagnostic_events` for each execution step\n- Supports AI-assisted locator flow via `ai_locator` in DSL steps\n- Execution can pause in `paused_waiting_for_ai` status and wait for AI selector submission\n- Supports DOM snapshot + optional screenshot capture for AI analysis\n- Web UI and REST clients can retrieve persisted browser diagnostics from the execution diagnostics endpoints for post-run investigation\n\n### 3. Project Management\n\n- Projects stored in XDG data directory (`~/.local/share/opentester/` on Linux, `~/Library/Application Support/opentester/` on macOS, `%LOCALAPPDATA%\\opentester\\` on Windows)\n- PRD content persisted with projects (provided by Agent)\n- Test case version management\n- Template library for reusable DSL patterns\n\n### 4. Real-time Monitoring\n\n- WebSocket real-time execution progress push\n- Web UI visual display\n- Execution history traceability\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_projects` | List all test projects |\n| `get_project` | Get project details (including cases) |\n| `create_project` | Create project |\n| `delete_project` | Delete project |\n| `validate_dsl` | Validate DSL syntax |\n| `save_case` | Save test case |\n| `delete_case` | Delete test case |\n| `run_case` | Execute single case |\n| `run_project` | Execute project cases |\n| `stop_execution` | Stop execution |\n| `get_execution_status` | Get execution status |\n| `get_execution_log` | Get detailed logs |\n| `request_dom_analysis` | Get DOM snapshot for paused AI step |\n| `submit_ai_selector` | Submit selector to resume paused execution |\n| `list_paused_executions` | List executions waiting for AI analysis |\n| `list_templates` | List templates |\n| `create_template` | Create DSL template |\n| `instantiate_template` | Create case from template |\n\nSee [MCP Interface Documentation](docs/MCP.md) for details.\n\n## Documentation\n\nSee [documentation](docs/) for detailed guides:\n- [Architecture](docs/ARCHITECTURE.md) - System architecture and design decisions\n- [MCP Interface](docs/MCP.md) - MCP tool specifications\n- [DSL Specification](docs/DSL_SPEC.md) - YAML-based test definition language\n- [Development Guide](docs/DEVELOPMENT.md) - Development setup and contribution\n\nAgents using OpenTester need to include DSL generation specifications. Refer to [SKILL_PROMPT.md](docs/SKILL_PROMPT.md)\n\n## DSL Specification\n\nYAML-based test definition language. See [DSL_SPEC.md](docs/DSL_SPEC.md) for details.\n\n## Architecture\n\nSee [ARCHITECTURE.md](docs/ARCHITECTURE.md) for system architecture, design principles, and architectural decisions.\n\n## Development Guide\n\nDevelopers refer to [DEVELOPMENT.md](docs/DEVELOPMENT.md)\n\n## Web UI\n\nAuxiliary features:\n- View project list and details\n- Edit DSL cases (Monaco editor)\n- Monitor execution progress\n- View history reports\n\n**Note**: Web UI is not the main entry point. All core features are provided through MCP.\n\n## Ports\n\n- FastAPI (Web UI / REST API): http://localhost:8000\n- MCP Server: http://localhost:8001/mcp\n- API Docs: http://localhost:8000/docs\n- Web UI Dev Server: http://localhost:5173\n\n## Data Storage\n\nOpenTester follows the XDG Base Directory Specification:\n\n- **Projects**: `\u003cXDG_DATA_HOME\u003e/opentester/projects/{project_id}.json`\n  - Linux: `~/.local/share/opentester/projects/`\n  - macOS: `~/Library/Application Support/opentester/projects/`\n  - Windows: `%LOCALAPPDATA%\\opentester\\projects\\`\n- **Executions**: `\u003cXDG_DATA_HOME\u003e/opentester/executions/`\n- **Templates**: `\u003cXDG_DATA_HOME\u003e/opentester/templates/`\n- **Logs**: `\u003cXDG_DATA_HOME\u003e/opentester/logs/daemon/` (daemon mode service logs)\n- **Config**: `~/.config/opentester/` (or `$XDG_CONFIG_HOME/opentester/`)\n\n\n## Distribution\n\nRefer to [DISTRIBUTION.md](docs/DISTRIBUTION.md) for:\n- PyPI publishing\n- PyInstaller packaging\n- Docker images\n- System package managers\n\nQuick build executable:\n```bash\ncd backend\npip install pyinstaller\npyinstaller opentester.spec\n# Output: dist/opentester.exe (Windows) or dist/opentester (Linux/Mac)\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Documentation\n\n- [English Documentation](docs/)\n- [中文文档](docs/zh/)\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n**OpenTester** - MCP-First Testing Execution Platform\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkznr02%2FOpenTester","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkznr02%2FOpenTester","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkznr02%2FOpenTester/lists"}