diff --git a/blog/storybook-testing.mdx b/blog/storybook-testing.mdx
new file mode 100644
index 0000000..213f920
--- /dev/null
+++ b/blog/storybook-testing.mdx
@@ -0,0 +1,30 @@
+---
+title: Screenshot testing with Storybook
+slug: screenshot-testing-with-storybook
+hide_table_of_contents: false
+date: 2024-09-26T13:00
+---
+
+Now, for automatic visual testing of your components, you only need Storybook with your components and the `@testplane/storybook` plugin. There’s no need to write any tests anymore.
+
+
+
+[Storybook][storybook] is a tool for developing user interfaces based on components. It allows developers to independently visualize components in various states in an isolated environment, separate from other components.
+This "showroom" is perfect for screenshot testing your components, as this isolated environment makes such tests significantly more stable and faster compared to e2e testing.
+
+With the [@testplane/storybook][testplane-storybook] plugin, you can automatically verify changes to your components using screenshot testing without writing a single line of test code.
+You just need to describe your component in `Storybook` and Testplane will automatically generate all necessary tests upon execution, run them in the required browsers and provide a visual report for updating screenshots.
+Additionally, if a [play function][play-function] has been declared for the components, Testplane will execute it before the test begins to set the component to the desired state.
+
+However, if these capabilities are not enough, you can directly describe a Testplane test in the story file, which will be executed as an additional test for the component.
+
+How to use it?
+
+Learn more about this in our documentation [Screenshot testing with Storybook][vt-story].
+Also you can try it yourself in our [example project][example] on GitHub with customized screenshot testing.
+
+[storybook]: https://storybook.js.org
+[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
+[play-function]: https://storybook.js.org/docs/writing-stories/play-function
+[vt-story]: ../../docs/v8/visual-testing/with-storybook
+[example]: https://github.com/gemini-testing/testplane/tree/master/examples/storybook-autoscreenshots
diff --git a/docs/plugins/testplane-storybook.mdx b/docs/plugins/testplane-storybook.mdx
new file mode 100644
index 0000000..53bfd0e
--- /dev/null
+++ b/docs/plugins/testplane-storybook.mdx
@@ -0,0 +1,202 @@
+import Admonition from "@theme/Admonition";
+
+# @testplane/storybook
+
+## Overview {#overview}
+
+Use the [@testplane/storybook][testplane-storybook] plugin to automatically check the changes in your Storybook components with screenshot testing without a single line of test code.
+
+This plugin adds:
+
+- automatic screenshot tests for storybook stories;
+- an ability to write Testplane tests for storybook stories right inside of the stories.
+
+## Installation {#install}
+
+```bash
+npm install @testplane/storybook --save-dev
+```
+
+## Setup {#setup}
+
+Storybook 6.4+ is required to use this plugin.
+
+### Storybook
+
+If you use `storybook@6`, you will need to enable [buildStoriesJson][build-stories] feature in your `storybook` config:
+
+```typescript tytle=".storybook/main.js"
+export default {
+ // ...
+ features: {
+ // ...
+ buildStoriesJson: true,
+ },
+};
+```
+
+You don't need to do this with storybook@7 or storybook@8.
+
+### Testplane
+
+Add `@testplane/storybook` plugin into your Testplane config:
+
+```typescript title=".testplane.conf.ts"
+export default {
+ plugins: {
+ "@testplane/storybook": {},
+
+ // other Testplane plugins...
+ },
+
+ // other Testplane settings...
+};
+```
+
+With this minimal config, you will be able to run `npx testplane --storybook` to autotest each storybook story with [Testplane assertView][assert-view] command. Testplane will open each story, wait for play function to finish (if defined), and then call `assertView` command. These tests would be generated in runtime.
+
+### Description of configuration parameters {#setup_description}
+
+
+
+
+ | **Parameter** |
+ **Type** |
+ **Default** |
+ **Description** |
+
+
+
+
+ | enabled |
+ `Boolean` |
+ true |
+ Enable / disable plugin. |
+
+
+ | storybookConfigDir |
+ `String` |
+ ".storybook" |
+ Path to the storybook configuration directory. |
+
+
+ | autoScreenshots |
+ `Boolean` |
+ true |
+ Enable / disable auto-screenshot tests |
+
+
+ | localport |
+ `Number` |
+ 6006 |
+ Port to launch storybook dev server on. |
+
+
+ | remoteStorybookUrl |
+ `String` |
+ "" |
+ URL of the remote Storybook. If specified, local storybook dev sever would not be launched. |
+
+
+ | browserIds |
+ `Array` |
+ [] |
+ Array of `browserId` to run storybook tests on. By default, all of browsers, specified in Testplane config would be used |
+
+
+
+
+
+ Storybook tests performance greatly depends on [Testplane testsPerSession][testsPerSession]
+ parameter, as these tests speeds up on reusing existing sessions, so setting values around 20+
+ is preferred. These tests ignore [Testplane isolation][isolation]. It would be turned off
+ unconditionally.
+
+
+## Advanced usage
+
+If you have `ts-node` in your project, you can write your Testplane tests right inside of storybook story files:
+
+
+ Storybook story files must have `.js` or `.ts` extension for this to work. Formats `jsx/tsx` are
+ not supported yet.
+
+
+```typescript title="stories/Primary.stories.ts"
+import type { StoryObj } from "@storybook/react";
+import type { WithTestplane } from "@testplane/storybook";
+
+export const Primary: WithTestplane = {
+ args: {
+ primary: true,
+ label: "Button",
+ },
+ testplane: {
+ "my test": async ({ browser, expect }) => {
+ const element = await browser.$(".storybook-button");
+
+ await expect(element).toHaveText("Button");
+ },
+ },
+};
+```
+
+You can also specify extra options in story default config:
+
+```typescript
+import type { WithTestplane } from "@testplane/storybook";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: WithTestplane> = {
+ title: "Example/Button",
+ component: Button,
+ testplane: {
+ skip: false, // if true, skips all Testplane tests from this story file
+ autoscreenshotSelector: ".my-selector", // Custom selector to auto-screenshot elements
+ browserIds: ["chrome"], // Testplane browsers to run tests from this story file
+ assertViewOpts: {
+ // override default assertView options for tests from this file
+ ignoreDiffPixelCount: 5,
+ },
+ },
+};
+
+export default meta;
+```
+
+If you decide to create separate config for storybook auto-tests (which is suggested), you need to specify config path via CLI option. For example:
+
+```bash
+npx testplane --storybook -c .testplane.storybook.conf.ts
+```
+
+This allows you to store references next to your story files:
+
+```typescript title=".testplane.conf.ts"
+import path from "path";
+import { getStoryFile } from "@testplane/storybook";
+
+export default {
+ screenshotsDir: test => {
+ const relativeStoryFilePath = getStoryFile(test);
+ const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);
+
+ return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
+ },
+ // other Testplane settings...
+};
+```
+
+In this example, screenshot references would be stored in `screens//` folder, next to each of your story files.
+
+## Useful links {#useful_links}
+
+- [@testplane/storybook plugin sources][testplane-storybook]
+- [assertView command][assert-view]
+
+[assert-view]: ../commands/browser/assertView.mdx
+[build-stories]: https://storybook.js.org/docs/6.4/configure/overview#feature-flags
+[isolation]: ../config/browsers.mdx#isolation
+[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
+[testplane]: https://github.com/gemini-testing/testplane
+[testsPerSession]: ../config/browsers.mdx#tests_per_session
diff --git a/docs/visual-testing/visual-testing-intro.mdx b/docs/visual-testing/visual-testing-intro.mdx
new file mode 100644
index 0000000..92e02c5
--- /dev/null
+++ b/docs/visual-testing/visual-testing-intro.mdx
@@ -0,0 +1,60 @@
+# Visual testing
+
+Visual testing is implemented in testplane, with which the user can check the visual changes of an individual component, a viewport or the entire page.
+We recommend using the [html-reporter][html-reporter] plugin, which provides a user-friendly UI for analyzing tests, saving/updating modified images and running tests.
+
+
+
+### Screenshot Comparison Features {#features}
+
+For screenshot checks, Testplane provides the `assertView` command, which allows you to take a screenshot of a specific element or the entire viewport.
+When the assertView command is invoked, it searches for the required element on the page with automatic waiting. By default, animations will be disabled on the page before taking a screenshot to eliminate potential instability in the test due to the changing state of the element.
+After taking a screenshot, the resulting image will be compared with the reference image. If the reference image does not exist yet, then it must be saved using the html reporter UI or the `--update-refs` CLI option.
+To compare images, we use our own library [looks-same][looks-same], which differs from competitors in high performance and accuracy of comparison.
+
+The following settings are taken into account during comparison:
+
+- the blinking cursor in text inputs is ignored by default;
+- elements specified in the comparison options are ignored in the image;
+- comparison accuracy settings (acceptable deviations) are considered;
+- anti-aliasing (the most common diffs in screenshots) accuracy settings for fonts are considered.
+
+### Usage {#usage}
+
+```typescript
+await browser.assertView(state, options);
+await browser.assertView(state, selector, options);
+await element.assertView(state, options);
+```
+
+The `assertView` command is available both in the browser context and in the context of the found element. The set of arguments is different in these cases:
+
+```typescript
+it("check search view", async ({ browser }) => {
+ // ...
+
+ // screenshot of the current browser viewport
+ await browser.assertView("viewport-screen");
+
+ // screenshot of a specific element on the page (call from the browser context)
+ await browser.assertView("any-state-name", ".DocSearch", opts);
+
+ const searchInput = await browser.$(".DocSearch");
+ await searchInput.click();
+
+ // taking screenshot of a previously found item (from the element context)
+ await searchInput.assertView("any-state-name");
+});
+```
+
+Read more about the capabilities of the `assertView' command in the relevant sections.
+
+### Useful links {#useful_links}
+
+- [browser.assertView command][browser-command]
+- [element.assertView command][element-command]
+
+[html-reporter]: ../../html-reporter/html-reporter-setup
+[looks-same]: https://github.com/gemini-testing/looks-same
+[browser-command]: https://testplane.io/docs/v8/commands/browser/assertView/
+[element-command]: https://testplane.io/docs/v8/commands/element/assertView/
diff --git a/docs/visual-testing/with-storybook.mdx b/docs/visual-testing/with-storybook.mdx
new file mode 100644
index 0000000..b2e7327
--- /dev/null
+++ b/docs/visual-testing/with-storybook.mdx
@@ -0,0 +1,209 @@
+import Admonition from "@theme/Admonition";
+
+# Screenshot testing with Storybook
+
+[Storybook][storybook] is a tool for developing user interfaces based on components. It allows developers to independently visualize components in various states in an isolated environment, separate from other components.
+This "showroom" is perfect for screenshot testing your components, as this isolated environment makes such tests significantly more stable and faster compared to e2e testing.
+
+With the [@testplane/storybook][testplane-storybook] plugin, you can automatically verify changes to your components using screenshot testing without writing a single line of test code.
+You just need to describe your component in `Storybook` and Testplane will automatically generate all necessary tests upon execution, run them in the required browsers and provide a visual report for updating screenshots.
+Additionally, if a [play function][play-function] has been declared for the components, Testplane will execute it before the test begins to set the component to the desired state.
+
+## How to use? {#how_to_use}
+
+### Step 1: Install dependencies
+
+If your project does not have a `Testplane` yet, then we recommend that you read the [quickstart][quickstart] section or run the command below in your project directory:
+
+```bash
+npm init testplane@latest
+```
+
+Install the plugin for `testplane`:
+
+```bash
+npm install @testplane/storybook --save-dev
+```
+
+### Step 2: Plugin configuration
+
+Minimal configuration is enough for the plugin to work — you just need to declare it in the `testplane` config without additional options:
+
+```typescript title=".testplane.conf.ts"
+export default {
+ plugins: {
+ "@testplane/storybook": {},
+
+ // other Testplane plugins...
+ },
+
+ // other Testplane settings...
+};
+```
+
+### Step 3: Run tests
+
+To run storybook tests, add the '--storybook` option. The '--update-refs` option allows you to save/update reference images via the CLI:
+
+```bash
+npx testplane --storybook --update-refs
+```
+
+Also using GUI mode from the [html-reporter][html-reporter], you can visually validate changes in screenshots, update them or restart tests:
+
+```bash
+npx testplane gui --storybook
+```
+
+If you use `storybook@6`, you will need to enable [buildStoriesJson][build-stories] feature in your `storybook` config:
+
+```typescript title=".storybook/main.js"
+export default {
+ // ...
+ features: {
+ // ...
+ buildStoriesJson: true,
+ },
+};
+```
+
+## Custom tests {#custom_tests}
+
+Here's the translation:
+
+Some components need to be brought to a specific state before taking a screenshot. For this purpose, Storybook has an entity called the [play function][play-function]. If it is defined, we will first execute all the actions from it, and only then take the screenshot.
+If you find Storybook's expressiveness lacking, you can describe a Testplane test directly within the story which will be executed as an additional test for the component.
+
+```typescript title="stories/Primary.stories.ts"
+import type { StoryObj } from "@storybook/react";
+import type { WithTestplane } from "@testplane/storybook";
+
+export const Primary: WithTestplane = {
+ args: {
+ primary: true,
+ label: "Button",
+ },
+ testplane: {
+ "my test": async ({ browser, expect }) => {
+ const element = await browser.$(".storybook-button");
+
+ await expect(element).toHaveText("Button");
+ },
+ },
+};
+```
+
+You can also add additional settings for the test:
+
+```typescript title="stories/Primary.stories.ts"
+import type { WithTestplane } from "@testplane/storybook";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: WithTestplane> = {
+ title: "Example/Button",
+ component: Button,
+ testplane: {
+ skip: false, // if true, skips all Testplane tests from this story file
+ autoscreenshotSelector: ".my-selector", // Custom selector to auto-screenshot elements
+ browserIds: ["chrome"], // Testplane browsers to run tests from this story file
+ assertViewOpts: {
+ // override default assertView options for tests from this file
+ ignoreDiffPixelCount: 5,
+ },
+ },
+};
+
+export default meta;
+```
+
+
+ Storybook story files must have `.js` or `.ts` extension for this to work. Formats `jsx/tsx` are
+ not supported yet.
+
+
+## Plugin configuration
+
+The plugin has a number of options for more flexible configuration. For example, to run tests on a Storybook published remotely on s3, the configuration will look as follows:
+
+```typescript title=".testplane.conf.ts"
+export default {
+ plugins: {
+ "@testplane/storybook": {
+ remoteStorybookUrl: "https://yastatic.net/s3/storybook/index.html",
+ },
+
+ // other Testplane plugins...
+ },
+
+ // other Testplane settings...
+};
+```
+
+The entire list of available options can be viewed on the [plugin page][plugin-link].
+
+## Additional settings {#extra_config}
+
+Other types of testing can already be configured in your project, which can be run using Testplane. In order not to mix entities, we recommend using a separate config for Storybook tests and specifying it when running tests.
+
+```bash
+npx testplane --storybook --config .testplane.storybook.conf.ts
+```
+
+A shortened version of the launch:
+
+```bash
+npx testplane --storybook -c .testplane.storybook.conf.ts
+```
+
+A separate config will allow you to describe storing screenshots of storybooks next to your story file:
+
+```typescript title=".testplane.storybook.conf.ts"
+import path from "path";
+import { getStoryFile } from "@testplane/storybook";
+
+export default {
+ screenshotsDir: test => {
+ const relativeStoryFilePath = getStoryFile(test);
+ const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);
+
+ return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
+ },
+ // other Testplane settings...
+};
+```
+
+In this example, screenshot references would be stored in `screens//` folder, next to each of your story files.
+
+## Optimization of test runs {#optimize_run}
+
+Storybook tests themselves are quite fast, because they do not need a complex environment, and only one component is rendered on the page.
+In the context of the browser, Storybook testing environments are created one time and reused from test to test. Therefore, for the maximum speed of passing the tests, we recommend setting the [testsPerSession][tests-per-session] option with a value of at least 20 (more is better) to reuse the browser session as long as possible:
+
+```typescript title=".testplane.storybook.conf.ts"
+export default {
+ testsPerSession: 40, // set value for all browsers
+
+ browsers: {
+ "chrome-desktop": {
+ testsPerSession: 50, // or set value for current browser
+ },
+ firefox: {
+ // ...
+ },
+ },
+
+ // other Testplane settings...
+};
+```
+
+Also, for storybook tests, the [isolation][isolation] option will be ignored, so as not to create an environment for each test (this does not affect the stability of the tests in any way).
+
+[build-stories]: https://storybook.js.org/docs/6.4/configure/overview#feature-flags
+[html-reporter]: ../../html-reporter/html-reporter-setup/
+[isolation]: ../../config/browsers/#isolation
+[play-function]: https://storybook.js.org/docs/writing-stories/play-function
+[plugin-link]: ../plugins/testplane-storybook.mdx
+[quickstart]: ../../quickstart
+[storybook]: https://storybook.js.org
+[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
+[tests-per-session]: ../../config/browsers/#tests_per_session
diff --git a/i18n/ru/docusaurus-plugin-content-blog/storybook-testing.mdx b/i18n/ru/docusaurus-plugin-content-blog/storybook-testing.mdx
new file mode 100644
index 0000000..cdf2a6c
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-blog/storybook-testing.mdx
@@ -0,0 +1,29 @@
+---
+title: Скриншотное тестирование со Storybook
+slug: screenshot-testing-with-storybook
+hide_table_of_contents: false
+date: 2024-09-26T13:00
+---
+
+Теперь для автоматического визуального тестирования ваших компонентов достаточно иметь Storybook с вашими компонентами и плагин `@testplane/storybook`. Больше не нужно писать тесты.
+
+
+
+[Storybook][storybook] - это инструмент для разработки пользовательских интерфейсов на основе компонентов. Он позволяет разработчикам независимо визуализировать компоненты в различных состояниях в изолированной от остальных компонентов среде.
+Такой "шоурум" идеально подходит для скриншотного тестирования ваших компонентов, т.к. за счет этой изолированной среды такие тесты получаются в разы стабильнее и быстрее, чем вариант с e2e.
+
+С помощью плагина [@testplane/storybook][testplane-storybook] предоставляется возможность автоматически проверять изменения ваших компонентов с помощью скриншотного тестирования без единой строчки кода теста.
+Вам достаточно описать ваш компонент в `Storybook`, а `testplane` при запуске автоматически сгенерит все необходимые тесты, прогонит их в нужных браузерах и предоставит визуальный отчет для обновления скриншотов.
+При этом, если для компонентов была задекларирована [play-функция][play-function], то `testplane` перед началом теста выполнит ее, чтобы привести компонент в нужное состояние.
+
+Но если и этих возможностей вам не хватит, то вы можете прямо в story-файле описать testplane-тест, который будет выполнен как дополнительный тест для компонента.
+
+Как это использовать?
+
+Узнайте больше об этом в нашей документации Скриншотное тестирование со Storybook.
+[Пример проекта][example] с настроенным скриншотным тестированием со Storybook можно посмотреть в нашем репозитории на GitHub.
+
+[storybook]: https://storybook.js.org
+[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
+[play-function]: https://storybook.js.org/docs/writing-stories/play-function
+[example]: https://github.com/gemini-testing/testplane/tree/master/examples/storybook-autoscreenshots
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current.json b/i18n/ru/docusaurus-plugin-content-docs/current.json
index e0b1c97..293a62c 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current.json
+++ b/i18n/ru/docusaurus-plugin-content-docs/current.json
@@ -11,6 +11,10 @@
"message": "HTML Отчет",
"description": "The label for category HTML Reporter in sidebar mainSidebar"
},
+ "sidebar.mainSidebar.category.Visual testing": {
+ "message": "Визуальное тестирование",
+ "description": "The label for category Visual testing in sidebar mainSidebar"
+ },
"sidebar.mainSidebar.category.Plugins": {
"message": "Плагины",
"description": "The label for category Plugins in sidebar mainSidebar"
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/plugins/testplane-storybook.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/plugins/testplane-storybook.mdx
new file mode 100644
index 0000000..5d9f187
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/plugins/testplane-storybook.mdx
@@ -0,0 +1,203 @@
+import Admonition from "@theme/Admonition";
+
+# @testplane/storybook
+
+## Обзор {#overview}
+
+Используйте плагин [@testplane/storybook][testplane-storybook] для автоматической проверки изменения ваших компонентов с помощью скриншотного тестирования без единой строчки кода теста.
+
+Этот плагин предоставляет:
+
+- автоматическую генерацию скриншотных проверок для ваших storybook-файлов;
+- возможность писать testplane-тесты прямо внутри ваших storybook-историй.
+
+## Установка {#install}
+
+```bash
+npm install @testplane/storybook --save-dev
+```
+
+## Настройка {#setup}
+
+Для плагина требуется Storybook версии 6.4+и выше.
+
+### Storybook
+
+Если используется `storybook@6`, то Вам необходимо включить опцию [buildStoriesJson][build-stories] в `storybook` конфиге:
+
+```typescript tytle=".storybook/main.js"
+export default {
+ // ...
+ features: {
+ // ...
+ buildStoriesJson: true,
+ },
+};
+```
+
+Этого не нужно делать для версий storybook@7 и выше.
+
+### Testplane
+
+Добавьте плагин `@testplane/storybook` в Ваш Testplane конфиг:
+
+```typescript title=".testplane.conf.ts"
+export default {
+ plugins: {
+ "@testplane/storybook": {},
+
+ // другие плагины Testplane...
+ },
+
+ // другие настройки Testplane...
+};
+```
+
+При такой минимальной конфигурации Вы уже сможете выполнить команду `npx testplane --storybook`, чтобы автоматически протестировать каждую историю в storybook с помощью команды [Testplane assertView][assert-view]. Testplane откроет каждую историю, подождет завершения функции play (если она определена), а затем вызовет команду `assertView` для компонента. Эти тесты будут сгенерированы в рантайме и не останутся на файловой системе после окончания тестов.
+
+### Расшифровка параметров конфигурации {#setup_description}
+
+
+
+
+ | **Параметр** |
+ **Тип** |
+ **По умолчанию** |
+ **Описание** |
+
+
+
+
+ | enabled |
+ `Boolean` |
+ true |
+ Включить / отключить плагин. |
+
+
+ | storybookConfigDir |
+ `String` |
+ ".storybook" |
+ Путь к директории конфигурационного файла Storybook. |
+
+
+ | autoScreenshots |
+ `Boolean` |
+ true |
+ Включить / отключить авто матическое скриншотное тестирование (будут выполняться только вручную описанные tetplane-тесты) |
+
+
+ | localport |
+ `Number` |
+ 6006 |
+ Порт для запуска dev-сервера Storybook. |
+
+
+ | remoteStorybookUrl |
+ `String` |
+ "" |
+ Урл удаленного Storybook. Если указан, то локальный dev-сервер Storybook не будет запущен. |
+
+
+ | browserIds |
+ `Array` |
+ [] |
+ Массив id браузеров, в которых будут запущены тесты. По умолчанию тесты будут запущены во всех браузерах, описанных в конфиге testplane |
+
+
+
+
+
+ Производительность тестов Storybook сильно зависит от параметра [Testplane
+ testsPerSession][testsPerSession], так как скорость этих тестов увеличивается при повторном
+ использовании существующих сессий. Поэтому рекомендуется устанавливать значения около 20 и
+ более. Такой тип тестов так же проигнорирует опцию [Testplane isolation][isolation]. Изоляция
+ будет отключена принудительно для оптимизации скорости прохождения тестов.
+
+
+## Продвинутое использование
+
+Если на Вашем проекте используется `ts-node`, то Вы можете писать testplane-тесты прямо внутри истории:
+
+
+ Для примеров ниже файлы Storybook историй должны иметь расширение `.js` или `.ts`. Форматы
+ jsx/tsx еще не поддержаны.
+
+
+```typescript title="stories/Primary.stories.ts"
+import type { StoryObj } from "@storybook/react";
+import type { WithTestplane } from "@testplane/storybook";
+
+export const Primary: WithTestplane = {
+ args: {
+ primary: true,
+ label: "Button",
+ },
+ testplane: {
+ "my test": async ({ browser, expect }) => {
+ const element = await browser.$(".storybook-button");
+
+ await expect(element).toHaveText("Button");
+ },
+ },
+};
+```
+
+Также Вы можете дополнительно установить набор опций в конфиге сторей по умолчанию:
+
+```typescript
+import type { WithTestplane } from "@testplane/storybook";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: WithTestplane> = {
+ title: "Example/Button",
+ component: Button,
+ testplane: {
+ skip: false, // если true, все testplane-тесты этого файла будут отключены
+ autoscreenshotSelector: ".my-selector", // переопределение селектора для скриншота (например, если нужно сделать скриншот не всего элемента)
+ browserIds: ["chrome"], // названия браузеров testplane, в которых нужно запустить тест
+ assertViewOpts: {
+ // секция для переопределения опций команды assertView для конкретного файла
+ ignoreDiffPixelCount: 5,
+ },
+ },
+};
+
+export default meta;
+```
+
+В Вашем проекте уже могут быть настроены другие типы тестирования, запускающиеся с помощью `testplane`. Чтобы не смешивать сущности, мы рекомендуем для storybook описать отдельный конфиг, а при запуске указывать путь к нему с помощью CLI-опции. Например:
+
+```bash
+npx testplane --storybook -c .testplane.storybook.conf.ts
+```
+
+В отдельном конфиге Вы сможете, например, переопределить путь к скриншотам тестов:
+
+```typescript title=".testplane.conf.ts"
+import path from "path";
+import { getStoryFile } from "@testplane/storybook";
+
+export default {
+ screenshotsDir: test => {
+ const relativeStoryFilePath = getStoryFile(test);
+ const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);
+
+ return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
+ },
+ // другие настройки Testplane...
+};
+```
+
+В примере выше эталонные скриншоты будут сохраняться по пути `screens//` рядом с Вашими файлами историй.
+
+## Полезные ссылки {#useful_links}
+
+- [исходники плагина @testplane/storybook][testplane-storybook]
+- [команда assertView][assert-view]
+
+[assert-view]: ../commands/browser/assertView.mdx
+[build-stories]: https://storybook.js.org/docs/6.4/configure/overview#feature-flags
+[isolation]: ../config/browsers.mdx#isolation
+[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
+[testplane]: https://github.com/gemini-testing/testplane
+[testsPerSession]: ../config/browsers.mdx#tests_per_session
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/visual-testing/visual-testing-intro.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/visual-testing/visual-testing-intro.mdx
new file mode 100644
index 0000000..f0d1d9a
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/visual-testing/visual-testing-intro.mdx
@@ -0,0 +1,60 @@
+# Визуальное тестирование
+
+В testplane реализовано визуальное тестирование, с помощью которого пользователь может проверить визуальные изменения отдельного компонента, вьюпорта или всей страницы целиком.
+Для анализа тестов, сохранения/обновления измененных изображений и запуска тестов рекомендуется использовать плагин [html-reporter][html-reporter], который предоставляет удобный UI для всех действий.
+
+
+
+### Особенности сравнения скриншотов
+
+Для скринштных проверок Testplane предоставляет команду `assertView`, которая позволяет сделать скриншот конкретного элемента или всего вьюпорта.
+При вызове команды `assertView` осуществляется поиск нужного элемента на странице с его автоматическим ожиданием. По умолчанию перед снятием скриншота на странице будет отключена анимация, чтобы исключить в будущем нестабильность теста из-за изменяющегося состояния элемента.
+После снятия скриншота будет произведено сравнение полученного изображения с эталонным. Если эталонного изображения еще не существует, то его необходимо сохранить с помощью [UI html-reporter][html-reporter] или CLI-опции `--update-refs`.
+Для сравнения изображений используется собственная библиотека [looks-same][looks-same], которая отличается от конкурентов высокой производительностью и точностью сравнения.
+
+При сравнении учитываются следующие настройки:
+
+- мигающая каретка в текстовых инпутах игнорируется по умолчанию
+- на изображении игнорируются элементы, которые были указаны в опциях сравнения
+- учитываются настройки точности сравнения (допустимые отклонения)
+- учитываются настройки точности сравнения антиалиасинга для шрифтов (самый частый дифф на скриншотах)
+
+### Использование
+
+```typescript
+await browser.assertView(state, options);
+await browser.assertView(state, selector, options);
+await element.assertView(state, options);
+```
+
+Команда `assertView` доступна как в контексте браузера, так и в контексте найденного элемента. Набор аргументов при этом отличается:
+
+```typescript
+it("check search view", async ({ browser }) => {
+ // ...
+
+ // скриншот текущего вьюпорта браузера
+ await browser.assertView("viewport-screen");
+
+ // скриншот конкретного элемента на странице (вызов из контекста браузера)
+ await browser.assertView("any-state-name", ".DocSearch", opts);
+
+ const searchInput = await browser.$(".DocSearch");
+ await searchInput.click();
+
+ // скриншот элемента, который был найден в предыдущих шагах теста (вызов из контекста элемента)
+ await searchInput.assertView("any-state-name");
+});
+```
+
+Подробнее о возможностях команды `assertView` читайте в соответствующих разделах.
+
+### Связанные команды
+
+- [browser.assertView][browser-command]
+- [element.assertView][element-command]
+
+[html-reporter]: ../../html-reporter/html-reporter-setup
+[looks-same]: https://github.com/gemini-testing/looks-same
+[browser-command]: https://testplane.io/docs/v8/commands/browser/assertView/
+[element-command]: https://testplane.io/docs/v8/commands/element/assertView/
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/visual-testing/with-storybook.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/visual-testing/with-storybook.mdx
new file mode 100644
index 0000000..4340790
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/visual-testing/with-storybook.mdx
@@ -0,0 +1,206 @@
+import Admonition from "@theme/Admonition";
+
+# Скриншотное тестирование со Storybook
+
+[Storybook][storybook] — это инструмент для разработки пользовательских интерфейсов на основе компонентов. Он позволяет разработчикам независимо визуализировать компоненты в различных состояниях в изолированной от остальных компонентов среде.
+Такой "шоурум" идеально подходит для скриншотного тестирования ваших компонентов, т.к. за счет этой изолированной среды такие тесты получаются в разы стабильнее и быстрее, чем вариант с e2e.
+
+С помощью плагина [@testplane/storybook][testplane-storybook] предоставляется возможность автоматически проверять изменения ваших компонентов с помощью скриншотного тестирования.
+Вам достаточно описать ваш компонент в `Storybook`, а `testplane` при запуске автоматически сгенерит все необходимые тесты, прогонит их в нужных браузерах и предоставит визуальный отчет для обновления скриншотов.
+
+## Как использовать? {#how_to_use}
+
+### Шаг 1: Установка необходимых зависимостей
+
+Если в Вашем проекте еще нет `Testplane`, то рекомендуем ознакомиться с разделом [quickstart][quickstart] или выполнить в директории Вашего проекта команду ниже:
+
+```bash
+npm init testplane@latest
+```
+
+Устанавливаем плагин для `testplane`
+
+```bash
+npm install @testplane/storybook --save-dev
+```
+
+### Шаг 2: Настройка плагина
+
+Для работы плагина достаточно минимальной настройки — нужно просто объявить его в конфиге `testplane` без дополнительных опций:
+
+```typescript title=".testplane.conf.ts"
+export default {
+ plugins: {
+ "@testplane/storybook": {},
+
+ // other Testplane plugins...
+ },
+
+ // другие настройки Testplane...
+};
+```
+
+### Шаг 3: Запуск тестов
+
+Для запуска storybook-тестов необходимо добавить опцию `--storybook`. Опция `--update-refs` позволяет сохранить/обновить эталонные изображения через CLI:
+
+```bash
+npx testplane --storybook --update-refs
+```
+
+С помощью GUI-режима вы можете визуально оценить изменения в скриншотах, обновить их или перезапустить тесты:
+
+```bash
+npx testplane gui --storybook
+```
+
+Если в Вашем проекте используется Storybook версии 6.x, то в настройках Storybook необходимо включить сохранение json-файла с Вашими историями:
+
+```typescript title=".storybook/main.js"
+export default {
+ // ...
+ features: {
+ // ...
+ buildStoriesJson: true,
+ },
+};
+```
+
+## Кастомные тесты {#custom_tests}
+
+Некоторые компоненты перед скриншотом нужно привести в какое-либо состояние. Для этого у сторибука есть сущность под названием [play-функция][play-function]. Если она определена, мы сначала выполним все action-ы из нее, и только после этого сделаем скриншот.
+Если вам не хватает выразительности Storybook, то вы можете в самой истории описать testplane-тест, который будет выполнен как дополнительный тест для компонента.
+
+```typescript title="stories/Primary.stories.ts"
+import type { StoryObj } from "@storybook/react";
+import type { WithTestplane } from "@testplane/storybook";
+
+export const Primary: WithTestplane = {
+ args: {
+ primary: true,
+ label: "Button",
+ },
+ testplane: {
+ "my test": async ({ browser, expect }) => {
+ const element = await browser.$(".storybook-button");
+
+ await expect(element).toHaveText("Button");
+ },
+ },
+};
+```
+
+Также для теста можно добавить дополнительные настройки:
+
+```typescript title="stories/Primary.stories.ts"
+import type { WithTestplane } from "@testplane/storybook";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: WithTestplane> = {
+ title: "Example/Button",
+ component: Button,
+ testplane: {
+ skip: false, // if true, skips all Testplane tests from this story file
+ autoscreenshotSelector: ".my-selector", // Custom selector to auto-screenshot elements
+ browserIds: ["chrome"], // Testplane browsers to run tests from this story file
+ assertViewOpts: {
+ // override default assertView options for tests from this file
+ ignoreDiffPixelCount: 5,
+ },
+ },
+};
+
+export default meta;
+```
+
+
+ При добавлении testplane-тестов расширение Ваших story-файлов должно быть `.js` или `.ts`.
+ Форматы jsx/tsx еще не поддержаны.
+
+
+## Параметры конфигурации плагина
+
+Плагин имеет ряд опций для более гибкой настройки. Например, для запуска тестов на Storybook, опубликованном удаленно на `s3`, настройка будет выглядеть следующим образом:
+
+```typescript title=".testplane.conf.ts"
+export default {
+ plugins: {
+ "@testplane/storybook": {
+ remoteStorybookUrl: "https://yastatic.net/s3/storybook/index.html",
+ },
+
+ // other Testplane plugins...
+ },
+
+ // другие настройки Testplane...
+};
+```
+
+Весь список доступных опций можно посмотреть на [странице плагина][plugin-link].
+
+## Дополнительные настройки {#extra_config}
+
+В Вашем проекте уже могут быть настроены другие типы тестирования, запускающиеся с помощью `testplane`. Чтобы не смешивать сущности, мы рекомендуем для storybook-тестов использовать отдельный конфиг и указывать его при запуске тестов.
+
+```bash
+npx testplane --storybook --config .testplane.storybook.conf.ts
+```
+
+Сокращенная версия запуска:
+
+```bash
+npx testplane --storybook -c .testplane.storybook.conf.ts
+```
+
+Отдельный конфиг позволит Вам описать хранение скриншотов сторибуков рядом с Вашим story-файлом:
+
+```typescript title=".testplane.storybook.conf.ts"
+import path from "path";
+import { getStoryFile } from "@testplane/storybook";
+
+export default {
+ screenshotsDir: test => {
+ const relativeStoryFilePath = getStoryFile(test);
+ const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);
+
+ return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
+ },
+ // другие настройки Testplane...
+};
+```
+
+В данном примере эталонные скриншоты будут сохранены в директории `screens//` относительно директории Вашего story-файла.
+
+## Оптимизация запуска тестов {#optimize_run}
+
+Storybook-тесты сами по себе довольно быстрые, т.к. для них не нужно сложное окружение, а на странице рендерится только один компонент.
+В контексте браузера 1 раз создается окружения для тестирования Storybook и переиспользуется от теста к тесту. Поэтому, для максимальной скорости прохождения тестов мы рекомендуем выставлять опцию [testsPerSession][tests-per-session] со значением не меньше 20, чтобы переиспользовать браузерную сессию как можно дольше:
+
+```typescript title=".testplane.storybook.conf.ts"
+export default {
+ testsPerSession: 40, // можно установить количество тестов для сессии сразу для всех браузеров
+
+ browsers: {
+ "chrome-desktop": {
+ testsPerSession: 50, // или установить значение для конкретного браузера
+ },
+ firefox: {
+ // ...
+ },
+ },
+
+ // другие настройки Testplane...
+};
+```
+
+Также, для storybook-тестов будет проигнорирована опция [isolation][isolation], чтобы не пресоздавать окружение на каджый тест (это никак не влияет на стабильность тестов).
+
+[build-stories]: https://storybook.js.org/docs/6.4/configure/overview#feature-flags
+[html-reporter]: ../../html-reporter/html-reporter-setup/
+[isolation]: ../../config/browsers/#isolation
+[play-function]: https://storybook.js.org/docs/writing-stories/play-function
+[plugin-link]: ../plugins/testplane-storybook.mdx
+[quickstart]: ../../quickstart
+[storybook]: https://storybook.js.org
+[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
+[tests-per-session]: ../../config/browsers/#tests_per_session
diff --git a/sidebars.ts b/sidebars.ts
index 508caf2..9025fec 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -25,6 +25,12 @@ const sidebars: SidebarsConfig = {
items: [{ type: "autogenerated", dirName: "config" }],
link: { type: "doc", id: "config/main" },
},
+ {
+ type: "category",
+ label: "Visual testing",
+ items: [{ type: "autogenerated", dirName: "visual-testing" }],
+ link: { type: "doc", id: "visual-testing/visual-testing-intro" },
+ },
{
type: "category",
label: "Guides",
diff --git a/static/img/docs/html-reporter/html-reporter.overview.png b/static/img/docs/html-reporter/html-reporter.overview.png
index 9fe62b2..151b2b3 100644
Binary files a/static/img/docs/html-reporter/html-reporter.overview.png and b/static/img/docs/html-reporter/html-reporter.overview.png differ