quarc/tests/MIGRATION.md

Migracja testów na Playwright

Podsumowanie zmian

Wszystkie testy Quarc Framework zostały przeniesione na Playwright, co zapewnia:

✅ Automatyczne zarządzanie serwerem deweloperskim ✅ Testy w prawdziwej przeglądarce ✅ Lepsze debugowanie i raportowanie ✅ Szybsze wykonanie testów ✅ Jednolity framework dla e2e i unit testów

Struktura przed migracją

tests/
├── unit/
│   ├── run-tests.ts              # Własny runner
│   ├── test-processors.ts
│   ├── test-signals-reactivity.ts
│   ├── test-directives.ts
│   └── ... (19 plików testowych)
└── e2e/
    ├── run-e2e-tests.ts          # Własny runner z fetch()
    └── app/                      # Aplikacja testowa

Struktura po migracji

tests/
├── playwright/
│   ├── e2e/
│   │   └── pipes.spec.ts         # Wszystkie testy pipes
│   └── unit/
│       └── processors.spec.ts    # Placeholder dla testów jednostkowych
├── e2e/
│   └── app/                      # Aplikacja testowa (bez zmian)
├── playwright.config.ts          # Konfiguracja Playwright
├── package.json                  # Nowe skrypty
└── README.md                     # Dokumentacja

Kluczowe zmiany

1. Automatyczne zarządzanie serwerem

Przed:

// Ręczne uruchamianie serwera w run-e2e-tests.ts
const serverProcess = spawn('qu', ['serve'], { cwd: appDir });
// Ręczne zamykanie
serverProcess.kill();

Po:

// playwright.config.ts - Playwright zarządza automatycznie
webServer: {
  command: 'cd e2e/app && npm install && node ../../../cli/bin/qu.js serve',
  url: 'http://localhost:4200',
  reuseExistingServer: !process.env.CI,
  timeout: 120000,
}

2. Testy E2E

Przed:

// Własny runner z fetch() i parsowaniem HTML
const html = await fetch(`http://localhost:${port}/uppercase`).then(r => r.text());
const result = extractTextContent(html, '#test-1 .result');
const expected = extractTextContent(html, '#test-1 .expected');

Po:

// Playwright API
test('should transform hardcoded string', async ({ page }) => {
  await page.goto('/uppercase');
  await page.waitForSelector('#test-1', { timeout: 10000 });
  const result = await page.locator('#test-1 .result').textContent();
  const expected = await page.locator('#test-1 .expected').textContent();
  expect(result?.trim()).toBe(expected?.trim());
});

3. Skrypty NPM

Przed:

{
  "scripts": {
    "test": "npx ts-node run-tests.ts",
    "test:e2e": "echo 'E2E tests not yet implemented'"
  }
}

Po:

{
  "scripts": {
    "test": "playwright test",
    "test:e2e": "playwright test playwright/e2e",
    "test:unit": "playwright test playwright/unit",
    "test:headed": "playwright test --headed",
    "test:debug": "playwright test --debug",
    "test:ui": "playwright test --ui",
    "test:report": "playwright show-report"
  }
}

Zalety migracji

1. Automatyzacja

• Serwer deweloperski uruchamia się i zamyka automatycznie
• Nie trzeba ręcznie zarządzać procesami
• Współdzielenie serwera między uruchomieniami w trybie lokalnym

2. Prawdziwa przeglądarka

• Testy działają w rzeczywistym środowisku Chromium
• Pełna obsługa JavaScript, CSS, Web Components
• Możliwość testowania interakcji użytkownika

3. Debugowanie

• UI Mode - interaktywny interfejs do debugowania
• Traces - nagrywanie przebiegu testów
• Screenshots - automatyczne zrzuty ekranu przy błędach
• Video - nagrywanie wideo testów
• Debug mode - step-by-step debugging

4. Raportowanie

• HTML reports z wizualizacją wyników
• Screenshots i traces dla niepowodzeń
• Szczegółowe logi i stack traces
• Metryki wydajności

5. Wydajność

• Równoległe wykonanie testów (8 workers domyślnie)
• Retry mechanism dla niestabilnych testów
• Optymalizacja dla CI/CD

Usunięte pliki

Następujące pliki nie są już potrzebne:

• /web/quarc/tests/unit/run-tests.ts - zastąpione przez Playwright
• /web/quarc/tests/e2e/run-e2e-tests.ts - zastąpione przez Playwright
• Wszystkie stare testy jednostkowe w /web/quarc/tests/unit/test-*.ts

Uwaga: Stare pliki testowe pozostają w repozytorium jako referencja, ale nie są już używane.

Migracja własnych testów

Jeśli chcesz przenieść własne testy na Playwright:

E2E Test

1. Utwórz plik .spec.ts w playwright/e2e/
2. Użyj Playwright API:

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

test.describe('My Feature', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/my-route');
    await page.waitForSelector('#my-element');
  });

  test('should work correctly', async ({ page }) => {
    const result = await page.locator('#result').textContent();
    expect(result).toBe('expected value');
  });
});

Unit Test

Dla testów jednostkowych które nie wymagają DOM:

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

test.describe('My Unit Tests', () => {
  test('should calculate correctly', () => {
    expect(2 + 2).toBe(4);
  });
});

Uruchamianie testów

cd /web/quarc/tests

# Wszystkie testy
npm test

# Tylko E2E
npm run test:e2e

# Tylko unit
npm run test:unit

# Z widoczną przeglądarką
npm run test:headed

# Debug mode
npm run test:debug

# UI mode (interaktywny)
npm run test:ui

CI/CD

W środowisku CI Playwright automatycznie:

• Nie współdzieli serwera (reuseExistingServer: false)
• Używa 1 workera (sekwencyjne wykonanie)
• Wykonuje 2 retry dla niestabilnych testów
• Generuje HTML report

Problemy i rozwiązania

Problem: Testy timeout'ują

Rozwiązanie: Dodaj waitForSelector przed sprawdzaniem elementów:

await page.waitForSelector('#test-1', { timeout: 10000 });

Problem: Elementy nie są znalezione

Rozwiązanie: Sprawdź czy routing działa poprawnie i czy aplikacja się załadowała:

await page.goto('/route');
await page.waitForLoadState('networkidle');

Problem: Serwer nie startuje

Rozwiązanie: Sprawdź czy aplikacja jest zbudowana:

cd e2e/app
node ../../../cli/bin/qu.js build

Następne kroki

1. ✅ Migracja testów E2E pipes - UKOŃCZONE
2. ⏳ Dodanie testów dla innych funkcjonalności (routing, directives, etc.)
3. ⏳ Konfiguracja CI/CD pipeline
4. ⏳ Dodanie testów cross-browser (Firefox, Safari)
5. ⏳ Dodanie visual regression tests