Skip to content

README.md

Latest commit

 

History

History
186 lines (130 loc) · 5.21 KB

README.md

File metadata and controls

186 lines (130 loc) · 5.21 KB
Raw

BGSTM End-to-End Tests

This directory contains the Playwright end-to-end test suite for the BGSTM application.

Prerequisites

  • Node.js v20+
  • Docker and Docker Compose (for the full stack test environment)
  • A running BGSTM frontend and backend (locally or via Docker)

Installation

Install Playwright and its browser binaries from the frontend/ directory:

cd frontend
npm install
npx playwright install

To install only the Chromium browser (faster, used in CI):

npx playwright install --with-deps chromium

Running Tests Locally

Against a locally running dev server

  1. Start the backend and frontend dev server:

    # In one terminal – start the backend
cd backend
uvicorn app.main:app --reload --port 8000

# In another terminal – start the frontend Vite dev server
cd frontend
npm run dev  # runs on http://localhost:3000

  2. Seed the database with test data (optional but recommended):

    psql -U bgstm -d bgstm < frontend/tests/e2e/fixtures/seed.sql

  3. Run the tests:

    cd frontend
npm run test:e2e

Headed mode (visible browser)

cd frontend
npm run test:e2e:headed

Interactive UI mode

cd frontend
npm run test:e2e:ui

Running Tests with Docker Compose

The docker-compose.test.yml file at the project root spins up a self-contained test environment including a seeded PostgreSQL database, the FastAPI backend, and the production Nginx frontend build.

# From the project root
docker compose -f docker-compose.test.yml up -d

# Wait for services to be healthy, then run tests
cd frontend
PLAYWRIGHT_BASE_URL=http://localhost:3001 \
PLAYWRIGHT_API_URL=http://localhost:8001 \
npx playwright test

# Tear down when done
cd ..
docker compose -f docker-compose.test.yml down -v

Viewing the HTML Report

After a test run, Playwright generates an HTML report in frontend/playwright-report/.

cd frontend
npx playwright show-report

This opens an interactive report in your browser showing passed/failed tests, traces, and screenshots.

Environment Variables

Variable Default Description
PLAYWRIGHT_BASE_URL http://localhost:3000 Frontend base URL
PLAYWRIGHT_API_URL http://localhost:8000 Backend API base URL
E2E_ADMIN_EMAIL admin@test.com Admin user email for tests
E2E_ADMIN_PASSWORD password123 Admin user password for tests

Test Structure

frontend/tests/e2e/
├── helpers/
│   └── auth.ts               # Reusable login/logout helper functions
├── fixtures/
│   └── seed.sql              # Test data seeded into PostgreSQL for E2E runs
├── auth.spec.ts              # Registration, login, logout, protected route access
├── suggestions.spec.ts       # Suggestion dashboard: filters, accept, reject
├── crud.spec.ts              # Requirements & test case CRUD (create, edit, delete)
├── traceability.spec.ts      # Traceability matrix data, filtering, export buttons
├── exports.spec.ts           # CSV and PDF export downloads
├── rbac.spec.ts              # Role-based access control: viewer, reviewer, admin
└── notifications.spec.ts     # Notification bell, mark-as-read, lifecycle

Adding New Tests

  1. Create a new *.spec.ts file in frontend/tests/e2e/.

  2. Import helpers as needed:

    import { test, expect } from '@playwright/test';
import { login } from './helpers/auth';
import { apiLogin, apiCreateRequirement } from './helpers/api';

  3. Use test.beforeEach to authenticate and navigate to the correct page.

  4. Use test.skip() to conditionally skip tests when the required UI element is not present in the current seed data.

  5. Run npm run test:e2e to verify your new tests pass.

CI Integration

The .github/workflows/e2e-tests.yml workflow runs on every pull request and push to main that touches frontend or backend code. It:

  1. Starts the full stack via docker-compose.test.yml.
  2. Waits for health checks to pass.
  3. Runs Playwright against Chromium only (to keep CI fast).
  4. Uploads the HTML report and screenshots as artifacts on failure.

Known Caveats

Test data pollution across spec files

The E2E tests share a single database instance within a CI run. CRUD tests (crud.spec.ts) create, update, and delete records, which can affect assertions in later spec files (e.g., traceability.spec.ts). To avoid flaky tests:

  • Don't assert against data that CRUD tests modify — use records the CRUD tests don't touch (e.g., "Role-Based Access Control" instead of "User Authentication")
  • Consider adding a DB reset — a globalSetup script that re-seeds the database between spec files would make tests fully isolated

Playwright configuration highlights

Setting CI Value Local Value
Timeout 60s 30s
Retries 2 0
Workers 1 (serial) Auto (parallel)
Browsers Chromium only Chromium + Firefox + WebKit
Screenshots On failure only On failure only
Traces On first retry On first retry