https://github.com/pyrex41/dreamup
https://github.com/pyrex41/dreamup
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/pyrex41/dreamup
- Owner: pyrex41
- Created: 2025-11-03T22:44:58.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-11-04T05:59:06.000Z (8 months ago)
- Last Synced: 2025-11-04T06:15:49.161Z (8 months ago)
- Language: Go
- Size: 36.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# DreamUp QA Agent
**Automated QA testing for web-based games using AI-powered evaluation**
[]()
[]()
[]()
🚀 **Live Demo**: [dreamup.fly.dev](https://dreamup.fly.dev)
📚 **Documentation**: [Architecture Guide](ARCHITECTURE.md) | [Deployment Guide](DEPLOYMENT.md)
## Overview
DreamUp 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.
### Key Features
- 🤖 **AI-Powered Evaluation**: GPT-4 Vision analyzes screenshots and gameplay
- 🌐 **Browser Automation**: Headless Chrome with chromedp
- 📸 **Evidence Collection**: Screenshots, console logs, UI detection
- 📊 **Comprehensive Reports**: JSON reports with S3 storage
- ⚡ **Serverless Ready**: AWS Lambda deployment with Terraform
- 🔄 **Error Handling**: Automatic retry with exponential backoff
- 🎯 **Smart Detection**: Automatic UI element detection
## Quick Start
### CLI Usage
```bash
# Build the CLI
go build -o qa ./cmd/qa
# Run a test
./qa test --url https://example.com/your-game
# With custom options
./qa test \
--url https://example.com/your-game \
--output ./results \
--headless=true \
--max-duration 300
```
### Configuration
Environment variables:
```bash
export OPENAI_API_KEY="sk-..." # For AI evaluation
export S3_BUCKET_NAME="my-bucket" # For artifact storage (optional)
export AWS_REGION="us-east-1" # AWS region (optional)
```
Or use a config file (`config.yaml`):
```yaml
output_dir: ./qa-results
headless: true
max_duration: 300
```
## Lambda Deployment
### Build Lambda Package
```bash
./scripts/build-lambda.sh
```
This creates `lambda-deployment.zip` ready for AWS Lambda.
### Deploy with Terraform
```bash
cd deployment/terraform
# Create terraform.tfvars
cat > terraform.tfvars < # Run test on game URL
qa test --help # Show all options
qa --version # Show version
```
### Lambda Event
```json
{
"game_url": "https://example.com/game",
"upload_to_s3": true,
"timeout": 280,
"metadata": {
"build_id": "12345",
"environment": "production"
}
}
```
### Lambda Response
```json
{
"success": true,
"report_id": "uuid",
"report_url": "https://s3.amazonaws.com/...",
"status": "passed",
"duration_seconds": 12.5,
"summary": { ... }
}
```
## Dependencies
- **chromedp**: Browser automation
- **go-openai**: GPT-4 Vision integration
- **aws-sdk-go-v2**: S3 upload + Lambda
- **cobra**: CLI framework
- **viper**: Configuration management
- **uuid**: Unique ID generation
## Development
### Requirements
- Go 1.24+
- Chrome/Chromium installed
- AWS credentials (for S3 upload)
- OpenAI API key (for evaluation)
### Build
```bash
# Build CLI
go build -o qa ./cmd/qa
# Build Lambda
GOOS=linux GOARCH=amd64 go build -tags lambda.norpc -o bootstrap ./cmd/lambda
zip lambda-deployment.zip bootstrap
# Run tests (when available)
go test ./...
```
### Environment Setup
```bash
# Install dependencies
go mod download
# Set up environment
cp .env.example .env
# Edit .env with your API keys
```
## Configuration
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `OPENAI_API_KEY` | OpenAI API key for evaluation | Yes (for AI) | - |
| `S3_BUCKET_NAME` | S3 bucket for artifacts | No | `dreamup-qa-artifacts` |
| `AWS_REGION` | AWS region | No | `us-east-1` |
| `DREAMUP_OUTPUT_DIR` | Output directory | No | `./qa-results` |
| `DREAMUP_HEADLESS` | Headless mode | No | `true` |
### Config File (config.yaml)
```yaml
output_dir: ./qa-results
headless: true
max_duration: 300
```
## Costs
### AWS Lambda
- **Compute**: ~$0.20 per 1000 invocations (2GB, 30s avg)
- **S3**: ~$0.023 per GB/month
- **CloudWatch**: ~$0.50 per GB logs
**Typical monthly cost**: $5-20 for 100-500 tests/day
## Monitoring
- **CloudWatch Logs**: `/aws/lambda/dreamup-qa-agent`
- **Metrics**: Duration, errors, invocations
- **Alarms**: Set up for error rate > 5%
## Security
- Store API keys in AWS Secrets Manager (not env vars)
- Use IAM authorization for Lambda Function URL
- Enable S3 encryption
- Deploy Lambda in VPC for isolation
## Troubleshooting
### "Browser failed to start"
- Ensure Chrome/Chromium is installed
- Check headless mode is enabled
- Verify no-sandbox flag is set
### "OPENAI_API_KEY not found"
- Set environment variable: `export OPENAI_API_KEY="sk-..."`
- Or configure in config.yaml
### "S3 upload failed"
- Verify AWS credentials are configured
- Check S3 bucket exists and has correct permissions
- Ensure AWS_REGION is set correctly
### Lambda timeout
- Increase timeout (max 15 minutes)
- Increase memory (more memory = faster CPU)
- Optimize game load time
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Acknowledgments
- Built with [chromedp](https://github.com/chromedp/chromedp)
- AI evaluation powered by OpenAI GPT-4 Vision
- Infrastructure managed with Terraform
- CLI framework by [Cobra](https://github.com/spf13/cobra)
## Support
For issues, questions, or feature requests, please open an issue on GitHub.
---
**DreamUp QA Agent** - Automated game testing made simple 🎮🤖