TESTING.md

July 27, 2026 · View on GitHub

Быстрый старт

node --run test — запускает все unit-тесты;
node --run test:e2e — запускает в Docker-контейнере скриншотные тесты;
node --run test:e2e-update — запускает в Docker-контейнере обновление скриншотных тестов.

Виды тестов

Unit-тесты

Используем:

Описываем в файлах:

Если это обычная функция, то moduleName.test.ts, (например, packages/vkui/src/lib/adaptivity/functions.test.ts)
Если это React-компонент, то ComponentName.test.ts (например, Checkbox.test.tsx)

Скриншотные тесты

Используем:

@playwright/experimental-ct-react
git-lfs – помогает от раздувания репозитория из-за эталонных скриншотов.
Docker – запускаем тесты в докере, чтобы для тестов было одинаковое окружение, что в CI, что локально. Этим достигается одинаковый рендер страницы. Для примера, шрифты рендерятся по разному в зависимости от ОС.

Описываем в файлах:

Тест-кейсы и вызов API Playwright в ComponentName.e2e.tsx (например, Accordion.e2e.tsx)
Примеры компонента в ComponentName.e2e-playground.tsx (например, Accordion.e2e-playground.tsx)
Выносим в отдельный файл из-за особенностей Playwright.

Ссылки по теме:
- Why can't I pass a variable to mount?
- playwright issue #18481

Настраиваем:

В папке packages/vkui/src/testing/e2e задаём кастомные свойства, создаём утилитарные функции уменьшающие бойлерплейт. Вот основные помощники:
- constants.ts – стоит обратить внимание на TEST_CLASS_NAMES (ищи примеры использования в коде).
- ComponentPlayground – помогает создавать песочницу компонентов с разными вариациями его параметров.
- screenshotWithClipToContent – обрезает скриншот до контентной части.
  Напрямую её использовать не придётся. Она используется в expectScreenshotClippedToContent(), которая доступна через аргументы test.
```
test("base", ({ expectScreenshotClippedToContent }) => {
  // ...
  await expectScreenshotClippedToContent();
});
```
В папке packages/vkui/playwright подключаем шрифты, подключаем CSS, подготавливаем HTML файл.
В файле packages/vkui/playwright-сt.config.ts конфигурируем Playwright.
В файле env.development.local определяем переменные окружения для удобства локального тестирования.

Как формируются названия скриншотов?

За это отвечает функцию generateCustomScreenshotName, которая используется внутри expectScreenshotClippedToContent().

Далее примеры того как отработает функция. Как входные данные возьмём:

platform: 'android'
browserName: 'chromium'
colorScheme: 'light'

test("Example", async ({ expectScreenshotClippedToContent }) => {
  // ...
  await expectScreenshotClippedToContent(); // => мы получим скриншот с названием 'example-android-chromium-light-1-snap.webp'
  await expectScreenshotClippedToContent(); // => мы получим скриншот с названием 'example-android-chromium-light-2-snap.webp'
});

test.describe("Example", () => {
  test("My AWESOME case description", async ({
    expectScreenshotClippedToContent,
  }) => {
    // ...
    await expectScreenshotClippedToContent(); // => мы получим скриншот с названием 'example-android-chromium-light-my-awesome-case-description-1-snap.webp'
  });
});

Запускаем тесты только для конкретных платформ

Используем test.use({ onlyForPlatforms: [] }), которая через test.skip будет пропускать тест если платформа platform не удовлетворяет условию.
Если в тестовом файле есть другие тесты, то оборачиваем в test.describe, иначе test.use будет применять и на них.

Пример

// Accordion.e2e.tsx
import { test } from '@vkui-e2e/test';
import { AccordionPlayground } from './Accordion.e2e-playground';

test.describe(() => {
  // Будет применяться для всех тестов внутри `test.describe('Accordion')`
  test.use({ onlyForPlatforms: ['vkcom'] });
  test('Accordion', async ({ mount expectScreenshotClippedToContent componentPlaygroundProps }) => {
    await mount(<AccordionPlayground {...componentPlaygroundProps} />);
    await expectScreenshotClippedToContent();
  });
});

// На эти тесты не влияет
test('Accordion', () => {});
test.describe(() => {
  test('Accordion', () => {});
});

Зашиваем параметры адаптивности

Используем test.use({ adaptivityProviderProps: {} });
Если в тестовом файле есть другие тесты, то оборачиваем в test.describe, иначе test.use будет применять и на них.

Пример

// Accordion.e2e.tsx
import { test } from '@vkui-e2e/test';
import { ViewWidth } from '../../lib/adaptivity';
import { AccordionPlayground } from './Accordion.e2e-playground';

test.describe(() => {
  // Будет применяться для всех тестов внутри `test.describe('Accordion')`
  test.use({ adaptivityProviderProps: { viewWidth: ViewWidth.TABLET } });
  test('Accordion', async ({ mount expectScreenshotClippedToContent componentPlaygroundProps }) => {
    await mount(<AccordionPlayground {...componentPlaygroundProps} />);
    await expectScreenshotClippedToContent();
  });
});

// На эти тесты не влияет
test('Accordion', () => {});
test.describe(() => {
  test('Accordion', () => {});
});

Debug

Для начала надо будет скачать браузеры, делаем это следующей командой:

node --run playwright:install

Далее копируем .env.development.local файл:

cp packages/vkui/.env.development.local packages/vkui/.env

И читаем комментарии к константам в файле .env. Там будут сразу примеры.

Live Debugging

В .env задаём желаемый проект и тест файл.
Запускаем команду
```
node --run test:e2e:ci -- --debug
```
Запустится Playwright DevTools и указанный браузер.

Подробнее см. https://playwright.dev/docs/debug#live-debugging

Troubleshooting

Q) Почему при запуске `test:e2e`/`test:e2e-update` падает команда `playwright test --config ...`?

В первую очередь смотрим лог ошибки. Если команда падает не успев пройтись по тест файлу, то скорей всего дело может быть в кэше Playwright.

Например, был вот такой кейс, что в файле Accordion.e2e-playground.tsx переименовали экспортируемый компонент с AccordionE2EPlayground на AccordionPlayground и команда упала со следующей ошибкой:

vkui-package_vkui-1  | $ playwright test --config playwright-ct.config.ts -u
vkui-package_vkui-1  |
vkui-package_vkui-1  | Running 10 tests using 2 workers
vkui-package_vkui-1  |
vkui-package_vkui-1  | vite v4.2.1 building for production...
vkui-package_vkui-1  | transforming...
vkui-package_vkui-1  | Error when using sourcemap for reporting an error: Can't resolve original location of error.
vkui-package_vkui-1  | ✓ 2616 modules transformed.
vkui-package_vkui-1  | ✓ built in 3.67s
vkui-package_vkui-1  | "AccordionE2EPlayground" is not exported by "src/components/Accordion/Accordion.e2e-playground.tsx", imported by "playwright/index.tsx".

Очистили кэш, запустили заново тесты и ошибка пропала.

Чтобы очистить кэш выполните:

yarn workspace @vkontakte/vkui run docker:clear-playwright-cache

Покрытие

Чтобы сгенерировать карту покрытия для coverage/lcov/index.html:

Note: карта покрытия будет создана только для пакета @vkontakte/vkui

node --run test:ci && node --run test:coverage