trip-planner/tests/README.md

# E2E Testing Suite for Trip Planner

This directory contains end-to-end tests using Selenium WebDriver for the Trip Planner application.

## Setup

### Prerequisites

1. **Docker Setup (Recommended)**
   - Docker/Podman installed and running
   - All services running: `podman-compose -f ../docker-compose.dev.yml up -d`

2. **Local Setup (For visible browser testing)**
   - Chrome or Chromium browser installed locally
   - Frontend running on `http://localhost:5173`
   - Backend running on `http://localhost:8000`

### Installation

```bash
cd tests
npm install
```

## Running Tests

### Using Docker Selenium (Headless - No visible browser)

```bash
# Run all tests
npm test

# Run all tests in headless mode (explicitly)
npm run test:headless

# Run authentication tests only
npm run test:auth

# Run with verbose output
npm run test:debug
```

### Using Local Chrome (Visible browser on your machine)

```bash
# Run all tests with visible browser
npm run test:local

# Run debug test with visible browser
npm run test:local:debug

# Run specific test file locally
HEADLESS=false jest --config jest-local.json e2e/visual-auth.test.js
```

### Debugging Tests

```bash
# Simple debug test
npm run test:debug-simple

# Visual authentication test (slow, with pauses)
npm run test:local e2e/visual-auth.test.js

# Screenshot test (saves screenshots to tests/screenshots/)
npm test screenshot.test.js
```

## Test Structure

```
tests/
├── specs/
│   ├── auth/
│   │   └── auth-clean.test.js          # Clean authentication tests
│   └── integration/
│       └── full-auth-flow.test.js      # Full user journey test
├── support/
│   ├── config/
│   │   ├── jest.setup.js               # Docker Selenium configuration
│   │   ├── jest.setup.local.js         # Local Chrome configuration
│   │   └── test-utils.js               # Helper utilities
│   ├── pages/
│   │   ├── BasePage.js                 # Base page object
│   │   ├── LoginPage.js                # Login page object
│   │   ├── RegistrationPage.js         # Registration page object
│   │   └── DashboardPage.js            # Dashboard page object
│   ├── fixtures/
│   │   └── users.json                  # Test user data
│   └── helpers/
│       └── test-data.js                # Test data management
└── screenshots/                        # Screenshot output directory
```

## Environment Variables

- `HEADLESS=true/false` - Run Chrome in headless mode (Docker only)
- `BASE_URL` - Override default frontend URL (default: http://localhost:5173)
- `SELENIUM_HUB` - Override Selenium hub URL (default: http://localhost:4444)

## Common Issues

### Tests hang with no browser window
- You're using Docker Selenium. The browser runs inside a container (invisible)
- Use `npm run test:local` to see the browser on your machine

### Connection refused errors
- Ensure all Docker services are running: `podman-compose -f ../docker-compose.dev.yml up -d`
- Check frontend is accessible: `curl http://localhost:5173`
- Check backend is accessible: `curl http://localhost:8000`

### Chrome not found (local testing)
- Install Chrome: https://www.google.com/chrome/
- Or install Chromium: `sudo dnf install chromium` (Fedora) or `sudo apt install chromium-browser` (Ubuntu)

### Tests can't find auth forms
- The app uses a single-page auth guard, not separate /login and /register routes
- Forms are toggled on the same page using buttons

## Writing New Tests

1. Create test file in `e2e/` directory
2. Use page objects from `pages/` for better maintainability
3. Add test data to `fixtures/` as needed
4. Follow the pattern in existing tests

Example:
```javascript
const LoginPage = require('../pages/LoginPage');

describe('My New Test', () => {
  let driver;
  let loginPage;

  beforeAll(async () => {
    driver = await global.createDriver();
    loginPage = new LoginPage(driver);
  });

  afterAll(async () => {
    await global.quitDriver(driver);
  });

  test('should do something', async () => {
    await loginPage.navigateToLogin();
    // ... test logic
  });
});
```

## Tips

- Use `npm run test:local` when debugging to see what's happening
- Use `npm test screenshot.test.js` to capture screenshots when tests fail
- Add `await driver.sleep(2000)` to slow down tests for debugging
- Check Docker logs: `podman logs -f trip-planner-selenium-chrome`