pulse/tests/integration/QUICK_START.md

Quick Start Guide - Update Integration Tests

This guide will help you get the update integration tests running quickly.

Prerequisites

• Docker and Docker Compose
• Node.js 24 and npm
• Go 1.25+ (for building mock server)

Setup (One-time)

cd tests/integration
./scripts/setup.sh
```text

This will:
- Install npm dependencies
- Install Playwright browsers
- Build Docker images for test environment

## Running Tests

### Run All Tests

```bash
npm test

This runs all test suites with appropriate configurations.

Run Specific Test Suite

# Happy path only
./scripts/run-tests.sh happy

# Bad checksums
./scripts/run-tests.sh checksums

# Rate limiting
./scripts/run-tests.sh rate-limit

# Network failures
./scripts/run-tests.sh network

# Stale releases
./scripts/run-tests.sh stale

# Frontend validation
./scripts/run-tests.sh frontend

Interactive Mode

# Open Playwright UI
npm run test:ui

# Debug mode
npm run test:debug

# Run in headed browser
npm run test:headed

Manual Docker Control

# Start test environment
npm run docker:up

# View logs
npm run docker:logs

# Stop environment
npm run docker:down

# Rebuild images
npm run docker:rebuild

Accessing Test Services

While the test environment is running:

• Pulse test UI (embedded frontend): http://localhost:7655
• Mock GitHub API: http://localhost:8080
• Health checks:
  • http://localhost:7655/api/health
  • http://localhost:8080/health

For the repo-local managed dev runtime, use npm run dev from the repo root and browse http://127.0.0.1:5173 instead. :7655 in this quick start is the backend-served test UI inside the docker environment, not the canonical hot-dev browser shell.

Viewing Test Results

After running tests:

# View HTML report
npm run test:report

# Reports are saved to:
# - playwright-report/ (HTML report)
# - test-results/ (screenshots, videos)

Test Scenarios

1. Diagnostic Smoke Test (00-diagnostic.spec.ts)

• Ensures the containerized stack boots and the UI renders.

2. Core E2E Flows (01-core-e2e.spec.ts)

• First-run setup wizard (fresh instance)
• Login/logout + authenticated state
• Alerts thresholds create/delete
• Settings persistence across refresh
• Add/delete a Proxmox node (test-only)

Troubleshooting

Tests failing to start

# Check Docker is running
docker ps

# Rebuild images
npm run docker:rebuild

# Check logs
npm run docker:logs

Port conflicts

If ports 7655 or 8080 are in use:

# Find and stop conflicting processes
lsof -i :7655
lsof -i :8080

Clean slate

# Remove all test containers and volumes
docker-compose -f docker-compose.test.yml down -v

# Clean Docker
docker system prune -f

# Reinstall
./scripts/setup.sh

CI Integration

The full Playwright suite, including the update-flow spec (tests/79-update-flow.spec.ts), runs via .github/workflows/test-e2e.yml on every push and PR that touches:

• internal/**
• frontend-modern/**
• tests/integration/**
• Dockerfile

Success Criteria

✅ All test scenarios pass reliably ✅ Tests catch checksum validation issues (like v4.28.0) ✅ Frontend UX regressions are blocked ✅ Tests run in CI on every relevant PR

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│  Playwright     │────▶│  Pulse Server    │────▶│  Mock GitHub API    │
│  (Browser UI)   │     │  (Test Instance) │     │  (Controlled        │
│                 │     │                  │     │   Responses)        │
└─────────────────┘     └──────────────────┘     └─────────────────────┘

The mock GitHub server provides controllable responses for testing different scenarios via environment variables:

• MOCK_CHECKSUM_ERROR=true - Return invalid checksums
• MOCK_NETWORK_ERROR=true - Simulate network failures
• MOCK_RATE_LIMIT=true - Enable aggressive rate limiting
• MOCK_STALE_RELEASE=true - Mark releases as stale

Writing New Tests

1. Add test file to tests/ directory
2. Use helpers from tests/helpers.ts
3. Follow existing test patterns
4. Update run-tests.sh if new environment config needed
5. Update CI workflow if needed

Example:

import { test, expect } from '@playwright/test';
import { ensureAuthenticated, navigateToSettings } from './helpers';

test('my new test', async ({ page }) => {
  await ensureAuthenticated(page);
  await navigateToSettings(page);

  // Your test logic here
});

Getting Help

• Check the main README for detailed information
• Review existing test files for examples
• Check Docker logs for service issues
• Review Playwright documentation: https://playwright.dev

Worktree-safe shell runner

scripts/run-tests.sh builds unique per-invocation image tags and uses a unique Compose project and container names. Host ports are allocated by Docker on loopback and discovered after startup; this runner does not honour fixed port or base-URL overrides. Its EXIT/INT/TERM/HUP cleanup removes only that invocation's stack, volumes and image tags. SIGKILL or host failure can leave resources behind; the printed pulse-e2e-… project identifies those resources for manual cleanup.

This isolation applies to the shell runner, not direct npm test, setup.sh or hand-written Compose commands, which retain legacy defaults. Do not use those defaults concurrently for checkout-specific qualification.