gridpilot.gg/tests/e2e/api/README.md

API Smoke Tests

This directory contains true end-to-end API smoke tests that make direct HTTP requests to the running API server to validate endpoint functionality and detect issues like "presenter not presented" errors.

Overview

The API smoke tests are designed to:

1. Test all public API endpoints - Make requests to discover and validate endpoints
2. Detect presenter errors - Identify use cases that return errors without calling this.output.present()
3. Validate response formats - Ensure endpoints return proper data structures
4. Test error handling - Verify graceful handling of invalid inputs
5. Generate detailed reports - Create JSON and Markdown reports of findings

Files

• api-smoke.test.ts - Main Playwright test file
• README.md - This documentation

Usage

Local Testing

Run the API smoke tests against a locally running API:

# Start the API server (in one terminal)
npm run docker:dev:up

# Run smoke tests (in another terminal)
npm run test:api:smoke

Docker Testing (Recommended)

Run the tests in the full Docker e2e environment:

# Start the complete e2e environment
npm run docker:e2e:up

# Run smoke tests in Docker
npm run test:api:smoke:docker

# Or use the unified command
npm run test:e2e:website  # This runs all e2e tests including API smoke

CI/CD Integration

Add to your CI pipeline:

# GitHub Actions example
- name: Start E2E Environment
  run: npm run docker:e2e:up

- name: Run API Smoke Tests
  run: npm run test:api:smoke:docker

- name: Upload Test Reports
  uses: actions/upload-artifact@v3
  with:
    name: api-smoke-reports
    path: |
      api-smoke-report.json
      api-smoke-report.md
      playwright-report/

Test Coverage

The smoke tests cover:

Race Endpoints

• /races/all - Get all races
• /races/total-races - Get total count
• /races/page-data - Get paginated data
• /races/reference/penalty-types - Reference data
• /races/{id} - Race details (with invalid IDs)
• /races/{id}/results - Race results
• /races/{id}/sof - Strength of field
• /races/{id}/protests - Protests
• /races/{id}/penalties - Penalties

League Endpoints

• /leagues/all - All leagues
• /leagues/available - Available leagues
• /leagues/{id} - League details
• /leagues/{id}/standings - Standings
• /leagues/{id}/schedule - Schedule

Team Endpoints

• /teams/all - All teams
• /teams/{id} - Team details
• /teams/{id}/members - Team members

Driver Endpoints

• /drivers/leaderboard - Leaderboard
• /drivers/total-drivers - Total count
• /drivers/{id} - Driver details

Media Endpoints

• /media/avatar/{id} - Avatar retrieval
• /media/{id} - Media retrieval

Sponsor Endpoints

• /sponsors/pricing - Sponsorship pricing
• /sponsors/dashboard - Sponsor dashboard
• /sponsors/{id} - Sponsor details

Auth Endpoints

• /auth/login - Login
• /auth/signup - Signup
• /auth/session - Session info

Dashboard Endpoints

• /dashboard/overview - Overview
• /dashboard/feed - Activity feed

Analytics Endpoints

• /analytics/metrics - Metrics
• /analytics/dashboard - Dashboard data

Admin Endpoints

• /admin/users - User management

Protest Endpoints

• /protests/race/{id} - Race protests

Payment Endpoints

• /payments/wallet - Wallet info

Notification Endpoints

• /notifications/unread - Unread notifications

Feature Flags

• /features - Feature flag configuration

Reports

After running tests, three reports are generated:

1. api-smoke-report.json - Detailed JSON report with all test results
2. api-smoke-report.md - Human-readable Markdown report
3. Playwright HTML report - Interactive test report (in playwright-report/)

Report Structure

{
  "timestamp": "2024-01-07T22:00:00Z",
  "summary": {
    "total": 50,
    "success": 45,
    "failed": 5,
    "presenterErrors": 3,
    "avgResponseTime": 45.2
  },
  "results": [...],
  "failures": [...]
}

Detecting Presenter Errors

The test specifically looks for the "Presenter not presented" error pattern:

// Detects these patterns:
- "Presenter not presented"
- "presenter not presented"
- Error messages containing these phrases

When found, these are flagged as presenter errors and require immediate attention.

Troubleshooting

API Not Ready

If tests fail because API isn't ready:

# Check API health
curl http://localhost:3101/health

# Wait longer in test setup (increase timeout in test file)

Port Conflicts

# Stop conflicting services
npm run docker:e2e:down

# Check what's running
docker-compose -f docker-compose.e2e.yml ps

Missing Data

The tests expect seeded data. If you see 404s:

# Ensure bootstrap is enabled
export GRIDPILOT_API_BOOTSTRAP=1

# Restart services
npm run docker:e2e:clean && npm run docker:e2e:up

Integration with Existing Tests

This smoke test complements the existing test suite:

• Unit tests (apps/api/src/**/*Service.test.ts) - Test individual services
• Integration tests (tests/integration/) - Test component interactions
• E2E website tests (tests/e2e/website/) - Test website functionality
• API smoke tests (this) - Test API endpoints directly

Best Practices

1. Run before deployments - Catch presenter errors before they reach production
2. Run in CI/CD - Automated regression testing
3. Review reports - Always check the generated reports
4. Fix presenter errors immediately - They indicate missing .present() calls
5. Keep tests updated - Add new endpoints as they're created

Performance

• Typical runtime: 30-60 seconds
• Parallel execution: Playwright runs tests in parallel by default
• Response time tracking: All requests are timed
• Average response time tracked in reports

Maintenance

When adding new endpoints:

1. Add them to the test arrays in api-smoke.test.ts
2. Test locally first: npm run test:api:smoke
3. Verify reports show expected results
4. Commit updated test file

When fixing presenter errors:

1. Run smoke test to identify failing endpoints
2. Check the specific error messages
3. Fix the use case to call this.output.present() before returning
4. Re-run smoke test to verify fix