# Playwright E2E тесты frontend

## Назначение

Playwright-тесты проверяют ключевые браузерные сценарии frontend-приложения UniVerse:

- редирект неавторизованного пользователя на страницу входа;
- отображение каталога открытых лекций;
- запись на доступную лекцию.

Тесты работают поверх production preview сборки frontend и используют mock API, поэтому для базового запуска не нужен поднятый backend.

## Где лежат файлы

- [playwright.config.ts](../frontend/playwright.config.ts) - конфигурация Playwright.
- [auth.spec.ts](../frontend/tests/e2e/auth.spec.ts) - сценарии аутентификации.
- [catalog.spec.ts](../frontend/tests/e2e/catalog.spec.ts) - сценарии каталога лекций.
- [mockApi.ts](../frontend/tests/e2e/support/mockApi.ts) - перехват и mock ответов API.
- [fixtures.ts](../frontend/tests/mocks/fixtures.ts) - тестовые данные.

## Как устроен запуск

Конфигурация находится во `frontend/playwright.config.ts`.

Основные параметры:

- `testDir: ./tests/e2e` - Playwright ищет тесты в папке `frontend/tests/e2e`.
- `baseURL: http://127.0.0.1:4173` - базовый адрес приложения в тестах.
- `webServer` запускает `pnpm preview --host 127.0.0.1 --port 4173`.
- В CI включены `2` retry и GitHub reporter.
- Локально используется list reporter.
- По умолчанию проект запускается в Chromium.

## Команды

Запуск всех E2E-тестов из корня репозитория:

```bash
pnpm -C frontend test:e2e
```

Интерактивный UI Playwright:

```bash
pnpm -C frontend test:e2e:ui
```

Если нужно вручную поднять preview-сервер:

```bash
pnpm -C frontend build-only
pnpm -C frontend test:e2e:preview
```

После этого можно запускать Playwright с переменной `PW_SKIP_WEB_SERVER=1`, чтобы он не стартовал свой `webServer`.

## Mock API

Тесты не обращаются к реальному backend. Вместо этого helper `mockApi(page, options)` перехватывает запросы к `/api/v1` через `page.route`.

Сейчас замоканы:

- `POST/GET /api/v1/auth/refresh` - refresh авторизации;
- `/api/v1/auth/me` - текущий пользователь;
- `/api/v1/users/me/stats` - статистика студента;
- `/api/v1/lectures` - список лекций;
- `/api/v1/lectures/{id}/enroll` - запись на лекцию.

Для авторизованного сценария используйте:

```ts
await mockApi(page, { authenticated: true })
```

Для проверки гостевого сценария:

```ts
await mockApi(page, { authenticated: false })
```

## Как добавлять новые тесты

1. Создавайте spec-файлы в `frontend/tests/e2e`.
2. Для страниц, которым нужен backend, сначала добавляйте нужные ответы в `mockApi.ts` и данные в `fixtures.ts`.
3. Проверяйте пользовательский результат через role/text/label locators: `getByRole`, `getByText`, `getByLabel`.
4. Не завязывайтесь на CSS-классы, если сценарий можно проверить через доступные пользователю элементы.
5. Для маршрутов под авторизацией вызывайте `mockApi(page, { authenticated: true })` до `page.goto(...)`.

## CI

Workflow находится в [.gitea/workflows/frontend-playwright.yml](../.gitea/workflows/frontend-playwright.yml).

Пайплайн:

1. Устанавливает зависимости через `pnpm install --frozen-lockfile`.
2. Собирает frontend командой `pnpm build-only`.
3. Устанавливает браузер Playwright Chromium.
4. Запускает `pnpm test:e2e`.

## Артефакты и отладка

Playwright сохраняет trace на первом retry: `trace: on-first-retry`.

Локально полезные команды:

```bash
pnpm -C frontend exec playwright show-report
pnpm -C frontend exec playwright show-trace ./test-results/<папка>/trace.zip
```

Папки `frontend/test-results` и `frontend/playwright-report` считаются временными артефактами тестовых прогонов.