soleprint/station/tools/tester/playwright/README.md

Playwright Test Integration

Frontend test support for ward/tools/tester.

Features

• Discover Playwright tests (.spec.ts files)
• Execute tests with Playwright runner
• Capture video recordings and screenshots
• Stream artifacts via API endpoints
• Inline video/screenshot playback in test results

Directory Structure

ward/tools/tester/
├── playwright/
│   ├── discovery.py    # Find .spec.ts tests
│   ├── runner.py       # Execute Playwright tests
│   └── artifacts.py    # Store and serve artifacts
├── frontend-tests/     # Synced Playwright tests (gitignored)
└── artifacts/          # Test artifacts (gitignored)
    ├── videos/
    ├── screenshots/
    └── traces/

Test Metadata Format

Add Gherkin metadata to Playwright tests via JSDoc comments:

/**
 * Feature: Reservar turno veterinario
 * Scenario: Verificar cobertura en zona disponible
 * Tags: @smoke @coverage @frontend
 * @description Coverage check shows message for valid address
 */
test('coverage check shows message for valid address', async ({ page }) => {
  await page.goto('http://localhost:3000/turnero');
  await page.fill('[name="address"]', 'Av Santa Fe 1234, CABA');
  await page.click('button:has-text("Verificar")');

  await expect(page.locator('.coverage-message')).toContainText('Tenemos cobertura');
});

Playwright Configuration

Tests should use playwright.config.ts with video/screenshot capture:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    // Capture video on failure
    video: 'retain-on-failure',
    // Capture screenshot on failure
    screenshot: 'only-on-failure',
  },

  // Output directory for artifacts
  outputDir: './test-results',

  reporter: [
    ['json', { outputFile: 'results.json' }],
    ['html'],
  ],
});

API Endpoints

Stream Artifact

GET /tools/tester/api/artifact/{run_id}/{filename}

Returns video/screenshot file for inline playback.

List Artifacts

GET /tools/tester/api/artifacts/{run_id}

Returns JSON list of all artifacts for a test run.

Artifact Display

Videos and screenshots are displayed inline in test results:

Video:

<video controls>
  <source src="/tools/tester/api/artifact/{run_id}/test-video.webm" type="video/webm">
</video>

Screenshot:

<img src="/tools/tester/api/artifact/{run_id}/screenshot.png">

Integration with Test Runner

Playwright tests are discovered alongside backend tests and can be:

• Run individually or in batches
• Filtered by Gherkin metadata (feature, scenario, tags)
• Filtered by pulse variables (role, stage, state)

Future Enhancements

• Playwright trace viewer integration
• Test parallelization
• Browser selection (chromium, firefox, webkit)
• Mobile device emulation
• Network throttling
• Test retry logic