From 70a637612deeafa43e43fb08c419d491e1eeaaf6 Mon Sep 17 00:00:00 2001 From: Danil Khaliulin Date: Fri, 20 Nov 2026 18:08:55 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=80=D1=83=D0=BA=D0=BE=D0=B2=D0=BE=D0=B4=D1=81?= =?UTF-8?q?=D1=82=D0=B2=D0=BE=20=D0=BF=D0=BE=20=D1=82=D0=B5=D1=81=D1=82?= =?UTF-8?q?=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD=D0=B8=D1=8E=20=D0=BA=D0=BE?= =?UTF-8?q?=D0=BC=D0=BF=D0=BE=D0=BD=D0=B5=D0=BD=D1=82=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Добавить страницу «Начало работы/Тестирование»: роли встроенного test-runner и e2e, запуск одной командой, отчёты и коды возврата. 2. Добавить в Getting Started раздел проверки компонента перед PR. Заметки для ревьюеров: - Только документация Storybook; e2e-харнесс локальный и в коммит не входит. --- src/stories/GettingStarted.mdx | 16 +++- src/stories/Testing.mdx | 132 +++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+), 2 deletions(-) create mode 100644 src/stories/Testing.mdx diff --git a/src/stories/GettingStarted.mdx b/src/stories/GettingStarted.mdx index 6a756763..595c4767 100644 --- a/src/stories/GettingStarted.mdx +++ b/src/stories/GettingStarted.mdx @@ -54,7 +54,19 @@ export class DemoComponent {} Список компонентов и их API — в разделе **Components** слева. -## 4. Tailwind v4 (опционально) +## 4. Проверить компонент + +Перед PR компонент проверяется одной командой: встроенный Storybook test-runner и e2e-сценарии. + +```bash +node e2e/check.mjs +``` + +Команда сама поднимет Storybook, прогонит оба уровня и запишет отчёт в `e2e/reports/-check.json`. + +Подробнее — страница «Тестирование» в разделе «Начало работы». + +## 5. Tailwind v4 (опционально) Кит отдаёт готовую Tailwind v4 тему (`@theme`), сгенерированную из тех же дизайн-токенов. Чтобы получить утилиты кита (цвета, типографику, radius, тени, spacing), добавьте в `styles.scss`: @@ -64,7 +76,7 @@ export class DemoComponent {} @use "@cdek-it/angular-ui-kit/tailwind"; ``` -## 5. Иконки (опционально) +## 6. Иконки (опционально) Компоненты используют [Tabler Icons](https://tabler.io/icons). Чтобы работали классы `ti ti-*`, установите пакет и подключите шрифт: diff --git a/src/stories/Testing.mdx b/src/stories/Testing.mdx new file mode 100644 index 00000000..51079a22 --- /dev/null +++ b/src/stories/Testing.mdx @@ -0,0 +1,132 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Тестирование компонентов + +Как проверить компонент перед PR: одной командой. + +## Коротко + +```bash +node e2e/check.mjs +``` + +Команда сама поднимет Storybook (если он не запущен), прогонит встроенный Storybook test-runner и e2e-спеку компонента и запишет общий отчёт: + +- **куда** — `e2e/reports/-check.json`; +- **формат** — JSON со статусами `builtin` и `e2e`, exit-кодами и путями к детальным отчётам; +- **что возвращает** — код завершения процесса: `0` — всё прошло, `1` — есть упавшие тесты, `2` — ошибка запуска (например, Storybook не поднялся или компонент не найден). + +Код `0/1` нужен не для чтения глазами, а для автоматики: терминал и IDE подсвечивают результат, CI останавливает пайплайн на `1` и не пропускает PR. Тестировщик при этом видит итог в терминале, а детали и скриншоты — в JSON-отчёте и `e2e/artifacts/`. + +## Два уровня проверок + +**Встроенный test-runner** + +- **Роль** — регрессионная сеть по всему каталогу stories компонента. +- **Польза** — без написания тестов ловит упавший рендер, новые critical/serious a11y-нарушения и дрейф стилей после правок токенов. +- **Что проверяет** — рендер каждой story, `play`, axe и вычисленные стили. +- **Когда падает** — новая a11y-ошибка или расхождение с baseline. +- **Отчёт** — вывод Jest и baseline. + +**E2E-раннер** + +- **Роль** — проверка пользовательских сценариев компонента. +- **Польза** — ловит поломки клавиатуры, фокуса, оверлеев и состояний, которые не видны в статичной story. +- **Что проверяет** — клики, ввод, клавиатуру, фокус, открытие/закрытие и выбранные значения. +- **Когда падает** — сломанный сценарий или неверное состояние. +- **Отчёт** — `e2e/reports/*.json` и скриншоты. + +## Быстрый старт + +```bash +# Storybook нужен один раз; check.mjs поднимет его сам +npm run storybook -- --port 6007 + +# всё по одному компоненту +node e2e/check.mjs +node e2e/check.mjs --theme=light,dark + +# только один уровень +node e2e/check.mjs --no-e2e +node e2e/check.mjs --no-builtin + +# все компоненты +node e2e/builtin-all.mjs +node e2e/all.mjs +``` + +Storybook проекта — `http://localhost:6007`; этот адрес `check.mjs` использует по умолчанию. Если Storybook запущен на другом порту, передайте свой `--url`. + +## Что получилось + +- `e2e/reports/-check.json` — общий статус: `builtin`, `e2e`, exit-коды и пути к деталям; +- `e2e/reports/-builtin-runner.json` — результаты встроенного раннера; +- `e2e/reports/-e2e.json` — результаты e2e; +- `e2e/artifacts//` — скриншоты упавших тестов. + +`knownIssue` — известный дефект: тест остаётся в отчёте, но не валит прогон. `failed` — блокирует PR. + +## Добавить e2e новому компоненту + +Спека лежит в `e2e/specs/.e2e.mjs`: + +```js +export default { + component: '', + stories: { + default: 'components----default' + }, + tests: [ + { + name: 'Default: компонент отрендерен', + story: 'default', + run: async ({ page, expect }) => { + await page.waitForSelector(''); + expect(await page.locator('').count(), 'компонент').toBe(1); + } + } + ] +}; +``` + +Правила: + +- story id берите из живого `index.json`, а не из `storybook-static` — он отстаёт; +- селекторы — роли, `aria-*`, `data-pc-section`, а не сгенерированные `pn_id_*`; +- оверлеи PrimeNG живут в `body`, вне `#storybook-root`; +- один тест — один сценарий; общие шаги выносите в локальные хелперы; +- найденный дефект фиксируйте через `knownIssue`, а не удаляйте проверку. + +## Baseline + +Встроенный раннер сравнивает вычисленные стили и axe с baseline: + +- рабочая матрица использует `e2e/baselines`, её не нужно трогать вручную; +- для локального «чистого» прогона: `node e2e/check.mjs --fresh-baselines`; +- обновление baseline — осознанное действие: `UPDATE_STYLE_BASELINES=1` / `UPDATE_A11Y_BASELINE=1`. + +## CI + +```bash +node e2e/builtin-all.mjs +node e2e/all.mjs --theme=light +``` + +Оба шага должны быть зелёными; `e2e/reports` и `e2e/artifacts` складывайте в артефакты CI. + +## Частые ошибки + +- **Storybook не запущен** — уберите `--no-start-storybook` или поднимите Storybook вручную. +- **Компонент не найден** — укажите title: `node e2e/check.mjs /`. +- **Короткое имя неоднозначно** — используйте точный title `Components/`. +- **Story id не найден** — story переименовали, обновите id из `index.json`. +- **E2E-спека не подходит к ветке** — укажите другую через `--spec=`. + +## Чек-лист перед PR + +- `node e2e/check.mjs ` — exit `0`; +- `check-stories-source` и `check-stories-descriptions` — PASS; +- сборка библиотеки проходит; +- новые `knownIssue` описаны в отчёте и понятны ревьюеру.