{"id":43614613,"url":"https://github.com/pyrex41/dreamup","last_synced_at":"2026-02-04T12:23:46.188Z","repository":{"id":322374318,"uuid":"1089113016","full_name":"pyrex41/dreamup","owner":"pyrex41","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-04T05:59:06.000Z","size":38679,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-04T06:15:49.161Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyrex41.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-03T22:44:58.000Z","updated_at":"2025-11-04T05:32:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pyrex41/dreamup","commit_stats":null,"previous_names":["pyrex41/dreamup"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pyrex41/dreamup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fdreamup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fdreamup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fdreamup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fdreamup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrex41","download_url":"https://codeload.github.com/pyrex41/dreamup/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fdreamup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29084187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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-02-04T12:23:46.108Z","updated_at":"2026-02-04T12:23:46.177Z","avatar_url":"https://github.com/pyrex41.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DreamUp QA Agent\n\n**Automated QA testing for web-based games using AI-powered evaluation**\n\n[![Status](https://img.shields.io/badge/status-production--ready-green)]()\n[![Go Version](https://img.shields.io/badge/go-1.24+-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-blue)]()\n\n🚀 **Live Demo**: [dreamup.fly.dev](https://dreamup.fly.dev)\n\n📚 **Documentation**: [Architecture Guide](ARCHITECTURE.md) | [Deployment Guide](DEPLOYMENT.md)\n\n## Overview\n\nDreamUp QA Agent is a fully automated testing system for web-based games. It uses browser automation, AI-powered visual analysis, and intelligent reporting to evaluate game quality, identify issues, and provide actionable recommendations.\n\n### Key Features\n\n- 🤖 **AI-Powered Evaluation**: GPT-4 Vision analyzes screenshots and gameplay\n- 🌐 **Browser Automation**: Headless Chrome with chromedp\n- 📸 **Evidence Collection**: Screenshots, console logs, UI detection\n- 📊 **Comprehensive Reports**: JSON reports with S3 storage\n- ⚡ **Serverless Ready**: AWS Lambda deployment with Terraform\n- 🔄 **Error Handling**: Automatic retry with exponential backoff\n- 🎯 **Smart Detection**: Automatic UI element detection\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Build the CLI\ngo build -o qa ./cmd/qa\n\n# Run a test\n./qa test --url https://example.com/your-game\n\n# With custom options\n./qa test \\\n  --url https://example.com/your-game \\\n  --output ./results \\\n  --headless=true \\\n  --max-duration 300\n```\n\n### Configuration\n\nEnvironment variables:\n```bash\nexport OPENAI_API_KEY=\"sk-...\"      # For AI evaluation\nexport S3_BUCKET_NAME=\"my-bucket\"   # For artifact storage (optional)\nexport AWS_REGION=\"us-east-1\"       # AWS region (optional)\n```\n\nOr use a config file (`config.yaml`):\n```yaml\noutput_dir: ./qa-results\nheadless: true\nmax_duration: 300\n```\n\n## Lambda Deployment\n\n### Build Lambda Package\n\n```bash\n./scripts/build-lambda.sh\n```\n\nThis creates `lambda-deployment.zip` ready for AWS Lambda.\n\n### Deploy with Terraform\n\n```bash\ncd deployment/terraform\n\n# Create terraform.tfvars\ncat \u003e terraform.tfvars \u003c\u003cEOF\naws_region      = \"us-east-1\"\nenvironment     = \"prod\"\ns3_bucket_name  = \"my-qa-artifacts\"\nopenai_api_key  = \"sk-...\"\nEOF\n\n# Deploy\nterraform init\nterraform apply\n```\n\n### Invoke Lambda\n\n```bash\naws lambda invoke \\\n  --function-name dreamup-qa-agent \\\n  --payload '{\"game_url\":\"https://example.com/game\",\"upload_to_s3\":true}' \\\n  response.json\n```\n\n## How It Works\n\n1. **Browser Launch**: Headless Chrome starts with optimized settings\n2. **Console Monitoring**: Captures all browser console logs (errors, warnings, info)\n3. **Navigation**: Loads the game URL with timeout protection\n4. **UI Detection**: Automatically finds start buttons and game canvas\n5. **Interaction**: Executes smart interaction plan based on detected UI\n6. **Evidence Collection**: Captures screenshots at key moments\n7. **AI Evaluation**: GPT-4 Vision analyzes screenshots and logs\n8. **Report Generation**: Creates comprehensive JSON report\n9. **S3 Upload**: Optionally uploads all artifacts to S3\n10. **Results**: Returns detailed test summary with scores and issues\n\n## Test Report Structure\n\n```json\n{\n  \"report_id\": \"uuid\",\n  \"game_url\": \"https://example.com/game\",\n  \"timestamp\": \"2025-11-03T10:00:00Z\",\n  \"duration_ms\": 15000,\n  \"score\": {\n    \"overall_score\": 85,\n    \"loads_correctly\": true,\n    \"interactivity_score\": 90,\n    \"visual_quality\": 80,\n    \"error_severity\": 10,\n    \"reasoning\": \"Game loads and functions well...\",\n    \"issues\": [\"Minor console warnings\"],\n    \"recommendations\": [\"Improve error handling\"]\n  },\n  \"evidence\": {\n    \"screenshots\": [...],\n    \"console_logs\": [...],\n    \"log_summary\": {\n      \"total\": 5,\n      \"errors\": 0,\n      \"warnings\": 2\n    }\n  },\n  \"summary\": {\n    \"status\": \"passed\",\n    \"passed_checks\": [\"Game loads successfully\", \"No console errors\"],\n    \"failed_checks\": [],\n    \"critical_issues\": []\n  }\n}\n```\n\n## Architecture\n\n```\n┌─────────────────┐\n│   CLI / Lambda  │\n└────────┬────────┘\n         │\n    ┌────▼─────────────────────────────┐\n    │     Test Orchestration           │\n    │  (Error Handling + Retry)        │\n    └────┬─────────────────────────────┘\n         │\n    ┌────▼────────┐  ┌──────────────┐  ┌──────────────┐\n    │   Browser   │  │  Evaluator   │  │   Reporter   │\n    │   Agent     │  │  (GPT-4)     │  │   (S3)       │\n    └─────────────┘  └──────────────┘  └──────────────┘\n         │                  │                  │\n    ┌────▼────────┐  ┌──────▼──────┐  ┌────────▼────────┐\n    │Screenshots  │  │  AI Scores  │  │  JSON + Upload  │\n    │Console Logs │  │ + Issues    │  │                 │\n    │UI Detection │  │             │  │                 │\n    └─────────────┘  └─────────────┘  └─────────────────┘\n```\n\n## Project Structure\n\n```\ndreamup/\n├── cmd/\n│   ├── qa/          # CLI application\n│   └── lambda/      # AWS Lambda handler\n├── internal/\n│   ├── agent/       # Browser automation + interactions\n│   ├── evaluator/   # AI evaluation (GPT-4 Vision)\n│   └── reporter/    # Report generation + S3 upload\n├── deployment/\n│   └── terraform/   # Infrastructure as Code\n├── scripts/\n│   └── build-lambda.sh\n└── log_docs/        # Project logs\n```\n\n## API Reference\n\n### CLI Commands\n\n```bash\nqa test --url \u003cURL\u003e              # Run test on game URL\nqa test --help                   # Show all options\nqa --version                     # Show version\n```\n\n### Lambda Event\n\n```json\n{\n  \"game_url\": \"https://example.com/game\",\n  \"upload_to_s3\": true,\n  \"timeout\": 280,\n  \"metadata\": {\n    \"build_id\": \"12345\",\n    \"environment\": \"production\"\n  }\n}\n```\n\n### Lambda Response\n\n```json\n{\n  \"success\": true,\n  \"report_id\": \"uuid\",\n  \"report_url\": \"https://s3.amazonaws.com/...\",\n  \"status\": \"passed\",\n  \"duration_seconds\": 12.5,\n  \"summary\": { ... }\n}\n```\n\n## Dependencies\n\n- **chromedp**: Browser automation\n- **go-openai**: GPT-4 Vision integration\n- **aws-sdk-go-v2**: S3 upload + Lambda\n- **cobra**: CLI framework\n- **viper**: Configuration management\n- **uuid**: Unique ID generation\n\n## Development\n\n### Requirements\n\n- Go 1.24+\n- Chrome/Chromium installed\n- AWS credentials (for S3 upload)\n- OpenAI API key (for evaluation)\n\n### Build\n\n```bash\n# Build CLI\ngo build -o qa ./cmd/qa\n\n# Build Lambda\nGOOS=linux GOARCH=amd64 go build -tags lambda.norpc -o bootstrap ./cmd/lambda\nzip lambda-deployment.zip bootstrap\n\n# Run tests (when available)\ngo test ./...\n```\n\n### Environment Setup\n\n```bash\n# Install dependencies\ngo mod download\n\n# Set up environment\ncp .env.example .env\n# Edit .env with your API keys\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `OPENAI_API_KEY` | OpenAI API key for evaluation | Yes (for AI) | - |\n| `S3_BUCKET_NAME` | S3 bucket for artifacts | No | `dreamup-qa-artifacts` |\n| `AWS_REGION` | AWS region | No | `us-east-1` |\n| `DREAMUP_OUTPUT_DIR` | Output directory | No | `./qa-results` |\n| `DREAMUP_HEADLESS` | Headless mode | No | `true` |\n\n### Config File (config.yaml)\n\n```yaml\noutput_dir: ./qa-results\nheadless: true\nmax_duration: 300\n```\n\n## Costs\n\n### AWS Lambda\n- **Compute**: ~$0.20 per 1000 invocations (2GB, 30s avg)\n- **S3**: ~$0.023 per GB/month\n- **CloudWatch**: ~$0.50 per GB logs\n\n**Typical monthly cost**: $5-20 for 100-500 tests/day\n\n## Monitoring\n\n- **CloudWatch Logs**: `/aws/lambda/dreamup-qa-agent`\n- **Metrics**: Duration, errors, invocations\n- **Alarms**: Set up for error rate \u003e 5%\n\n## Security\n\n- Store API keys in AWS Secrets Manager (not env vars)\n- Use IAM authorization for Lambda Function URL\n- Enable S3 encryption\n- Deploy Lambda in VPC for isolation\n\n## Troubleshooting\n\n### \"Browser failed to start\"\n- Ensure Chrome/Chromium is installed\n- Check headless mode is enabled\n- Verify no-sandbox flag is set\n\n### \"OPENAI_API_KEY not found\"\n- Set environment variable: `export OPENAI_API_KEY=\"sk-...\"`\n- Or configure in config.yaml\n\n### \"S3 upload failed\"\n- Verify AWS credentials are configured\n- Check S3 bucket exists and has correct permissions\n- Ensure AWS_REGION is set correctly\n\n### Lambda timeout\n- Increase timeout (max 15 minutes)\n- Increase memory (more memory = faster CPU)\n- Optimize game load time\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Acknowledgments\n\n- Built with [chromedp](https://github.com/chromedp/chromedp)\n- AI evaluation powered by OpenAI GPT-4 Vision\n- Infrastructure managed with Terraform\n- CLI framework by [Cobra](https://github.com/spf13/cobra)\n\n## Support\n\nFor issues, questions, or feature requests, please open an issue on GitHub.\n\n---\n\n**DreamUp QA Agent** - Automated game testing made simple 🎮🤖\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fdreamup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrex41%2Fdreamup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fdreamup/lists"}