codeceptjs 3.2.1 → 3.3.0-beta.2

package/docs/plugins.md

@@ -58,6 +58,21 @@ const allure = codeceptjs.container.plugins('allure');
 -   `addAttachment(name, buffer, type)` - add an attachment to current test / suite
 -   `addLabel(name, value)` - adds a label to current test
 -   `addParameter(kind, name, value)` - adds a parameter to current test
+-   `createStep(name, stepFunc)` - create a step, stepFunc could consist an attachment
+    Example of usage:
+
+```js
+    allure.createStep('New created step', () => {
+      allure.addAttachment(
+        'Request params',
+        '{"clientId":123, "name":"Tom", "age":29}',
+        'application/json'
+      );
+    });
+```
+
+![Created Step Image][3]
+
 -   `severity(value)` - adds severity label
 -   `epic(value)` - adds epic label
 -   `feature(value)` - adds feature label
@@ -127,7 +142,7 @@ If a session expires automatically logs in again.
 ```js
 // inside a test file
 // use login to inject auto-login function
-Before(login => {
+Before(({ login }) => {
    login('user'); // login using user session
 });
 
@@ -434,7 +449,7 @@ Possible config options:
 
 ## customLocator
 
-Creates a [custom locator][3] by using special attributes in HTML.
+Creates a [custom locator][4] 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:
@@ -501,11 +516,76 @@ I.click('=sign-up'); // matches => [data-qa=sign-up]
 
 -   `config`  
 
+## eachElement
+
+Provides `eachElement` global function to iterate over found elements to perform actions on them.
+
+`eachElement` takes following args:
+
+-   `purpose` - the goal of an action. A comment text that will be displayed in output.
+-   `locator` - a CSS/XPath locator to match elements
+-   `fn(element, index)` - **asynchronous** function which will be executed for each matched element.
+
+Example of usage:
+
+```js
+// this example works with Playwright and Puppeteer helper
+await eachElement('click all checkboxes', 'form input[type=checkbox]', async (el) => {
+  await el.click();
+});
+```
+
+Click odd elements:
+
+```js
+// this example works with Playwright and Puppeteer helper
+await eachElement('click odd buttons', '.button-select', async (el, index) => {
+  if (index % 2) await el.click();
+});
+```
+
+Check all elements for visibility:
+
+```js
+// this example works with Playwright and Puppeteer helper
+const assert = require('assert');
+await eachElement('check all items are visible', '.item', async (el) => {
+  assert(await el.isVisible());
+});
+```
+
+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]
+
+#### Configuration
+
+-   `registerGlobal` - to register `eachElement` function globally, true by default
+
+If `registerGlobal` is false you can use eachElement from the plugin:
+
+```js
+const eachElement = codeceptjs.container.plugins('eachElement');
+```
+
+### Parameters
+
+-   `purpose` **[string][8]** 
+-   `locator` **CodeceptJS.LocatorOrString** 
+-   `fn` **[Function][9]** 
+
+Returns **([Promise][10]<any> | [undefined][11])** 
+
 ## fakerTransform
 
-Use the [faker.js][4] package to generate fake data inside examples on your gherkin tests
+Use the [faker.js][12] package to generate fake data inside examples on your gherkin tests
 
-![Faker.js][5]
+![Faker.js][13]
 
 #### Usage
 
@@ -543,7 +623,7 @@ Scenario Outline: ...
 
 ## pauseOnFail
 
-Automatically launches [interactive pause][6] when a test fails.
+Automatically launches [interactive pause][14] when a test fails.
 
 Useful for debugging flaky tests on local environment.
 Add this plugin to config file:
@@ -726,14 +806,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][7] plugin automatically starts browsers and video recording.
+[Selenoid][15] 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][8] tool from Selenoid
+> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][16] tool from Selenoid
 
 ### Usage
 
@@ -762,7 +842,7 @@ plugins: {
   }
 ```
 
-When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][9] and start Selenoid automatically.
+When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][17] 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.
@@ -774,10 +854,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][8] to create and start containers semi-automatically.
+> Use [Selenoid Configuration Manager][16] 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][10] to know more about browsers.json.
+    [Refer to Selenoid documentation][18] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -802,7 +882,7 @@ _Sample browsers.json_
 
 2.  Create Selenoid container
 
-Run the following command to create a container. To know more [refer here][11]
+Run the following command to create a container. To know more [refer here][19]
 
 ```bash
 docker create                                    \
@@ -835,7 +915,7 @@ 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][12] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][20] to know more   |
 
 ### Parameters
 
@@ -843,7 +923,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 
 ## stepByStepReport
 
-![step-by-step-report][13]
+![step-by-step-report][21]
 
 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.
@@ -898,7 +978,7 @@ Run tests with plugin enabled:
 #### Configuration:
 
 -   `timeout` - global step timeout, default 150 seconds
--   `force` - whether to use timeouts set in plugin config to override step timeouts set in code with I.limitTime(x).action(...), default false
+-   `overrideStepLimits` - whether to use timeouts set in plugin config to override step timeouts set in code with I.limitTime(x).action(...), default false
 -   `noTimeoutSteps` - an array of steps with no timeout. Default:
 
     -   `amOnPage`
@@ -915,7 +995,7 @@ Run tests with plugin enabled:
 plugins: {
     stepTimeout: {
         enabled: true,
-        force: true,
+        overrideStepLimits: true,
         noTimeoutSteps: [
           'scroll*', // ignore all scroll steps
           /Cookie/, // ignore all steps with a Cookie in it (by regexp)
@@ -981,18 +1061,22 @@ Use this plugin if:
 
 #### Multiple Conditional Assertions
 
+````js
+Add assert requires first:
 ```js
+const assert = require('assert');
+````
+
+Then use the assert:
 const result1 = await tryTo(() => I.see('Hello, user'));
 const result2 = await tryTo(() => I.seeElement('.welcome'));
 assert.ok(result1 && result2, 'Assertions were not succesful');
-```
 
-##### Optional click
+    ##### Optional click
 
-```js
-I.amOnPage('/');
-tryTo(() => I.click('Agree', '.cookies'));
-```
+    ```js
+    I.amOnPage('/');
+    tryTo(() => I.click('Agree', '.cookies'));
 
 #### Configuration
 
@@ -1020,7 +1104,7 @@ This plugin allows to run webdriverio services like:
 -   browserstack
 -   appium
 
-A complete list of all available services can be found on [webdriverio website][14].
+A complete list of all available services can be found on [webdriverio website][22].
 
 #### Setup
 
@@ -1032,7 +1116,7 @@ See examples below:
 
 #### Selenium Standalone Service
 
-Install `@wdio/selenium-standalone-service` package, as [described here][15].
+Install `@wdio/selenium-standalone-service` package, as [described here][23].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -1051,7 +1135,7 @@ Please note, this service can be used with Protractor helper as well!
 
 #### Sauce Service
 
-Install `@wdio/sauce-service` package, as [described here][16].
+Install `@wdio/sauce-service` package, as [described here][24].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -1085,30 +1169,46 @@ In the same manner additional services from webdriverio can be installed, enable
 
 [2]: https://github.com/allure-framework/allure2/blob/master/plugins/screen-diff-plugin/README.md
 
-[3]: https://codecept.io/locators#custom-locators
+[3]: https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png
+
+[4]: https://codecept.io/locators#custom-locators
+
+[5]: https://playwright.dev/docs/api/class-elementhandle
+
+[6]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
+
+[7]: https://webdriver.io/docs/api
+
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
 
-[4]: https://www.npmjs.com/package/faker
+[12]: https://www.npmjs.com/package/faker
 
-[5]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
+[13]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
 
-[6]: /basics/#pause
+[14]: /basics/#pause
 
-[7]: https://aerokube.com/selenoid/
+[15]: https://aerokube.com/selenoid/
 
-[8]: https://aerokube.com/cm/latest/
+[16]: https://aerokube.com/cm/latest/
 
-[9]: https://hub.docker.com/u/selenoid
+[17]: https://hub.docker.com/u/selenoid
 
-[10]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[18]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[11]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[19]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[12]: https://docs.docker.com/engine/reference/commandline/create/
+[20]: https://docs.docker.com/engine/reference/commandline/create/
 
-[13]: https://codecept.io/img/codeceptjs-slideshow.gif
+[21]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[14]: https://webdriver.io
+[22]: https://webdriver.io
 
-[15]: https://webdriver.io/docs/selenium-standalone-service.html
+[23]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[16]: https://webdriver.io/docs/sauce-service.html
+[24]: https://webdriver.io/docs/sauce-service.html

package/docs/puppeteer.md

@@ -31,7 +31,7 @@ To start you need CodeceptJS with Puppeteer packages installed
 npm install codeceptjs puppeteer --save
 ```
 
-Or see [alternative installation options](http://codecept.io/installation/)
+Or see [alternative installation options](https://codecept.io/installation/)
 
 > If you already have CodeceptJS project, just install `puppeteer` package and enable a helper it in config.
 
@@ -80,7 +80,7 @@ By default it is set to `domcontentloaded` which waits for `DOMContentLoaded` ev
 When a test runs faster than application it is recommended to increase `waitForAction` config value.
 It will wait for a small amount of time (100ms) by default after each user action is taken.
 
-> ▶ More options are listed in [helper reference](http://codecept.io/helpers/Puppeteer/).
+> ▶ More options are listed in [helper reference](https://codecept.io/helpers/Puppeteer/).
 
 ## Writing Tests
 
@@ -105,12 +105,11 @@ Tests consist with a scenario of user's action taken on a page. The most widely
 * `see`, `dontSee` - to check for a text on a page
 * `seeElement`, `dontSeeElement` - to check for elements on a page
 
-> ℹ  All actions are listed in [Puppeteer helper reference](http://codecept.io/helpers/Puppeteer/).*
+> ℹ  All actions are listed in [Puppeteer helper reference](https://codecept.io/helpers/Puppeteer/).*
 
 All actions which interact with elements **support CSS and XPath locators**. Actions like `click` or `fillField` by locate elements by their name or value on a page:
 
 ```js
-
 // search for link or button
 I.click('Login');
 // locate field by its label
@@ -172,8 +171,10 @@ If you need to get element's value inside a test you can use `grab*` methods. Th
 ```js
 const assert = require('assert');
 Scenario('get value of current tasks', async ({ I }) => {
-  I.createTodo('do 1');
-  I.createTodo('do 2');
+  I.fillField('.todo', 'my first item');
+  I.pressKey('Enter')
+  I.fillField('.todo', 'my second item');
+  I.pressKey('Enter')
   let numTodos = await I.grabTextFrom('.todo-count strong');
   assert.equal(2, numTodos);
 });
@@ -185,20 +186,35 @@ In case some actions should be taken inside one element (a container or modal wi
 Please take a note that you can't use within inside another within in Puppeteer helper:
 
 ```js
-within('.todoapp', () => {
-  I.createTodo('my new item');
+await within('.todoapp', () => {
+  I.fillField('.todo', 'my new item');
+  I.pressKey('Enter')
   I.see('1 item left', '.todo-count');
   I.click('.todo-list input.toggle');
 });
 I.see('0 items left', '.todo-count');
 ```
 
-> [▶ Learn more about basic commands](/basics#writing-tests)
+### Each Element <Badge text="Since 3.3" type="warning"/>
+
+Usually, CodeceptJS performs an action on the first matched element. 
+In case you want to do an action on each element found, use the special function `eachElement` which comes from [eachElement](https://codecept.io/plugins/#eachelement) plugin. 
+
+`eachElement` function matches all elements by locator and performs a callback on each of those element. A callback function receives [ElementHandle instance](https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle) from Puppeteer API. `eachElement` may perform arbitrary actions on a page, so the first argument should by a description of the actions performed. This description will be used for logging purposes.
 
-CodeceptJS allows you to implement custom actions like `I.createTodo` or use **PageObjects**. Learn how to improve your tests in [PageObjects](http://codecept.io/pageobjects/) guide.
+Usage example
 
-> [▶ Demo project is available on GitHub](https://github.com/DavertMik/codeceptjs-todomvc-puppeteer)
+```js
+await eachElement(
+  'click all checkboxes', 
+  'input.custom-checkbox', 
+  async (el, index) => {
+    await el.click();
+  });
+);
+```
 
+> ℹ Learn more about [eachElement plugin](/plugins/#eachelement)
 
 ## Mocking Requests
 
@@ -297,4 +313,4 @@ async renderPageToPdf() {
 
 The same way you can also access `browser` object to implement more actions or handle events.
 
-> [▶ Learn more about Helpers](http://codecept.io/helpers/)
+> [▶ Learn more about Helpers](https://codecept.io/helpers/)

package/docs/quickstart.md

@@ -37,9 +37,6 @@ TestCafe provides cross-browser support without Selenium. TestCafe tests are fas
 
 # Quickstart
 
-> CodeceptJS supports various engines for running browser tests. By default we recommend using **Playwright** which is cross-browser and performant solution.
-
-
 
 Use [CodeceptJS all-in-one installer](https://github.com/codeceptjs/create-codeceptjs) to get CodeceptJS, a demo project, and Playwright.
 
@@ -47,6 +44,8 @@ Use [CodeceptJS all-in-one installer](https://github.com/codeceptjs/create-codec
 npx create-codeceptjs .
 ```
 
+If you prefer not to use Playwright see other [installation options](/installation/).
+
 ![Installation](/img/codeceptinstall.gif)
 
 > To install codeceptjs into a different folder, like `tests` use `npx create-codeceptjs tests`

package/docs/reports.md

@@ -141,11 +141,52 @@ npx codecepjs dry-run --debug
 
 > ℹ If you use custom JavaScript code inside tests, or rely on values from `grab*` commands, dry-run may produce error output.
 
+
+## Testomat.io
+
+[Testomat.io](https://testomat.io) is a modern test management tool focused on CodeceptJS and **created by CodeceptJS team**.
+Testomat.io is commercial SaaS service that can receive run reports from local runs or CI. Out of box Testomat.io supports parallel runs, uploading of screenshots and videos.
+
+![](https://user-images.githubusercontent.com/220264/151728836-b52d2b2b-56e1-4640-8d3a-b39de817b1fd.png)
+
+> 😻 **Testomat.io is free** for small teams, so you can use its reporting features with CodeceptJS.
+
+To receive run reports you should:
+
+* [Sign up](https://app.testomat.io/users/sign_up) at Testomat.io
+* Create a new "Classical" project (select "BDD" project if you use CodeceptJS in BDD mode)
+* Select "Import from Source Code"
+* Select "CodeceptJS" as testing framework and JavaScript or TypeScript as a language. If you use BDD select "Gherkin" as language.
+* Execute provided command in a terminal with your project. This will be "check-tests" or "check-cucmber" command. It scans all your test files and imports them into Testomat.io. This way all your e2e tests will be visible in one UI.
+* After tests are imported, go to Runs tab and select "Setup automated tests".
+* Follow the instructions:
+
+
+![image](https://user-images.githubusercontent.com/77803888/151834217-5da44d92-a59a-458d-8856-64ce61bf3a38.png)
+
+* You will need to install `@testomatio/reporter` package and enable it as a plugin in codeceptjs config:
+
+```js
+plugins: {
+  testomatio: {
+    enabled: true,
+    require: '@testomatio/reporter/lib/adapter/codecept',
+    apiKey: process.env.TESTOMATIO,
+  }
+}
+```
+
+* Run tests with `TESTOMATIO=` env variable and API key provided by Testomat.io
+* See the run report is created and updated in realtime.
+
+
+[Testomat.io](https://testomat.io) reporter works in the cloud, so it doesn't require you to install additional software. It can be integrated with your CI service to rerun only failed tests, launch new runs from UI, and send report notifications by email or in Slack, MS Teams, or create issue in Jira.
+
+
 ## Allure
 
-> ℹ  We recommend using Allure reports on CI. Allure is one of the best open-source reporters designed to collect and show test reports in nicest way.
 
-[Allure reporter](http://allure.qatools.ru/#) is a tool to store and display test reports.
+[Allure reporter](https://allure.qatools.ru/#) is a tool to store and display test reports.
 It provides nice web UI which contains all important information on test execution.
 CodeceptJS has built-in support for Allure reports. Inside reports you will have all steps, substeps and screenshots.
 
@@ -201,7 +242,7 @@ npx codeceptjs dry-run --debug -p allure
 
 ## ReportPortal
 
-Allure is a great reporting tool, however, if you are running tests on different machines it is hard to merge its XML result files to build a proper report. So, for enterprise grade reporting we recommend using [ReportPortal](https://reportportal.io).
+For enterprise grade we reporting we recommend using [ReportPortal](https://reportportal.io).
 
 ![](https://camo.githubusercontent.com/6550c0365f1d0ce1e29c53f1860b12957d1fc529/68747470733a2f2f692e6962622e636f2f516d353247306e2f53637265656e73686f742d323031392d30342d31312d61742d31352d35372d34302e706e67)
 

package/docs/testcafe.md

@@ -54,7 +54,7 @@ A first test should be created with `codeceptjs gt` command
 npx codeceptjs gt
 ```
 
-In the next example we will [TodoMVC application](http://todomvc.com/examples/angularjs/#/). So let's create a test which will fill in todo list:
+In the next example we will [TodoMVC application](https://todomvc.com/examples/angularjs/#/). So let's create a test which will fill in todo list:
 
 ```js
 Feature('TodoMVC');

package/docs/translation.md

@@ -38,7 +38,7 @@ This way tests can be written in native language while it is still JavaScript:
 
 ```js
 Сценарий('пробую написать реферат', (Я) => {
-    Я.на_странице('http://yandex.ru/referats');
+    Я.на_странице('https://yandex.ru/referats');
     Я.вижу("Написать реферат по");
     Я.выбираю_опцию('Психологии');
     Я.кликаю("Написать реферат");
@@ -57,7 +57,7 @@ To write your tests in portuguese you can enable the portuguese translation in c
 Now you can write test like this:
 
 ```js
-Scenario('Efetuar login', ({ Eu }) => {
+Cenário('Efetuar login', ({ Eu }) => {
     Eu.estouNaPagina('http://minhaAplicacao.com.br');
     Eu.preenchoOCampo("login", "usuario@minhaAplicacao.com.br");
     Eu.preenchoOCampo("senha", "123456");

package/docs/videos.md

@@ -7,7 +7,7 @@ editLink: false
 ---
 
 > Add your own videos to our [Wiki Page](https://github.com/codeceptjs/CodeceptJS/wiki/Videos)
-[![](http://i3.ytimg.com/vi/BRMWstiOTks/maxresdefault.jpg)](https://www.youtube.com/watch?v=BRMWstiOTks)
+[![](https://i3.ytimg.com/vi/BRMWstiOTks/maxresdefault.jpg)](https://www.youtube.com/watch?v=BRMWstiOTks)
 
 ## [An Introduction, Getting started and working with CodeceptJS & Puppeteer (EAWeekend)](https://www.youtube.com/watch?v=BRMWstiOTks)
 
@@ -15,7 +15,7 @@ editLink: false
 
 ## [Introductory Videos](https://www.youtube.com/watch?v=FPFG1rBNJ64&list=PLcFXthgti9Lt4SjSvL1ALDg6dOeTC0TvT)
 
-Free educational videos provided by our community member **[@ontytoom](http://github.com/ontytoom)**.
+Free educational videos provided by our community member **[@ontytoom](https://github.com/ontytoom)**.
 
 1. [Installation](https://www.youtube.com/watch?v=FPFG1rBNJ64)
 1. [Creating a Test](https://www.youtube.com/watch?v=mdQZjL3h9d0)

package/docs/visual.md

@@ -58,7 +58,7 @@ Base Image is compared with the screenshot image and test results are derived ba
 
 ### Example
 
-Lets consider visual testing for [CodeceptJS Home](http://codecept.io)
+Lets consider visual testing for [CodeceptJS Home](https://codecept.io)
 
 ```js
 Feature('To test screen comparison with resemble Js Example test');
@@ -183,7 +183,7 @@ The first time you run this test a new baseline will be created, and subsequent
 
 ### Example
 
-Lets consider visual testing for [CodeceptJS Home](http://codecept.io).
+Lets consider visual testing for [CodeceptJS Home](https://codecept.io).
 You can also find example repo here: https://github.com/PeterNgTr/codeceptjs-applitoolshelper
 
 ```js

package/docs/vue.md

@@ -111,7 +111,7 @@ If you agreed to create a demo component, you will also see `TestMe` component i
 * [Learn CodeceptJS basics](/basics)
 * [Learn how to write CodeceptJS tests with Puppeteer](/puppeteer)
 * [See full reference for CodeceptJS Puppeteer Helper](/helpers/Puppeteer)
-* Ask your questions in [Slack](http://bit.ly/chat-codeceptjs) & [Forum](https://codecept.discourse.group/)
+* Ask your questions in [Slack](https://bit.ly/chat-codeceptjs) & [Forum](https://codecept.discourse.group/)
 
 ## Enjoy testing!