feedBack/tests/browser/README.md

Browser Tests

This directory contains Playwright browser tests for FeedBack keyboard shortcuts.

Prerequisites

1. FeedBack web server: Tests need the server reachable at http://localhost:8000. Playwright auto-starts it via webServer.command in playwright.config.ts, so manual startup is optional. Start it manually if you want to debug the server, run tests outside Playwright, or skip the per-run boot delay:

   LIBRARY_PATH=/path/to/your/library docker compose up -d
   

   Playwright reuses an already-running server locally (reuseExistingServer: true).

2. Node.js installed: Required for running Playwright tests

   node --version  # Should be v18 or higher
   

Installation

Install dependencies:

npm install

Install Playwright browsers:

npm run install:playwright

Running Tests

Run all tests:

npm test

Run tests in headed mode (watch the browser):

npm run test:headed

Debug tests with interactive inspector:

npm run test:debug

Test Files

• basic-load.spec.ts - Basic app load and shortcut registry availability
• check-errors.spec.ts - Check for console errors
• keyboard-shortcuts.spec.ts - Comprehensive keyboard shortcut tests

Writing Tests

Tests use Playwright's test API. Example:

import { test, expect } from '@playwright/test';

test('my test', async ({ page }) => {
  await page.goto('/');
  await page.waitForSelector('.screen.active');
  
  // Interact with the page
  await page.keyboard.press('?');
  
  // Assert
  await expect(page.locator('#shortcuts-modal')).toBeVisible();
});

Troubleshooting

Container won't start

If the Docker container exits immediately, check the logs:

docker compose logs

Common issue: Missing dependencies. Rebuild the container:

docker compose build --no-cache
docker compose up -d

Tests timeout

Increase timeout in playwright.config.ts if needed.

LIBRARY_PATH not set

Make sure to set the LIBRARY_PATH environment variable:

LIBRARY_PATH=~/feedBack-library docker compose up -d

CI/CD

In CI environments, Playwright will:

• Run tests in headless mode
• Retry failed tests up to 2 times
• Generate HTML report with screenshots/videos on failure