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

cd tests
npm install

Running Tests

Using Docker Selenium (Headless - No visible browser)

# 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)

# 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

# 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/
├── config/
│   ├── jest.setup.js          # Docker Selenium configuration
│   ├── jest.setup.local.js    # Local Chrome configuration
│   └── test-utils.js          # Helper utilities
├── e2e/
│   ├── auth.test.js           # Main authentication test suite
│   ├── debug.test.js          # Simple connection test
│   ├── visual-auth.test.js    # Slow visual test for debugging
│   └── screenshot.test.js     # Takes screenshots for debugging
├── fixtures/
│   └── users.json             # Test user data
├── pages/
│   ├── BasePage.js            # Base page object
│   ├── LoginPage.js           # Login page object
│   ├── RegistrationPage.js    # Registration page object
│   └── DashboardPage.js       # Dashboard page object
└── 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:

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