cloud-server/scripts/README.md

# API Testing Scripts

This directory contains two types of API testing scripts:
- **api-tester.ts**: Endpoint-level testing (unit/integration)
- **e2e-tester.ts**: End-to-end scenario testing (workflow validation)

---

## e2e-tester.ts

End-to-End testing script that validates complete user workflows against the deployed production API.

### Quick Start

```bash
# Run all scenarios
npm run test:e2e

# Dry run (preview without actual API calls)
npm run test:e2e:dry

# Run specific scenario
npx tsx scripts/e2e-tester.ts --scenario wordpress
npx tsx scripts/e2e-tester.ts --scenario budget
```

### Scenarios

#### Scenario 1: WordPress Server Recommendation

**Flow**: Recommendation → Detail Lookup → Validation

1. POST /recommend with WordPress stack (nginx, php-fpm, mysql)
2. Extract instance_id from first recommendation
3. GET /instances to fetch detailed specs
4. Validate specs meet requirements (memory >= 3072MB, vCPU >= 2)

**Run**: `npx tsx scripts/e2e-tester.ts --scenario wordpress`

---

#### Scenario 2: Budget-Constrained Search

**Flow**: Price Filter → Validation

1. GET /instances?max_price=50&sort_by=price&order=asc
2. Validate all results are within budget ($50/month)
3. Validate ascending price sort order

**Run**: `npx tsx scripts/e2e-tester.ts --scenario budget`

---

#### Scenario 3: Cross-Region Price Comparison

**Flow**: Multi-Region Query → Price Analysis

1. GET /instances?region=ap-northeast-1 (Tokyo)
2. GET /instances?region=ap-northeast-2 (Seoul)
3. Calculate average prices and compare regions

**Run**: `npx tsx scripts/e2e-tester.ts --scenario region`

---

#### Scenario 4: Provider Sync Verification

**Flow**: Sync → Health Check → Data Validation

1. POST /sync with provider: linode
2. GET /health to verify sync_status
3. GET /instances?provider=linode to confirm data exists

**Run**: `npx tsx scripts/e2e-tester.ts --scenario sync`

---

#### Scenario 5: Rate Limiting Test

**Flow**: Burst Requests → Rate Limit Detection

1. Send 10 rapid requests to /instances
2. Check for 429 Too Many Requests response
3. Verify Retry-After header

**Run**: `npx tsx scripts/e2e-tester.ts --scenario ratelimit`

---

### E2E Command Line Options

**Run All Scenarios**:
```bash
npm run test:e2e
```

**Run Specific Scenario**:
```bash
npx tsx scripts/e2e-tester.ts --scenario <name>
```

Available scenarios: `wordpress`, `budget`, `region`, `sync`, `ratelimit`

**Dry Run (Preview Only)**:
```bash
npm run test:e2e:dry
```

**Combine Options**:
```bash
npx tsx scripts/e2e-tester.ts --scenario wordpress --dry-run
```

### E2E Example Output

```
🎬 E2E Scenario Tester
================================
API: https://cloud-instances-api.kappa-d8e.workers.dev

▶️  Scenario 1: WordPress Server Recommendation → Detail Lookup
  Step 1: Request WordPress server recommendation...
    ✅ POST /recommend - 200 OK (150ms)
    Recommended: Linode 4GB ($24/mo) in Tokyo
  Step 2: Fetch instance details...
    ✅ GET /instances - 80ms
  Step 3: Validate specs...
    ✅ Memory: 4096MB >= 3072MB required
    ✅ vCPU: 2 >= 2 required
  ✅ Scenario PASSED (230ms)

================================
📊 E2E Report
  Scenarios: 1
  Passed: 1 ✅
  Failed: 0 ❌
  Total Duration: 0.2s
```

### E2E Exit Codes

- `0` - All scenarios passed
- `1` - One or more scenarios failed

---

## api-tester.ts

Comprehensive API endpoint tester for the Cloud Instances API.

### Features

- Tests all API endpoints with various parameter combinations
- Colorful console output with status indicators (✅❌⚠️)
- Response time measurement for each test
- Response schema validation
- Support for filtered testing (specific endpoints)
- Verbose mode for detailed response inspection
- Environment variable support for API configuration

### Usage

#### Basic Usage

Run all tests:
```bash
npx tsx scripts/api-tester.ts
```

#### Filter by Endpoint

Test only specific endpoint:
```bash
npx tsx scripts/api-tester.ts --endpoint=/health
npx tsx scripts/api-tester.ts --endpoint=/instances
npx tsx scripts/api-tester.ts --endpoint=/sync
npx tsx scripts/api-tester.ts --endpoint=/recommend
```

#### Verbose Mode

Show full response bodies:
```bash
npx tsx scripts/api-tester.ts --verbose
```

Combine with endpoint filter:
```bash
npx tsx scripts/api-tester.ts --endpoint=/instances --verbose
```

#### Environment Variables

Override API URL and key:
```bash
API_URL=https://my-api.example.com API_KEY=my-secret-key npx tsx scripts/api-tester.ts
```

### Test Coverage

#### /health Endpoint
- GET without authentication
- GET with authentication
- Response schema validation

#### /instances Endpoint
- Basic query (no filters)
- Provider filter (`linode`, `vultr`, `aws`)
- Memory filter (`min_memory_gb`, `max_memory_gb`)
- vCPU filter (`min_vcpu`, `max_vcpu`)
- Price filter (`max_price`)
- GPU filter (`has_gpu=true`)
- Sorting (`sort_by=price`, `order=asc/desc`)
- Pagination (`limit`, `offset`)
- Combined filters
- Invalid provider (error case)
- No authentication (error case)

#### /sync Endpoint
- Linode provider sync
- Invalid provider (error case)
- No authentication (error case)

#### /recommend Endpoint
- Basic recommendation (nginx + mysql, small scale)
- With budget constraint
- Large scale deployment
- Multiple stack components
- Invalid stack (error case)
- Invalid scale (error case)
- No authentication (error case)

### Example Output

```
🧪 Cloud Instances API Tester
================================
Target: https://cloud-instances-api.kappa-d8e.workers.dev
API Key: 0f955192075f7d36b143...

📍 Testing /health
  ✅ GET /health (no auth) - 200 (45ms)
  ✅ GET /health (with auth) - 200 (52ms)

📍 Testing /instances
  ✅ GET /instances (basic) - 200 (120ms)
  ✅ GET /instances?provider=linode - 200 (95ms)
  ✅ GET /instances?min_memory_gb=4 - 200 (88ms)
  ✅ GET /instances?min_vcpu=2&max_vcpu=8 - 200 (110ms)
  ✅ GET /instances?max_price=50 - 200 (105ms)
  ✅ GET /instances?has_gpu=true - 200 (98ms)
  ✅ GET /instances?sort_by=price&order=asc - 200 (115ms)
  ✅ GET /instances?limit=10&offset=0 - 200 (92ms)
  ✅ GET /instances (combined) - 200 (125ms)
  ✅ GET /instances?provider=invalid (error) - 400 (65ms)
  ✅ GET /instances (no auth - error) - 401 (55ms)

📍 Testing /sync
  ✅ POST /sync (linode) - 200 (2500ms)
  ✅ POST /sync (no auth - error) - 401 (60ms)
  ✅ POST /sync (invalid provider - error) - 200 (85ms)

📍 Testing /recommend
  ✅ POST /recommend (nginx+mysql) - 200 (150ms)
  ✅ POST /recommend (with budget) - 200 (165ms)
  ✅ POST /recommend (large scale) - 200 (175ms)
  ✅ POST /recommend (invalid stack - error) - 200 (80ms)
  ✅ POST /recommend (invalid scale - error) - 200 (75ms)
  ✅ POST /recommend (no auth - error) - 401 (58ms)

================================
📊 Test Report
  Total: 24 tests
  Passed: 24 ✅
  Failed: 0 ❌
  Duration: 4.5s
```

### Exit Codes

- `0`: All tests passed
- `1`: One or more tests failed or fatal error occurred

### Notes

- Tests are designed to be non-destructive (safe to run against production)
- Sync endpoint tests use only the 'linode' provider to minimize impact
- Response validation checks basic structure and required fields
- Timing measurements include network latency
- Color output is optimized for dark terminal themes