wings88/docs/testing.md

# Testing Guide

This document provides information on how to run tests for the 3D Flight Simulator project.

## 🧪 Test Structure

The project uses a combination of unit tests and end-to-end tests:

```
tests/
├── unit/          # Unit tests (Jest)
│   └── *.test.js  # Test files
└── integration/   # Integration tests (Playwright)
    └── *.spec.js  # Test files
```

## 🚀 Running Tests

### Prerequisites

- Node.js (v16 or higher)
- npm or yarn
- Playwright browsers (installed automatically when running tests)

### Running Unit Tests

To run unit tests using Jest:

```bash
# Run all unit tests
npm test

# Run unit tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- tests/unit/example.test.js

# Run tests with coverage
npm test -- --coverage
```

### Running Playwright Tests

To run end-to-end tests using Playwright:

```bash
# Run all Playwright tests
npm run test:e2e

# Run tests in headed mode (visible browser)
npx playwright test --headed

# Run tests for specific browser
npx playwright test --project=chromium

# Run specific test file
npx playwright test tests/integration/example.spec.js

# Run tests in debug mode
npm run test:debug
```

### Running All Tests

To run both unit and Playwright tests:

```bash
npm run test:all
```

## 📝 Writing Tests

### Unit Tests

Unit tests are written using Jest and should test individual functions or components in isolation.

**Example:**

```javascript
// tests/unit/math.test.js
describe('Math utilities', () => {
  it('should add two numbers', () => {
    const result = add(2, 3);
    expect(result).toBe(5);
  });
});
```

### Playwright Tests

Playwright tests are written using the Playwright Test Runner and should test user interactions and page behavior.

**Example:**

```javascript
// tests/integration/loading-screen.spec.js
const { test, expect } = require('@playwright/test');

test('should display loading screen', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle(/3D Flight Simulator/);
  await expect(page.locator('.loading-screen')).toBeVisible();
});
```

## 🔧 Test Configuration

### Jest Configuration

The Jest configuration is located in `jest.config.js`. Key settings:

- `testEnvironment`: 'node' (for backend tests)
- `testMatch`: '**/tests/unit/**/*.test.js'
- `coverageDirectory`: 'coverage'

### Playwright Configuration

The Playwright configuration is located in `playwright.config.js`. Key settings:

- `testDir`: './tests'
- `use`: { `baseURL`: 'http://localhost:3000' }
- `projects`: [chromium] (default browser)

## 📊 Test Reports

### Jest Reports

Jest generates reports in the following formats:

- Text summary (console output)
- LCOV format (for coverage tools)
- HTML coverage report (in `coverage/lcov-report/index.html`)

### Playwright Reports

Playwright generates the following reports:

- Test results (console output)
- Trace files (for failed tests)
- Video recordings (for failed tests)
- Screenshots (for failed tests)

To view Playwright reports:

```bash
# View last test report
npx playwright show-report

# View trace for specific test
npx playwright show-trace trace/trace.zip
```

## 🤖 Continuous Integration

The project uses Gitea Actions for continuous integration. The workflow is defined in:

`.gitea/workflows/test.yml`

This workflow runs on:
- Push events to `main` and `dev` branches
- Pull request events targeting `main` and `dev` branches

The workflow performs the following steps:
1. Checkout code
2. Install dependencies
3. Install Playwright browsers
4. Run unit tests
5. Run Playwright tests
6. Upload test artifacts (if tests fail)

## 💡 Best Practices

1. **Test Naming**: Use descriptive test names that explain what is being tested
2. **Test Organization**: Group related tests in the same test file
3. **Test Isolation**: Ensure tests don't depend on each other
4. **Test Coverage**: Aim for high coverage, especially for critical paths
5. **Test Data**: Use realistic test data that matches production scenarios
6. **Test Performance**: Keep tests fast to encourage running them frequently

## 🐛 Debugging Tests

### Debugging Unit Tests

```bash
# Run tests in debug mode
npm test -- --debug

# Run specific test in debug mode
npm test -- --testNamePattern="should add two numbers" --debug
```

### Debugging Playwright Tests

```bash
# Run tests in debug mode
npm run test:debug

# Pause on first test failure
npx playwright test --debug

# Use Chrome DevTools
npx playwright test --headed
```

## 📞 Support

If you encounter issues with the test infrastructure, please:
1. Check the test output for error messages
2. Verify that all dependencies are installed
3. Ensure your Node.js version is compatible
4. Review the test configuration files

For questions or issues, please open an issue in the repository.