Перейти к основному содержимому

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

storyshots легко интегрируется даже в уже написанные приложения благодаря своей архитектуре.

Установка и сборка​

примечание

На данный момент библиотека не публикуется ни в один из реестров пакетов, ввиду наличия не стабильной структуры пакетов. Компоненты устанавливаются из локальных артефактов, а не из публичного registry.

В корне проекта установить зависимости:

npm install

Собрать пакеты и запаковать в архив:

npm run build && npm run pack

Интеграция в проект​

По итогу будут сформированы артефакты .tar. Описание данных компонентов можно найти в разделах архитектура и модули.

подсказка

Для стандартного CSR проекта, использующего react, будет достаточен следующий набор:

  • @storyshots/core - ядро storyshots.
  • @storyshots/react - клиент preview react приложений.
  • @storyshots/exec-preview - сервер preview.

Данные модули необходимо разместить в папке проекта и поместить их под контроль VCS:

project/
├── src/
├── offline/
│   ├── @storyshots-core-0.0.18.tgz
│   ├── @storyshots-react-0.0.18.tgz
│   └── @storyshots-exec-preview-0.0.18.tgz
└── package.json

Далее зависимости необходимо зарегистрировать:

package.json
{
  "devDependencies": {
    "@storyshots/core": "file:offline/storyshots-core-0.0.18.tgz",
    "@storyshots/react": "file:offline/storyshots-react-0.0.18.tgz",
    "@storyshots/exec-preview": "file:offline/storyshots-exec-preview-0.0.18.tgz"
  }
}

И установить:

npm i

Описание превью​

примечание

Связанные со storyshots файлы в данном руководстве располагаются в src/storyshots (см. дислокация тестов).

После установки всё готово для описания клиента preview и первых историй. Начнём с preview:

/src/storyshots/preview/config.ts
import { createPreviewApp } from '@storyshots/react';

// Инициализация превью
export const { it, run } = createPreviewApp({
  /*
   Определение поведения "по умолчанию" для внешних зависимостей.
   В данном случае это методы BE API.
  */
  createExternals: (config) => ({
    getUser: async () => ({ id: 1, name: 'John Doe' }),
  }),
  // Маркировка методов для записи в журнал вызовов
  createJournalExternals: (externals, config) => ({
    getUser: config.journal.asRecordable('getUser', externals.getUser),
  }),
});

После, опишем первые истории:

/src/storyshots/stories/index.tsx
import { finder } from '@storyshots/core';

import { it } from '../preview/config';

export const stories = [
  it('renders the application correctly'),
  it('handles missing user gracefully', {
    // Модифицируем поведение сервера для данной истории
    arrange: (externals) => ({ ...externals, getUser: async () => null }),
  }),
  it('allows to login', {
    // Эмулируем действия на странице
    act: (actor) => actor.click(finder.getByRole('button', { name: 'Login' })),
  }),
];
подсказка

Истории можно декомпозировать.

После чего, запустим описанные истории реализовав render по умолчанию с внедрением зависимостей:

/src/storyshots/preview/index.tsx
import { map } from '@storyshots/core';

import { run } from './config';
import { stories } from '../stories';

run(
  map(stories, (story) => ({
    render: (externals) => (
      <Externals externals={externals}>
        <App />
      </Externals>
    ),
    ...story,
  })),
);

Описание менеджера​

Далее необходимо описать сервер preview:

/src/storyshots/manager/createAppServer.ts
import { createExecPreview } from '@storyshots/exec-preview';

export function createAppServer() {
  return createExecPreview({
    ui: {
      command: 'npx webpack-cli serve', // <- Скрипт запускающий приложение в dev режиме
      at: 'http://localhost:8080', // <- Адрес dev сервера
    },
    ci: {
      command: 'npx webpack-cli build', // <- Скрипт сборки артефакта
      serve: './dist', // <- Расположение артефакта сборки
    },
  });
}

Также необходимо настроить используемый сборщик (в данном примере используется webpack), указав верный entry:

webpack.config.ts
export default {
  entry:
    // process.env.STORYSHOTS выставляется @storyshots/exec-preview автоматически
    process.env.STORYSHOTS === 'true' // <- Выставляем entry до preview взависимости от режима сборки.
      ? './src/storyshots/preview/index.tsx'
      : './src/index.tsx',
  // ... ///
};
подсказка

Более подробно про @storyshots/exec-preview можно прочитать в данном разделе.

После описания сервера, нужно определить общую конфигурацию тестирования:

/src/storyshots/manager/config.ts
import { ManagerConfig } from '@storyshots/core/manager';

import { createAppServer } from './createAppServer';

export default {
  // Список тестируемых устройств
  devices: [
    {
      name: 'desktop',
      width: 1480,
      height: 920,
    },
  ],
  // Описание путей до основных артефактов: снимков и журналов
  paths: {
    screenshots: path.join(process.cwd(), 'screenshots'),
    records: path.join(process.cwd(), 'records'),
  },
  // Описание сервера превью
  preview: createAppServer(),
} satisfies ManagerConfig;
подсказка

Список всех доступных настроек доступен в данном разделе.

Далее UI режим запустить с помощью

storyshots --ui /src/storyshots/manager/config.ts
примечание

Для запуска всех тестов в фоновом режиме использовать:

storyshots /src/storyshots/manager/config.ts

Примеры​