feat(allure): screen diff block from allure 2 (#3573)

Co-authored-by: Michael Bodnarchuk <[email protected]>

Author: EgorBodnar

docs/plugins.md

@@ -7,11 +7,72 @@ title: Plugins
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+## addAttachment
+
+Add an attachment to the current test case
+
+### Parameters
+
+-   `name` **[string][1]** Name of the attachment
+-   `buffer` **[Buffer][2]** Buffer of the attachment
+-   `type` **[string][1]** MIME type of the attachment
+
+## addLabel
+
+Adds a label with the given name and value to the current test in the Allure report
+
+### Parameters
+
+-   `name` **[string][1]** name of the label to add
+-   `value` **[string][1]** value of the label to add
+
+## addParameter
+
+Adds a parameter with the given kind, name, and value to the current test in the Allure report
+
+### Parameters
+
+-   `kind` **[string][1]** kind of the parameter to add
+-   `name` **[string][1]** name of the parameter to add
+-   `value` **[string][1]** value of the parameter to add
+
+## addScreenDiff
+
+Add a special screen diff block to the current test case
+
+### Parameters
+
+-   `name` **[string][1]** Name of the screen diff block
+-   `expectedImg` **[string][1]** string representing the contents of the expected image file encoded in base64
+-   `actualImg` **[string][1]** string representing the contents of the actual image file encoded in base64
+-   `diffImg` **[string][1]** string representing the contents of the diff image file encoded in base64.
+    Could be generated by image comparison lib like "pixelmatch" or alternative
+
+## createStep
+
+A method for creating a step in a test case.
+
+### Parameters
+
+-   `name` **[string][1]** The name of the step.
+-   `stepFunc` **[Function][3]** The function that should be executed for this step. (optional, default `()=>{}`)
+
+Returns **any** The result of the step function.
+
+## setDescription
+
+Set description for the current test case
+
+### Parameters
+
+-   `description` **[string][1]** Description for the test case
+-   `type` **[string][1]** MIME type of the description (optional, default `'text/plain'`)
+
 ## allure
 
 Allure reporter
 
-![][1]
+![][4]
 
 Enables Allure reporter.
 
@@ -43,7 +104,7 @@ Launch Allure server and see the report like on a screenshot above:
 -   `outputDir` - a directory where allure reports should be stored. Standard output directory is set by default.
 -   `enableScreenshotDiffPlugin` - a boolean flag for add screenshot diff to report.
      To attach, tou need to attach three files to the report - "diff.png", "actual.png", "expected.png".
-     See [Allure Screenshot Plugin][2]
+     See [Allure Screenshot Plugin][5]
 
 #### Public API
 
@@ -71,7 +132,20 @@ const allure = codeceptjs.container.plugins('allure');
     });
 ```
 
-![Created Step Image][3]
+![Created Step Image][6]
+
+-   `addScreenDiff(name, expectedImg, actualImg, diffImg)` - add a special screen diff block to the current test case
+    image must be a string representing the contents of the expected image file encoded in base64
+    Example of usage:
+
+```js
+const expectedImg = fs.readFileSync('expectedImg.png', { encoding: 'base64' });
+...
+allure.addScreenDiff('Screen Diff', expectedImg, actualImg, diffImg);
+```
+
+![Overlay][7]
+![Diff][8]
 
 -   `severity(value)` - adds severity label
 -   `epic(value)` - adds epic label
@@ -84,6 +158,16 @@ const allure = codeceptjs.container.plugins('allure');
 
 -   `config`  
 
+## allure
+
+Creates an instance of the allure reporter
+
+### Parameters
+
+-   `config` **Config** Configuration for the allure reporter (optional, default `{outputDir:global.output_dir}`)
+
+Returns **[Object][9]** Instance of the allure reporter
+
 ## autoDelay
 
 Sometimes it takes some time for a page to respond to user's actions.
@@ -449,7 +533,7 @@ Possible config options:
 
 ## customLocator
 
-Creates a [custom locator][4] by using special attributes in HTML.
+Creates a [custom locator][10] by using special attributes in HTML.
 
 If you have a convention to use `data-test-id` or `data-qa` attributes to mark active elements for e2e tests,
 you can enable this plugin to simplify matching elements with these attributes:
@@ -599,9 +683,9 @@ This method works with WebDriver, Playwright, Puppeteer, Appium helpers.
 Function parameter `el` represents a matched element.
 Depending on a helper API of `el` can be different. Refer to API of corresponding browser testing engine for a complete API list:
 
--   [Playwright ElementHandle][5]
--   [Puppeteer][6]
--   [webdriverio element][7]
+-   [Playwright ElementHandle][11]
+-   [Puppeteer][12]
+-   [webdriverio element][13]
 
 #### Configuration
 
@@ -615,17 +699,17 @@ const eachElement = codeceptjs.container.plugins('eachElement');
 
 ### Parameters
 
--   `purpose` **[string][8]** 
+-   `purpose` **[string][1]** 
 -   `locator` **CodeceptJS.LocatorOrString** 
--   `fn` **[Function][9]** 
+-   `fn` **[Function][3]** 
 
-Returns **([Promise][10]&lt;any> | [undefined][11])** 
+Returns **([Promise][14]&lt;any> | [undefined][15])** 
 
 ## fakerTransform
 
-Use the [faker.js][12] package to generate fake data inside examples on your gherkin tests
+Use the [faker.js][16] package to generate fake data inside examples on your gherkin tests
 
-![Faker.js][13]
+![Faker.js][17]
 
 #### Usage
 
@@ -663,7 +747,7 @@ Scenario Outline: ...
 
 ## pauseOnFail
 
-Automatically launches [interactive pause][14] when a test fails.
+Automatically launches [interactive pause][18] when a test fails.
 
 Useful for debugging flaky tests on local environment.
 Add this plugin to config file:
@@ -679,6 +763,20 @@ Enable it manually on each run via `-p` option:
 
     npx codeceptjs run -p pauseOnFail
 
+## reporter
+
+Type: Allure
+
+### pendingCase
+
+Mark a test case as pending
+
+#### Parameters
+
+-   `testName` **[string][1]** Name of the test case
+-   `timestamp` **[number][19]** Timestamp of the test case
+-   `opts` **[Object][9]** Options for the test case (optional, default `{}`)
+
 ## retryFailedStep
 
 Retries each failed step in a test.
@@ -846,14 +944,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][15] plugin automatically starts browsers and video recording.
+[Selenoid][20] plugin automatically starts browsers and video recording.
 Works with WebDriver helper.
 
 ### Prerequisite
 
 This plugin **requires Docker** to be installed.
 
-> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][16] tool from Selenoid
+> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][21] tool from Selenoid
 
 ### Usage
 
@@ -882,7 +980,7 @@ plugins: {
   }
 ```
 
-When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][17] and start Selenoid automatically.
+When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][22] and start Selenoid automatically.
 It will also create `browsers.json` file required by Selenoid.
 
 In automatic mode the latest version of browser will be used for tests. It is recommended to specify exact version of each browser inside `browsers.json` file.
@@ -894,10 +992,10 @@ In automatic mode the latest version of browser will be used for tests. It is re
 While this plugin can create containers for you for better control it is recommended to create and launch containers manually.
 This is especially useful for Continous Integration server as you can configure scaling for Selenoid containers.
 
-> Use [Selenoid Configuration Manager][16] to create and start containers semi-automatically.
+> Use [Selenoid Configuration Manager][21] to create and start containers semi-automatically.
 
 1.  Create `browsers.json` file in the same directory `codecept.conf.js` is located
-    [Refer to Selenoid documentation][18] to know more about browsers.json.
+    [Refer to Selenoid documentation][23] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -922,7 +1020,7 @@ _Sample browsers.json_
 
 2.  Create Selenoid container
 
-Run the following command to create a container. To know more [refer here][19]
+Run the following command to create a container. To know more [refer here][24]
 
 ```bash
 docker create                                    \
@@ -955,15 +1053,15 @@ When `allure` plugin is enabled a video is attached to report automatically.
 | enableVideo      | Enable video recording and use `video` folder of output (default: false)       |
 | enableLog        | Enable log recording and use `logs` folder of output (default: false)          |
 | deletePassed     | Delete video and logs of passed tests (default : true)                         |
-| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][20] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][25] to know more   |
 
 ### Parameters
 
 -   `config`  
 
 ## stepByStepReport
 
-![step-by-step-report][21]
+![step-by-step-report][26]
 
 Generates step by step report for a test.
 After each step in a test a screenshot is created. After test executed screenshots are combined into slideshow.
@@ -1144,7 +1242,7 @@ This plugin allows to run webdriverio services like:
 -   browserstack
 -   appium
 
-A complete list of all available services can be found on [webdriverio website][22].
+A complete list of all available services can be found on [webdriverio website][27].
 
 #### Setup
 
@@ -1156,7 +1254,7 @@ See examples below:
 
 #### Selenium Standalone Service
 
-Install `@wdio/selenium-standalone-service` package, as [described here][23].
+Install `@wdio/selenium-standalone-service` package, as [described here][28].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -1175,7 +1273,7 @@ Please note, this service can be used with Protractor helper as well!
 
 #### Sauce Service
 
-Install `@wdio/sauce-service` package, as [described here][24].
+Install `@wdio/sauce-service` package, as [described here][29].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -1205,50 +1303,60 @@ In the same manner additional services from webdriverio can be installed, enable
 
 -   `config`  
 
-[1]: https://user-images.githubusercontent.com/220264/45676511-8e052800-bb3a-11e8-8cbb-db5f73de2add.png
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[2]: https://nodejs.org/api/buffer.html
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[4]: https://user-images.githubusercontent.com/220264/45676511-8e052800-bb3a-11e8-8cbb-db5f73de2add.png
+
+[5]: https://github.com/allure-framework/allure2/blob/master/plugins/screen-diff-plugin/README.md
+
+[6]: https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png
 
-[2]: https://github.com/allure-framework/allure2/blob/master/plugins/screen-diff-plugin/README.md
+[7]: https://user-images.githubusercontent.com/63167966/215404458-9a325668-819e-4289-9b42-5807c49ebddb.png
 
-[3]: https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png
+[8]: https://user-images.githubusercontent.com/63167966/215404645-73b09da0-9e6d-4352-a123-80c22f7014cd.png
 
-[4]: https://codecept.io/locators#custom-locators
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[5]: https://playwright.dev/docs/api/class-elementhandle
+[10]: https://codecept.io/locators#custom-locators
 
-[6]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
+[11]: https://playwright.dev/docs/api/class-elementhandle
 
-[7]: https://webdriver.io/docs/api
+[12]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
 
-[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[13]: https://webdriver.io/docs/api
 
-[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
 
-[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
+[16]: https://www.npmjs.com/package/faker
 
-[12]: https://www.npmjs.com/package/faker
+[17]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
 
-[13]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
+[18]: /basics/#pause
 
-[14]: /basics/#pause
+[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[15]: https://aerokube.com/selenoid/
+[20]: https://aerokube.com/selenoid/
 
-[16]: https://aerokube.com/cm/latest/
+[21]: https://aerokube.com/cm/latest/
 
-[17]: https://hub.docker.com/u/selenoid
+[22]: https://hub.docker.com/u/selenoid
 
-[18]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[23]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[19]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[24]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[20]: https://docs.docker.com/engine/reference/commandline/create/
+[25]: https://docs.docker.com/engine/reference/commandline/create/
 
-[21]: https://codecept.io/img/codeceptjs-slideshow.gif
+[26]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[22]: https://webdriver.io
+[27]: https://webdriver.io
 
-[23]: https://webdriver.io/docs/selenium-standalone-service.html
+[28]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[24]: https://webdriver.io/docs/sauce-service.html
+[29]: https://webdriver.io/docs/sauce-service.html