implemented eachElement plugin (#3221)

Author: DavertMik

docs/playwright.md

@@ -175,8 +175,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);
 });
@@ -188,17 +190,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 Playwright 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"/>
 
-CodeceptJS allows you to implement custom actions like `I.createTodo` or use **PageObjects**. Learn how to improve your tests in [PageObjects](https://codecept.io/pageobjects/) guide.
+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://playwright.dev/docs/api/class-elementhandle) from Playwright 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.
+
+Usage example
+
+```js
+await eachElement(
+  'tick all checkboxes', 
+  'input.custom-checkbox', 
+  async (el, index) => {
+    await el.check();
+  });
+);
+```
+
+> ℹ Learn more about [eachElement plugin](/plugins/#eachelement)
 
 ## Multi Session Testing
 
@@ -307,19 +327,6 @@ Scenario('website looks nice on iPhone', () => {
 });
 ```
 
-## Configuring CI
-
-### GitHub Actions
-
-Playwright can be added to GitHub Actions using [official action](https://github.com/microsoft/playwright-github-action). Use it before starting CodeceptJS tests to install all dependencies. It is important to run tests in headless mode ([otherwise you will need to enable xvfb to emulate desktop](https://github.com/microsoft/playwright-github-action#run-in-headful-mode)).
-
-```yml
-# from workflows/tests.yml
-- uses: microsoft/playwright-github-action@v1
-- name: run CodeceptJS tests
-  run: npx codeceptjs run
-```
-
 ## Accessing Playwright API
 
 To get [Playwright API](https://playwright.dev/docs/api/class-playwright) inside a test use `I.usePlaywrightTo` method with a callback.
@@ -496,6 +503,7 @@ Open `index.html` in your browser to view the full interactive coverage report.
 ![](https://user-images.githubusercontent.com/16587779/131858993-87d1aafc-8ef1-4a82-867d-e64a13e36106.png)
 
 ![](https://user-images.githubusercontent.com/16587779/131859006-c6f17d18-c603-44a5-9d59-0670177276cf.png)
+
 ## Extending Helper
 
 To create custom `I.*` commands using Playwright API you need to create a custom helper.
@@ -538,3 +546,17 @@ async setPermissions() {
 > [▶ Learn more about BrowserContext](https://github.com/microsoft/playwright/blob/master/docs/src/api/class-browsercontext.md)
 
 > [▶ Learn more about Helpers](https://codecept.io/helpers/)
+
+
+## Configuring CI
+
+### GitHub Actions
+
+Playwright can be added to GitHub Actions using [official action](https://github.com/microsoft/playwright-github-action). Use it before starting CodeceptJS tests to install all dependencies. It is important to run tests in headless mode ([otherwise you will need to enable xvfb to emulate desktop](https://github.com/microsoft/playwright-github-action#run-in-headful-mode)).
+
+```yml
+# from workflows/tests.yml
+- uses: microsoft/playwright-github-action@v1
+- name: run CodeceptJS tests
+  run: npx codeceptjs run
+```

docs/plugins.md

@@ -501,11 +501,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][4]
+-   [Puppeteer][5]
+-   [webdriverio element][6]
+
+#### 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][7]** 
+-   `locator` **CodeceptJS.LocatorOrString** 
+-   `fn` **[Function][8]** 
+
+Returns **([Promise][9]<any> | [undefined][10])** 
+
 ## fakerTransform
 
-Use the [faker.js][4] package to generate fake data inside examples on your gherkin tests
+Use the [faker.js][11] package to generate fake data inside examples on your gherkin tests
 
-![Faker.js][5]
+![Faker.js][12]
 
 #### Usage
 
@@ -543,7 +608,7 @@ Scenario Outline: ...
 
 ## pauseOnFail
 
-Automatically launches [interactive pause][6] when a test fails.
+Automatically launches [interactive pause][13] when a test fails.
 
 Useful for debugging flaky tests on local environment.
 Add this plugin to config file:
@@ -726,14 +791,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][7] plugin automatically starts browsers and video recording.
+[Selenoid][14] 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][15] tool from Selenoid
 
 ### Usage
 
@@ -762,7 +827,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][16] 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 +839,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][15] 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][17] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -802,7 +867,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][18]
 
 ```bash
 docker create                                    \
@@ -835,15 +900,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][12] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][19] to know more   |
 
 ### Parameters
 
 -   `config`  
 
 ## stepByStepReport
 
-![step-by-step-report][13]
+![step-by-step-report][20]
 
 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.
@@ -1024,7 +1089,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][21].
 
 #### Setup
 
@@ -1036,7 +1101,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][22].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -1055,7 +1120,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][23].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -1091,28 +1156,42 @@ In the same manner additional services from webdriverio can be installed, enable
 
 [3]: https://codecept.io/locators#custom-locators
 
-[4]: https://www.npmjs.com/package/faker
+[4]: https://playwright.dev/docs/api/class-elementhandle
+
+[5]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
+
+[6]: https://webdriver.io/docs/api
+
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
+
+[11]: https://www.npmjs.com/package/faker
 
-[5]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
+[12]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
 
-[6]: /basics/#pause
+[13]: /basics/#pause
 
-[7]: https://aerokube.com/selenoid/
+[14]: https://aerokube.com/selenoid/
 
-[8]: https://aerokube.com/cm/latest/
+[15]: https://aerokube.com/cm/latest/
 
-[9]: https://hub.docker.com/u/selenoid
+[16]: https://hub.docker.com/u/selenoid
 
-[10]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[17]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[11]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[18]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[12]: https://docs.docker.com/engine/reference/commandline/create/
+[19]: https://docs.docker.com/engine/reference/commandline/create/
 
-[13]: https://codecept.io/img/codeceptjs-slideshow.gif
+[20]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[14]: https://webdriver.io
+[21]: https://webdriver.io
 
-[15]: https://webdriver.io/docs/selenium-standalone-service.html
+[22]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[16]: https://webdriver.io/docs/sauce-service.html
+[23]: https://webdriver.io/docs/sauce-service.html

docs/puppeteer.md

@@ -110,7 +110,6 @@ Tests consist with a scenario of user's action taken on a page. The most widely
 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](https://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