# E2E Test Environment Setup

This guide provides instructions for setting up the local environment to run E2E tests for the MetaDrivenPlatform4AI/NexusCRM project.

## Prerequisites

- **Node.js** v24.x or later
- **npm** v11.x or later
- **Go** 1.22.x or later
- **Docker** (for local TiDB) OR access to TiDB Cloud
- **MySQL Client** (for database operations)

## Quick Start

```bash
# 1. Install dependencies
npm install

# 2. Install Playwright browsers
npx playwright install --with-deps

# 3. Copy environment template
cp .env.example .env.test

# 4. Start TiDB (Docker)
docker run -d --name tidb-test -p 4000:4000 -p 10080:10080 pingcap/tidb:latest

# 5. Reset and seed database
./tests/e2e/scripts/reset-db.sh

# 6. Run E2E tests
npx playwright test
```

---

## Docker + TiDB Setup

### Option A: Local TiDB with Docker (Recommended for Development)

```bash
# Pull the TiDB image
docker pull pingcap/tidb:latest

# Start TiDB container
docker run -d --name tidb-test \
  -p 4000:4000 \
  -p 10080:10080 \
  pingcap/tidb:latest

# Wait for TiDB to be ready (approximately 10-15 seconds)
sleep 10

# Verify TiDB is running
docker ps | grep tidb-test

# Test connection (requires mysql client)
mysql -h 127.0.0.1 -P 4000 -u root -e "SELECT version();"
```

**Connection Details:**
| Parameter | Value |
|-----------|-------|
| Host      | localhost |
| Port      | 4000 |
| User      | root |
| Password  | (empty) |
| Database  | nexuscrm_test |

### Option B: TiDB Cloud (Production/Staging)

1. Create a TiDB Cloud cluster at https://tidbcloud.com
2. Get your cluster connection details from the dashboard
3. Update `.env.test` with your TiDB Cloud credentials

---

## Database Reset & Seed

### Reset Database

The reset script drops and recreates the test database:

```bash
# Reset local test database
./tests/e2e/scripts/reset-db.sh

# Reset with specific environment
./tests/e2e/scripts/reset-db.sh staging
```

### Seed Test Data

Seed the database with test accounts, contacts, and opportunities:

```bash
# Seed test data
cd tests/e2e/scripts
go run seed-test-data.go
```

### Test Users

After seeding, the following test accounts are available:

| Username  | Email                    | Password   | Profile        |
|-----------|--------------------------|------------|----------------|
| admin     | admin@nexuscrm.test      | *(set via `NEXUS_ADMIN_PASSWORD` env var)* | System Admin   |
| testuser  | testuser@nexuscrm.test   | Test123!   | Standard User  |
| readonly  | readonly@nexuscrm.test   | Read123!   | Read Only      |

---

## Frontend/Backend Startup Commands

### Frontend (Development)

```bash
# Start frontend dev server (Vite)
cd frontend
npm run dev

# Or from project root
npm run dev:client
```

Frontend will be available at: http://localhost:5173

### Backend (Development)

```bash
# Start backend server (Go)
cd backend
export $(grep -v '^#' ../.env.test | xargs)
PORT=3001 go run cmd/server/main.go

# Or from project root
npm run dev:server
```

Backend API will be available at: http://localhost:3001

### Full Stack (Both Frontend + Backend)

```bash
# Start both servers concurrently
npm run dev:full
```

---

## Environment Variables

### .env.test Template

Copy `.env.example` to `.env.test` and configure:

```bash
# Environment
NODE_ENV=test

# Database Configuration (REQUIRED)
TIDB_HOST=localhost
TIDB_PORT=4000
TIDB_USER=root
TIDB_PASSWORD=
TIDB_DATABASE=nexuscrm_test

# Server Configuration
PORT=3001
API_BASE_URL=http://localhost:3001

# Frontend Configuration
REACT_APP_BACKEND_URL=http://localhost:3001
REACT_APP_FRONTEND_URL=http://localhost:5173
FRONTEND_URL=http://localhost:5173

# Feature Flags
FEATURE_WEBSOCKET=true
FEATURE_DEBUG_MODE=false
FEATURE_TRACE_LOGGING=false

# Allowed Origins (for CORS/WebSocket)
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3001,http://127.0.0.1:5173
```

### Environment Variable Reference

| Variable | Description | Default |
|----------|-------------|---------|
| `NODE_ENV` | Runtime environment | `test` |
| `TIDB_HOST` | TiDB host | `localhost` |
| `TIDB_PORT` | TiDB port | `4000` |
| `TIDB_USER` | TiDB username | `root` |
| `TIDB_PASSWORD` | TiDB password | (empty) |
| `TIDB_DATABASE` | Database name | `nexuscrm_test` |
| `PORT` | Backend server port | `3001` |
| `FRONTEND_URL` | Frontend URL for CORS | `http://localhost:5173` |

---

## Validation: One Command to Check Everything

Run the validation script to verify all components are ready:

```bash
./tests/e2e/scripts/validate-env.sh
```

This checks:
- [ ] Node.js and npm installed
- [ ] Go installed
- [ ] Docker running (if using local TiDB)
- [ ] TiDB container running
- [ ] Database connection working
- [ ] Dependencies installed
- [ ] Playwright browsers installed

---

## Troubleshooting

### Docker Not Available

If Docker is not available, use TiDB Cloud:
1. Sign up at https://tidbcloud.com
2. Create a free serverless cluster
3. Update `.env.test` with your cluster credentials

### TiDB Connection Fails

```bash
# Check if TiDB container is running
docker ps | grep tidb-test

# Check container logs
docker logs tidb-test

# Restart container
docker restart tidb-test

# Remove and recreate
docker rm -f tidb-test
docker run -d --name tidb-test -p 4000:4000 pingcap/tidb:latest
```

### MySQL Client Not Found

```bash
# Ubuntu/Debian
sudo apt-get install mysql-client

# macOS
brew install mysql-client

# RHEL/CentOS
sudo yum install mysql
```

### Permission Denied on Reset Script

```bash
chmod +x tests/e2e/scripts/reset-db.sh
```

---

## Playwright Test Configuration

See `tests/e2e/playwright.config.ts` for:
- Browser configuration
- Test timeouts
- Reporter settings
- Project configurations

---

## Additional Resources

- [Playwright Documentation](https://playwright.dev)
- [TiDB Documentation](https://docs.pingcap.com/tidb/stable)
- [Project README](../../README.md)