ColaFlow/QUICK-START-QA.md

# QA Quick Start Guide

## Sprint 1 QA Setup - Complete Checklist

### Phase 1: Environment Verification (5 minutes)

#### 1.1 Check Prerequisites
```bash
# Verify Docker is installed and running
docker --version
docker ps

# Verify .NET 9 SDK
dotnet --version

# Should output: 9.0.xxx
```

**Status**:
- [✅] Docker Desktop: v28.3.3 installed
- [✅] .NET SDK: 9.0.305 installed
- [❌] Docker Desktop: **NOT RUNNING** - Please start Docker Desktop before continuing

#### 1.2 Start Docker Desktop
1. Open Docker Desktop application
2. Wait for it to fully initialize (green icon in system tray)
3. Verify: `docker ps` runs without errors

---

### Phase 2: Docker Environment Setup (10 minutes)

#### 2.1 Review Configuration
```bash
# Navigate to project root
cd c:\Users\yaoji\git\ColaCoder\product-master

# Validate Docker Compose configuration
docker-compose config
```

#### 2.2 Start Services
```bash
# Start all services (PostgreSQL, Redis, Backend, Frontend)
docker-compose up -d

# View logs
docker-compose logs -f

# Check service health
docker-compose ps
```

**Expected Output**:
```
NAME                      STATUS              PORTS
colaflow-postgres         Up (healthy)        5432
colaflow-redis            Up (healthy)        6379
colaflow-api              Up (healthy)        5000, 5001
colaflow-web              Up (healthy)        3000
```

#### 2.3 Access Services

| Service | URL | Test Command |
|---------|-----|--------------|
| Frontend | http://localhost:3000 | Open in browser |
| Backend API | http://localhost:5000 | `curl http://localhost:5000/health` |
| PostgreSQL | localhost:5432 | `docker-compose exec postgres psql -U colaflow -d colaflow` |
| Redis | localhost:6379 | `docker-compose exec redis redis-cli -a colaflow_redis_password ping` |

---

### Phase 3: Test Framework Setup (15 minutes)

#### 3.1 Create Test Projects

Once backend development starts, create test projects:

```bash
cd tests

# Domain Tests
dotnet new xunit -n ColaFlow.Domain.Tests
cp ColaFlow.Domain.Tests.csproj.template ColaFlow.Domain.Tests/ColaFlow.Domain.Tests.csproj

# Application Tests
dotnet new xunit -n ColaFlow.Application.Tests
cp ColaFlow.Application.Tests.csproj.template ColaFlow.Application.Tests/ColaFlow.Application.Tests.csproj

# Integration Tests
dotnet new xunit -n ColaFlow.IntegrationTests
cp ColaFlow.IntegrationTests.csproj.template ColaFlow.IntegrationTests/ColaFlow.IntegrationTests.csproj

# Restore packages
dotnet restore
```

#### 3.2 Verify Test Projects Build
```bash
cd tests
dotnet build

# Expected: Build succeeded. 0 Error(s)
```

#### 3.3 Run Example Tests
```bash
# Run all tests
dotnet test

# Run with detailed output
dotnet test --logger "console;verbosity=detailed"
```

---

### Phase 4: Testcontainers Configuration (5 minutes)

#### 4.1 Verify Testcontainers Setup

Files already created:
- [✅] `tests/IntegrationTestBase.cs` - Base class for integration tests
- [✅] `tests/WebApplicationFactoryBase.cs` - API test factory
- [✅] `tests/TestContainers.config.json` - Testcontainers configuration

#### 4.2 Test Testcontainers

Once backend is implemented, run:
```bash
cd tests
dotnet test --filter Category=Integration
```

---

### Phase 5: Coverage & CI/CD Setup (10 minutes)

#### 5.1 Test Coverage Locally
```bash
# Run tests with coverage
cd tests
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

# Generate HTML report
dotnet tool install -g dotnet-reportgenerator-globaltool
reportgenerator -reports:coverage.opencover.xml -targetdir:coveragereport -reporttypes:Html

# Open report (Windows)
start coveragereport/index.html
```

#### 5.2 GitHub Actions Workflows

Files already created:
- [✅] `.github/workflows/test.yml` - Main test workflow
- [✅] `.github/workflows/coverage.yml` - Coverage workflow

**To trigger**:
1. Push code to `main` or `develop` branch
2. Create a pull request
3. Manually trigger via GitHub Actions UI

---

## Daily QA Workflow

### Morning Routine (10 minutes)
```bash
# 1. Pull latest changes
git pull origin develop

# 2. Restart Docker services
docker-compose down
docker-compose up -d

# 3. Check service health
docker-compose ps

# 4. Run tests
cd tests
dotnet test
```

### Before Committing (5 minutes)
```bash
# 1. Run all tests
dotnet test

# 2. Check coverage
dotnet test /p:CollectCoverage=true /p:Threshold=80

# 3. Commit if tests pass
git add .
git commit -m "Your commit message"
git push
```

### Bug Found - What to Do?
1. Create GitHub issue with template
2. Add label: `bug`, `sprint-1`
3. Assign priority: `critical`, `high`, `medium`, `low`
4. Notify team in Slack/Teams
5. Add to Sprint 1 Test Report

---

## Common Commands Reference

### Docker Commands
```bash
# Start services
docker-compose up -d

# Stop services
docker-compose stop

# View logs
docker-compose logs -f [service-name]

# Restart service
docker-compose restart [service-name]

# Remove everything (⚠️ DATA LOSS)
docker-compose down -v

# Shell into container
docker-compose exec [service-name] /bin/sh
```

### Testing Commands
```bash
# Run all tests
dotnet test

# Run specific project
dotnet test ColaFlow.Domain.Tests/

# Run specific test
dotnet test --filter "FullyQualifiedName~ProjectTests"

# Run by category
dotnet test --filter "Category=Unit"

# Run with coverage
dotnet test /p:CollectCoverage=true

# Parallel execution
dotnet test --parallel
```

### Database Commands
```bash
# Access PostgreSQL CLI
docker-compose exec postgres psql -U colaflow -d colaflow

# List tables
\dt

# Describe table
\d table_name

# Exit
\q

# Backup database
docker-compose exec postgres pg_dump -U colaflow colaflow > backup.sql

# Restore database
docker-compose exec -T postgres psql -U colaflow -d colaflow < backup.sql
```

---

## Troubleshooting

### Issue: Docker Desktop Not Running
**Error**: `error during connect: Get "http:///.../docker..."`

**Solution**:
1. Start Docker Desktop
2. Wait for initialization
3. Retry command

### Issue: Port Already in Use
**Error**: `Bind for 0.0.0.0:5432 failed`

**Solution**:
```bash
# Windows: Find process using port
netstat -ano | findstr :5432

# Kill process
taskkill /PID <PID> /F

# Or change port in docker-compose.yml
```

### Issue: Tests Failing
**Symptoms**: Red test output

**Solution**:
1. Check Docker services are running: `docker-compose ps`
2. Check logs: `docker-compose logs`
3. Clean and rebuild: `dotnet clean && dotnet build`
4. Check test data/database state

### Issue: Low Coverage
**Symptoms**: Coverage below 80%

**Solution**:
1. Generate detailed report: `reportgenerator ...`
2. Identify low-coverage files
3. Write missing tests
4. Focus on critical business logic first

---

## Next Steps

### Immediate (Today)
1. [✅] Start Docker Desktop
2. [✅] Verify `docker ps` works
3. [✅] Run `docker-compose up -d`
4. [✅] Access http://localhost:3000 and http://localhost:5000

### This Week
1. [ ] Wait for backend team to create initial Domain classes
2. [ ] Create actual test projects (using templates)
3. [ ] Write first unit tests for Project aggregate
4. [ ] Set up test data builders

### Sprint 1 Goals
- [✅] Docker environment working
- [✅] Testcontainers configured
- [✅] CI/CD pipelines ready
- [ ] 80%+ unit test coverage
- [ ] All API endpoints tested
- [ ] 0 critical bugs

---

## Resources

### Documentation
- [DOCKER-README.md](./DOCKER-README.md) - Complete Docker guide
- [tests/README.md](./tests/README.md) - Testing guide
- [M1-Architecture-Design.md](./docs/M1-Architecture-Design.md) - Architecture reference

### Templates
- [tests/ExampleDomainTest.cs](./tests/ExampleDomainTest.cs) - Unit test template
- [tests/ExampleIntegrationTest.cs](./tests/ExampleIntegrationTest.cs) - Integration test template
- [tests/SPRINT1-TEST-REPORT-TEMPLATE.md](./tests/SPRINT1-TEST-REPORT-TEMPLATE.md) - Report template

### Tools
- xUnit: https://xunit.net/
- FluentAssertions: https://fluentassertions.com/
- Testcontainers: https://dotnet.testcontainers.org/
- Coverlet: https://github.com/coverlet-coverage/coverlet

---

**Last Updated**: 2025-11-02
**Status**: Ready for Sprint 1
**Next Review**: After first backend implementation

---

## Quick Checklist

Copy this to your daily standup notes:

```
Today's QA Tasks:
- [ ] Docker services running
- [ ] All tests passing
- [ ] Coverage >= 80%
- [ ] No new critical bugs
- [ ] CI/CD pipeline green
- [ ] Test report updated
```