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 18+ and npm
• Go 1.23+ (for building mock server)

Setup (One-time)

cd tests/integration
./scripts/setup.sh

This will:

• Install npm dependencies
• Install Playwright browsers
• Build Docker images for test environment

Running Tests

Run All Tests

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 UI: http://localhost:7655
• Mock GitHub API: http://localhost:8080
• Health checks:
  • http://localhost:7655/api/health
  • http://localhost:8080/health

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. Happy Path (01-happy-path.spec.ts)

• Valid checksums, successful update flow
• Tests complete update from UI to backend
• Verifies modal appears exactly once

2. Bad Checksums (02-bad-checksums.spec.ts)

• Server rejects update due to invalid checksums
• UI shows error once (not twice)
• Error messages are user-friendly

3. Rate Limiting (03-rate-limiting.spec.ts)

• Multiple rapid requests are throttled gracefully
• Proper rate limit headers returned
• Clear error messages when limited

4. Network Failure (04-network-failure.spec.ts)

• UI retries with exponential backoff
• Handles timeouts gracefully
• Shows appropriate loading states

5. Stale Release (05-stale-release.spec.ts)

• Backend refuses to install flagged releases
• Proper error messages about why release is rejected
• No backup created for rejected releases

6. Frontend Validation (06-frontend-validation.spec.ts)

• UpdateProgressModal appears exactly once
• Error messages are user-friendly (not raw API errors)
• Modal can be dismissed after error
• No duplicate modals on error
• Proper accessibility attributes

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

Tests run automatically on every PR that touches:

• internal/updates/**
• internal/api/updates.go
• frontend-modern/src/components/Update*.tsx
• frontend-modern/src/api/updates.ts
• frontend-modern/src/stores/updates.ts
• tests/integration/**

See .github/workflows/test-updates.yml for CI configuration.

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 { loginAsAdmin, navigateToSettings } from './helpers';

test('my new test', async ({ page }) => {
  await loginAsAdmin(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