From 41ac583ac1a378068ebe283de1b29ed9799d4e01 Mon Sep 17 00:00:00 2001 From: Rashid Ksirov Date: Wed, 28 Sep 2022 21:25:24 +0300 Subject: [PATCH] doc: rewrite english doc and add russian doc --- README.md | 65 +-------- docs/en/hermione-assert-view-extended.md | 171 +++++++++++++++++++++++ docs/ru/hermione-assert-view-extended.md | 171 +++++++++++++++++++++++ 3 files changed, 349 insertions(+), 58 deletions(-) create mode 100644 docs/en/hermione-assert-view-extended.md create mode 100644 docs/ru/hermione-assert-view-extended.md diff --git a/README.md b/README.md index 978f717..0ef3247 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,16 @@ # hermione-assert-view-extended -Hermione plugin for extend assertView command. Inspired [hermione-ignore](https://github.com/deemidroll/hermione-ignore). +_Inspired by [hermione-ignore](https://github.com/deemidroll/hermione-ignore)._ -## Install +The plugin for [hermione](https://github.com/gemini-testing/hermione). -``` -npm i -D hermione-assert-view-extended -``` +Use the `hermione-assert-view-extended` plugin to extend the capabilities of Hermione's `assertView` command. -## Usage +The plugin allows you to take screenshots with minimal irrelevant diffs. -Set options for the plugin in your hermione config: -```js -{ - hooks: { - beforeEach: function(name, selector, options) { - return this.browser.moveTo(0, 0); - }, - afterEach: function(name, selector, options) { - console.log(`Asserted view '${name}' for '${selector}' selector.`); - } - }, - globalStyles: { - animationDisabled: true, - redraw: true, - // Elements will be covered with black rect. - ignoreElements: [ - '.classname1' - ], - // Elements will be hidden with `opacity: 0`. - invisibleElements: [ - '.classname3' - ], - // Elements will be hidden with `display: none`. - hideElements: [ - '.classname2' - ], - customCSS: ` - body { - background-color: red; - } - ` - } -} -``` - -## Options - -| Option | Default | Description | -| --- | --- | --- | -| `hooks` | | Hermione commands which will be called before/after call assertView in `then()`. | -| `hooks.beforeEach` | | Hermione commands which will be called before call assertView and first inner execute. | -| `hooks.afterEach` | | Hermione commands which will be called after call assertView and last inner execute. | -| `globalStyles` | | CSS injection appended in `` before call assertView. It will be removed after call assertView. | -| `globalStyles.animationDisabled` | `false` | Disable CSS animation (`transition-duration: 0s`, `animation-duration: 0s`, etc.). | -| `globalStyles.redraw` | `false` | Bowser redraw page after apply styles. It will be `true`, if you set `redrawElements`. | -| `globalStyles.redrawMode` | `'medium'` | Bowser redraw page after apply styles.
| -| `globalStyles.redrawElements` | `['body']` | Elements will be redrawed. | -| `globalStyles.redrawTimeout` | | Timeout after redraw elements. | -| `globalStyles.ignoreElements` | | Elements will be covered with black rect. | -| `globalStyles.invisibleElements` | | Elements will be hidden with `opacity: 0`. | -| `globalStyles.hideElements` | | Elements will be hidden with `display: none`. | -| `globalStyles.customCSS` | | Custom styles. | +See full documentation in various languages here: +* [English](./docs/en/hermione-assert-view-extended.md) +* [Русский](./docs/ru/hermione-assert-view-extended.md) ## Licence diff --git a/docs/en/hermione-assert-view-extended.md b/docs/en/hermione-assert-view-extended.md new file mode 100644 index 0000000..74b570e --- /dev/null +++ b/docs/en/hermione-assert-view-extended.md @@ -0,0 +1,171 @@ +# hermione-assert-view-extended + +## Overview + +Use the `hermione-assert-view-extended` plugin to extend the capabilities of Hermione's `assertView` command. + +The plugin allows you to take screenshots with minimal irrelevant diffs. + +### What are irrelevant diffs? + +Often in tests, when taking screenshots and comparing them with benchmarks, diffs arise that are not related to the test. Diffs may appear due to the following reasons: + +* animation on the page: for example, the animation did not have time to end, and the test is already taking a screenshot and the result does not match the standard; the fact is that the animation can be carried out differently each time, taking a screenshot may occur with a slight delay relative to the previous time or vice versa earlier than the last time. all this is enough for the screenshots to show the difference from each other when comparing; + +* the presence of elements in the layout that fall into the screenshot, but do not relate to the test and are not controlled by it, and may be different at different times due to their implementation; + +* [anti-aliasing][anti-aliasing] artifacts that occur due to a combination of certain element colors and background color. + +The `hermione-assert-view-extended` plugin allows you to compensate to a large extent for the above disadvantages when properly configured. With it, you can disable animation, set which elements to ignore (they will be replaced with black rectangles), which elements to make invisible by setting them to zero opacity, or which elements to hide. You can also enable the application of your own CSS before taking a screenshot. + +### Why can't we just hide all the irrelevant elements? + +Why do we need 3 options for how to exclude an element from a screenshot? + +Because in some cases, removing an element from a page can lead to an undesirable change in the layout. That is, you will be testing essentially another page, and not the one that your user will actually see. + +### What else does the plugin allow? + +The plugin also allows you to specify the actions to be performed each time before taking a screenshot. Or actions to be performed after taking a screenshot. To do this, you need to specify handlers for _beforeach- and afterEach-_ hooks in the plugin settings. + +## Install + +```bash +npm install -D hermione-assert-view-extended +``` + +## Setup + +Add the plugin to the `plugins` section of the `hermione` config: + +```javascript +module.exports = { + plugins: { + 'hermione-assert-view-extended': { + hooks: { + beforeEach: function(name, selector, options) { + return this.browser.moveTo(0, 0); + }, + afterEach: function(name, selector, options) { + console.log(`Asserted view '${name}' for '${selector}' selector.`); + } + }, + globalStyles: { + animationDisabled: true, + redraw: true, + ignoreElements: [ // Page elements to be replaced with black rectangles + '.classname1' + ], + invisibleElements: [ // Page elements to be made completely transparent + '.classname3' + ], + hideElements: [ // Page elements to be hidden + '.classname2' + ], + customCSS: ` + body { + background-color: red; + } + ` + } + }, + + // other hermione plugins... + }, + + // other hermione settings... +}; +``` + +### Description of configuration parameters + +| **Parameter** | **Type** | **Default value** | **Description** | +| :--- | :---:| :---: | :--- | +| hooks | Object | `{ }` | Обработчики для хуков _beforeEach_ и _afterEach_, которые будут вызваны до и после снятия скриншота. | +| globalStyles | Object | `{ }` | Переопределение стилей для различных элементов. Накладывается перед снятием скриншота и снимается после снятия. | + +### hooks parameters + +| **Parameter** | **Type** | **Default value** | **Description** | +| :--- | :---:| :---: | :--- | +| beforeEach | Function | null | Функция-обработчик, которая будет выполняться _перед_ снятием каждого скриншота. | +| afterEach | Function | null | Функция-обработчик, которая будет выполняться _после_ снятия каждого скриншота. | + +### globalStyles parameters + +| **Parameter** | **Type** | **Default value** | **Description** | +| :--- | :---:| :---: | :--- | +| animationDisabled | Boolean | false | Отключить CSS-анимацию. | +| redraw | Boolean | false | Перерисовать страницу браузера после применения всех новых стилей. Также перерисовка произойдет принудительно, независимо от значения этого параметра, если задан список _redrawElements._ | +| redrawMode](#setup_redraw_mode) | String | 'medium' | Режим перерисовки: _soft, medium, hard._ См. подробности ниже. | +| redrawElements](#setup_redraw_elements) | Array | `['body']` | Элементы страницы, которые нужно перерисовывать. Если элементы заданы, то перерисовка произойдет даже, если параметр _redraw_ установлен в _false._ | +| redrawTimeout | Number | _N/A_ | Пауза, перед тем как перерисовать элементы страницы, в мс. | +| ignoreElements | Array | _N/A_ | Элементы страницы, которые будут заменены на черные прямоугольники. | +| invisibleElements | Array | _N/A_ | Элементы страницы, которые будут сделаны полностью прозрачными. | +| hideElements | Array | _N/A_ | Элементы страницы, которые будут спрятаны. | +| customCSS | String | _N/A_ | Собственные стили, которые будут применены перед снятием скриншота. | + +### animationDisabled + +The following set of styles is used to disable animation: + +```css + body, body *, body *:after, body *:before, + body[class], body[class] *, body[class] *:after, body[class] *:before { + -webkit-animation-duration: 0s !important; + -moz-animation-duration: 0s !important; + -ms-animation-duration: 0s !important; + animation-duration: 0s !important; + -webkit-transition-duration: 0s !important; + -moz-transition-duration: 0s !important; + -ms-transition-duration: 0s !important; + transition-duration: 0s !important; + -webkit-transition-delay: 0s !important; + -moz-transition-delay: 0s !important; + -ms-transition-delay: 0s !important; + transition-delay: 0s !important; + } +``` + +### redraw + +Enables forced redrawing of the browser page after applying all new styles. Also, the redrawing will be forced, regardless of the value of this parameter, if the `redrawElements` list is set. + +### redrawMode + +The redrawing mode can take the following values: + +* `soft` — redraw the page without reflowing using the `transform: translateZ(0)` style to all elements specified in the `redrawElements` list; +* `medium` — reflow the page and redraw it using the `opacity: 0` style to all elements specified in the `redrawElements` list; +* `hard` — reflow the page and redraw it using the `display: none` style to all elements specified in the `redrawElements` parameter. + +### redrawElements + +Page elements that need to be redrawn. If the elements are specified, the redrawing will occur even if the `redraw` parameter is set to `false`. By default, the array of elements contains `body`. + +### redrawTimeout + +The pause in milliseconds that the browser must endure before redrawing the page elements. + +### ignoreElements + +Page elements that will be replaced with black rectangles. The specified list of elements will be added to the `ignoreElements` list of Hermione's `assertView` command, every time a screenshot is taken. + +### invisibleElements + +Page elements that will be made completely transparent. To do this, the style `opacity: 0 !important` is applied to them. + +### hideElements + +Page elements to be hidden. To do this, the `display: none !important` style is applied to them. + +### customCSS + +You can set your own styles that will be applied before taking a screenshot. + +## Useful links + +* [hermione-assert-view-extended plugin sources][hermione-assert-view-extended] + +[hermione-assert-view-extended]: https://github.com/ruslanxdev/hermione-assert-view-extended +[anti-aliasing]: https://en.wikipedia.org/wiki/Spatial_anti-aliasing diff --git a/docs/ru/hermione-assert-view-extended.md b/docs/ru/hermione-assert-view-extended.md new file mode 100644 index 0000000..595c6a1 --- /dev/null +++ b/docs/ru/hermione-assert-view-extended.md @@ -0,0 +1,171 @@ +# hermione-assert-view-extended + +## Обзор + +Используйте плагин `hermione-assert-view-extended`, чтобы расширить возможности команды `assertView` гермионы. + +Плагин позволяет снимать скриншоты с минимальными нерелевантными диффами. + +### Что такое нерелевантные диффы? + +Нередко в тестах при снятии скриншотов и их сравнении с эталонами возникают диффы, которые не имеют отношения к тесту. Диффы могут появляться из-за следующих причин: + +* анимация на странице: например, анимация не успела закончиться, а тест уже делает скриншот и получившийся результат не совпадает с эталоном; дело в том, что анимация может каждый раз осуществляться по-разному, снятие скриншота может происходить с небольшой задержкой относительно предыдущего раза или наоборот раньше, чем в прошлый раз — всего этого достаточно, чтобы скриншоты показали отличие друг от друга при сравнении; + +* наличие элементов в верстке, которые попадают в скриншот, но не относятся к тесту и не контролируются им, и могут быть разными в разные моменты времени в силу своей реализации; + +* артефакты [анти-алиасинга][anti-aliasing], возникающие из-за сочетания определенных цветов элементов и цвета фона. + +Плагин `hermione-assert-view-extended` позволяет компенсировать в значительной степени вышеперечисленные недостатки при его правильной настройке. С помощью него вы можете отключить анимацию, задать какие элементы нужно игнорировать (они будут заменены на черные прямоугольники), какие элементы сделать невидимыми, установив им нулевую непрозрачность _(opacity)_, или какие элементы спрятать. Также вы можете включить применение своего собственного CSS перед тем как делать скриншот. + +### Почему нельзя просто спрятать все нерелевантные элементы? + +Зачем нужны 3 варианта как исключить элемент из скриншота? + +Потому что в некоторых случаях удаление элемента со страницы может приводить к нежелательному изменению верстки. То есть вы будете тестировать по сути _другую_ страницу, а не ту, которую на самом деле будет видеть ваш пользователь. + +### Что еще позволяет плагин? + +Ещё плагин позволяет вам задать действия, которые нужно выполнить каждый раз, перед тем как снять скриншот. Или действия, которые нужно выполнить после снятия скриншота. Для этого вам нужно указать обработчики для _beforeEach- и afterEach-_ хуков в настройках плагина. + +## Установка + +```bash +npm install -D hermione-assert-view-extended +``` + +## Настройка + +Необходимо подключить плагин в разделе `plugins` конфига `hermione`: + +```javascript +module.exports = { + plugins: { + 'hermione-assert-view-extended': { + hooks: { + beforeEach: function(name, selector, options) { + return this.browser.moveTo(0, 0); + }, + afterEach: function(name, selector, options) { + console.log(`Asserted view '${name}' for '${selector}' selector.`); + } + }, + globalStyles: { + animationDisabled: true, + redraw: true, + ignoreElements: [ // Элементы страницы, которые будут заменены на черные прямоугольники + '.classname1' + ], + invisibleElements: [ // Элементы страницы, которые будут сделаны полностью прозрачными + '.classname3' + ], + hideElements: [ // Элементы страницы, которые будут спрятаны + '.classname2' + ], + customCSS: ` + body { + background-color: red; + } + ` + } + }, + + // другие плагины гермионы... + }, + + // другие настройки гермионы... +}; +``` + +### Расшифровка параметров конфигурации + +| **Параметр** | **Тип** | **По умолчанию** | **Описание** | +| :--- | :---:| :---: | :--- | +| hooks | Object | `{ }` | Обработчики для хуков _beforeEach_ и _afterEach_, которые будут вызваны до и после снятия скриншота. | +| globalStyles | Object | `{ }` | Переопределение стилей для различных элементов. Накладывается перед снятием скриншота и снимается после снятия. | + +### Параметры hooks + +| **Параметр** | **Тип** | **По умолчанию** | **Описание** | +| :--- | :---:| :---: | :--- | +| beforeEach | Function | null | Функция-обработчик, которая будет выполняться _перед_ снятием каждого скриншота. | +| afterEach | Function | null | Функция-обработчик, которая будет выполняться _после_ снятия каждого скриншота. | + +### Параметры globalStyles + +| **Параметр** | **Тип** | **По умолчанию** | **Описание** | +| :--- | :---:| :---: | :--- | +| animationDisabled | Boolean | false | Отключить CSS-анимацию. | +| redraw | Boolean | false | Перерисовать страницу браузера после применения всех новых стилей. Также перерисовка произойдет принудительно, независимо от значения этого параметра, если задан список _redrawElements._ | +| redrawMode | String | 'medium' | Режим перерисовки: _soft, medium, hard._ См. подробности ниже. | +| redrawElements](#setup_redraw_elements) | Array | `['body']` | Элементы страницы, которые нужно перерисовывать. Если элементы заданы, то перерисовка произойдет даже, если параметр _redraw_ установлен в _false._ | +| redrawTimeout | Number | _N/A_ | Пауза, перед тем как перерисовать элементы страницы, в мс. | +| ignoreElements | Array | _N/A_ | Элементы страницы, которые будут заменены на черные прямоугольники. | +| invisibleElements | Array | _N/A_ | Элементы страницы, которые будут сделаны полностью прозрачными. | +| hideElements | Array | _N/A_ | Элементы страницы, которые будут спрятаны. | +| customCSS | String | _N/A_ | Собственные стили, которые будут применены перед снятием скриншота. | + +### animationDisabled + +Для отключения анимации применяется следующий набор стилей: + +```css + body, body *, body *:after, body *:before, + body[class], body[class] *, body[class] *:after, body[class] *:before { + -webkit-animation-duration: 0s !important; + -moz-animation-duration: 0s !important; + -ms-animation-duration: 0s !important; + animation-duration: 0s !important; + -webkit-transition-duration: 0s !important; + -moz-transition-duration: 0s !important; + -ms-transition-duration: 0s !important; + transition-duration: 0s !important; + -webkit-transition-delay: 0s !important; + -moz-transition-delay: 0s !important; + -ms-transition-delay: 0s !important; + transition-delay: 0s !important; + } +``` + +### redraw + +Включает принудительную перерисовку страницы браузера после применения всех новых стилей. Также перерисовка произойдет принудительно, независимо от значения этого параметра, если задан список `redrawElements`. + +### redrawMode + +Режим перерисовки может принимать следующие значения: + +* `soft` — перерисовать страницу без переформатирования с применением стиля `transform: translateZ(0)` ко всем элементам, заданным в параметре `redrawElements`; +* `medium` — переформатировать страницу и перерисовать её с применением стиля `opacity: 0` ко всем элементам, заданным в параметре `redrawElements`; +* `hard` — переформатировать страницу и перерисовать её с применением стиля `display: none` ко всем элементам, заданным в параметре `redrawElements`. + +### redrawElements + +Элементы страницы, которые нужно перерисовывать. Если элементы заданы, то перерисовка произойдет, даже если параметр `redraw` установлен в `false`. По умолчанию, массив элементов содержит `body`. + +### redrawTimeout + +Пауза в миллисекундах, которую должен выдержать браузер, перед тем как перерисовать элементы страницы. + +### ignoreElements + +Элементы страницы, которые будут заменены на черные прямоугольники. Указанный список элементов будет добавляться в список `ignoreElements` команды гермионы `assertView`, каждый раз как будет сниматься скриншот. + +### invisibleElements + +Элементы страницы, которые будут сделаны полностью прозрачными. Для этого к ним применяется стиль `opacity: 0 !important`. + +### hideElements + +Элементы страницы, которые будут спрятаны. Для этого к ним применяется стиль `display: none !important`. + +### customCSS + +Можно задать свои собственные стили, которые будут применены перед снятием скриншота. + +## Полезные ссылки + +* [Исходники плагина hermione-assert-view-extended][hermione-assert-view-extended] + +[hermione-assert-view-extended]: https://github.com/ruslanxdev/hermione-assert-view-extended +[anti-aliasing]: https://ru.wikipedia.org/wiki/Экранное_сглаживание