gravl/frontend/TESTING.md

Gravl E2E Testing Guide

Overview

This project uses Playwright for E2E and API testing.

Test Suites

1. API Tests (tests/gravl.api.spec.js)

✅ Working - Uses Playwright's API context (no browser required)

Tests HTTP endpoints without launching a browser:

• Homepage accessibility check
• Login page accessibility
• API connectivity validation

Run API tests:

npx playwright test tests/gravl.api.spec.js

2. UI Tests (tests/gravl.spec.js)

⚠️ Requires System Setup - Needs graphics libraries

Tests interactive UI elements using browser automation:

• Login form visibility
• Logo detection
• Dashboard title validation

System Requirements:

• libXcomposite.so.1
• libX11 and related X11 libraries
• libwayland (for Wayland support)
• Other graphics/media libraries

Install on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y \
  libxcomposite1 libxdamage1 libxrandr2 libxinerama1 \
  libxcursor1 libxtst6 libxss1 libx11-6 libatk1.0-0 \
  libatk-bridge2.0-0 libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-0 \
  libgtk-3-0 libnss3 libnspr4 libdbus-1-3 libxext6 libxfixes3

Note: For CI/CD environments without X11, use API tests or containerized setup.

Running Tests

All tests (API only in this environment):

npx playwright test

With JSON report:

npx playwright test --reporter=json > test-results.json

Headless browser (requires system libraries):

STAGING_URL=http://localhost:3000 npx playwright test

Watch mode:

npx playwright test --watch

Configuration

File: playwright.config.js

• testDir: ./tests
• baseURL: http://localhost:5173 (dev) or $STAGING_URL
• Projects: API context (no browser)

Test Results

See /test-results/ directory for latest run reports.

Troubleshooting

"Executable doesn't exist" / Missing browsers

Run: npx playwright install

"cannot open shared object file: libXcomposite.so.1"

Browser engine missing system dependencies. Use API tests instead.

Tests timeout

Check if application is running on baseURL (e.g., http://localhost:5173)

Phase 06-04 Status

✅ API tests working - 3/3 passing ⚠️ UI tests blocked - Requires system graphics libraries (not available in this environment)

Workaround implemented: Use API tests for regression testing. Full E2E testing requires browser environment.