codeceptjs · DavertMik · Mar 31, 2020 · Feb 18, 2020 · Mar 28, 2020 · Mar 28, 2020
diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml
@@ -8,6 +8,11 @@ on:
     branches:
       - master
 
+env:
+  CI: true
+  # Force terminal colors. @see https://www.npmjs.com/package/colors
+  FORCE_COLOR: 1
+
 jobs:
   build:
 
@@ -26,17 +31,16 @@ jobs:
     - name: install required packages
       run: |
         sudo apt-get update
-        sudo apt-get install libgbm-dev libwoff1 libopus0 libwebp6 libwebpdemux2 libenchant1c2a libgudev-1.0-0 libsecret-1-0 libhyphen0 libgdk-pixbuf2.0-0 libegl1 libgles2 libevent-2.1-6 libnotify4 libxslt1.1
-        sudo apt-get install xvfb
+        sudo apt-get install libgbm1 libgbm-dev libwoff1 libopus0 libwebp6 libwebpdemux2 libenchant1c2a libgudev-1.0-0 libsecret-1-0 libhyphen0 libgdk-pixbuf2.0-0 libegl1 libgles2 libevent-2.1-6 libnotify4 libxslt1.1
         sudo apt-get install php
     - name: npm install
       run: |
         npm install
     - name: start a server
       run: "php -S 127.0.0.1:8000 -t test/data/app &"
     - name: run chromium tests
-      run: " ./bin/codecept.js run -c test/acceptance/codecept.Playwright.js --grep @Playwright --debug"
+      run: "./bin/codecept.js run -c test/acceptance/codecept.Playwright.js --grep @Playwright --debug"
     - name: run firefox tests
-      run: "BROWSER=firefox ./bin/codecept.js run -c test/acceptance/codecept.Playwright.js --grep @Playwright --debug"
+      run: "BROWSER=firefox node ./bin/codecept.js run -c test/acceptance/codecept.Playwright.js --grep @Playwright --debug"
     - name: run webkit tests
-      run: "BROWSER=webkit ./bin/codecept.js run -c test/acceptance/codecept.Playwright.js --grep @Playwright --debug"
+      run: "BROWSER=webkit node ./bin/codecept.js run -c test/acceptance/codecept.Playwright.js --grep @Playwright --debug"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,80 @@
+## 2.6.0
+
+* **[Playwright] Updated to Playwright 0.12** by @Georgegriff.
+
+Upgrade playwright to ^0.12:
+
+```
+npm i playwright@^0.12 --save
+```
+
+[Notable changes](https://github.com/microsoft/playwright/releases/tag/v0.12.0):
+  * Fixed opening two browsers on start
+  * `executeScript` - passed function now accepts only one argument. Pass in objects or arrays if you need multtple arguments:
+```js
+// Old style, does not work anymore:
+I.executeScript((x, y) => x + y, x, y);
+// New style, passing an object:
+I.executeScript(({x, y}) => x + y, {x, y});
+```
+  * `click` - automatically waits for element to become clickable (visible, not animated) and waits for navigation.
+  * `clickLink` - deprecated
+  * `waitForClickable` - deprecated
+  * Added support for custom locators. See #2277
+  * Introduced [device emulation](/playwright/#device-emulation):
+    * globally via `emulate` config option
+    * per session
+
+**[WebDriver] Updated to webdriverio v6** by @PeterNgTr.
+
+Read [release notes](https://webdriver.io/blog/2020/03/26/webdriverio-v6-released.html), then
+upgrade webdriverio to ^6.0:
+
+```
+npm i webdriverio@^6.0 --save
+```
+*(webdriverio v5 support is deprecated and will be removed in CodeceptJS 3.0)*
+
+[WebDriver] Introduced [Shadow DOM support](/shadow) by @gkushang
+
+```js
+I.click({ shadow: ['my-app', 'recipe-hello', 'button'] });
+```
+
+* **Fixed parallel execution of `run-workers` for Gherkin** scenarios by @koushikmohan1996
+* [MockRequest] Updated and **moved to [standalone package](https://github.com/codecept-js/mock-request)**:
+  * full support for record/replay mode for Puppeteer
+  * added `mockServer` method to use flexible PollyJS API to define mocks
+  * fixed stale browser screen in record mode.
+* [Playwright] Added support on for `screenshotOnFail` plugin by @amonkc
+* Gherkin improvement: setting different tags per examples. See #2208 by @acuper
+* [TestCafe] Updated `click` to take first visible element. Fixes #2226 by @theTainted
+* [Puppeteer][WebDriver] Updated `waitForClickable` method to check for element overlapping. See #2261 by @PiQx
+* [Puppeteer] Dropped `puppeteer-firefox` support, as Puppeteer supports Firefox natively.
+* [REST] Rrespect Content-Type header. See #2262 by @pmarshall-legacy
+* [allure plugin] Fixes BeforeSuite failures in allure reports. See #2248 by @Georgegriff
+* [WebDriver][Puppeteer][Playwright] A screenshot of for an active session is saved in multi-session mode. See #2253 by @ChexWarrior
+* Fixed `--profile` option by @pablopaul. Profile value to be passed into `run-multiple` and `run-workers`:
+
+```
+npx codecept run-workers 2 --profile firefox
+```
+
+Value is available at `process.env.profile` (previously `process.profile`). See #2302. Fixes #1968 #1315
+
+* [commentStep Plugin introduced](/plugins#commentstep). Allows to annotate logical parts of a test:
+
+```js
+__`Given`;
+I.amOnPage('/profile')
+
+__`When`;
+I.click('Logout');
+
+__`Then`;
+I.see('You are logged out');
+```
+
 ## 2.5.0
 
 * **Experimental: [Playwright](/playwright) helper introduced**.

diff --git a/docs/basics.md b/docs/basics.md
@@ -622,7 +622,7 @@ within('.js-signup-form', () => {
 I.see('There were problems creating your account.');
 ```
 
-> ⚠ `within` can cause problems when used incorrectly. If you see a weired behavior of a test try to refactor it to not use `within`. It is recommended to keep within for simplest cases when possible.
+> ⚠ `within` can cause problems when used incorrectly. If you see a weird behavior of a test try to refactor it to not use `within`. It is recommended to keep within for simplest cases when possible.
 
 `within` can also work with IFrames. A special `frame` locator is required to locate the iframe and get into its context.
 

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -7,6 +7,25 @@ layout: Section
 
 # Releases
 
+## 2.5.0
+
+* **Experimental: [Playwright](/playwright) helper introduced**.
+
+> [Playwright](https://github.com/microsoft/playwright/) is an alternative to Puppeteer which works very similarly to it but adds cross-browser support with Firefox and Webkit. Until v1.0 Playwright API is not stable but we introduce it to CodeceptJS so you could try it.
+
+* **[Puppeteer]** Fixed basic auth support when running in multiple sessions. See [#2178](https://github.com/Codeception/CodeceptJS/issues/2178) by **[ian-bartholomew](https://github.com/ian-bartholomew)**
+* **[Puppeteer]** Fixed `waitForText` when there is no `body` element on page (redirect). See [#2181](https://github.com/Codeception/CodeceptJS/issues/2181) by **[Vorobeyko](https://github.com/Vorobeyko)**
+* [Selenoid plugin] Fixed overriding current capabilities by adding deepMerge. Fixes [#2183](https://github.com/Codeception/CodeceptJS/issues/2183) by **[koushikmohan1996](https://github.com/koushikmohan1996)**
+* Added types for `Scenario.todo` by **[Vorobeyko](https://github.com/Vorobeyko)**
+* Added types for Mocha by **[Vorobeyko](https://github.com/Vorobeyko)**. Fixed typing conflicts with Jest
+* **[FileSystem]** Added methods by **[nitschSB](https://github.com/nitschSB)**
+  * `waitForFile`
+  * `seeFileContentsEqualReferenceFile`
+* Added `--colors` option to `run` and `run-multiple` so you force colored output in dockerized environment. See [#2189](https://github.com/Codeception/CodeceptJS/issues/2189) by **[mirao](https://github.com/mirao)**
+* **[WebDriver]** Added `type` command to enter value without focusing on a field. See [#2198](https://github.com/Codeception/CodeceptJS/issues/2198) by **[xMutaGenx](https://github.com/xMutaGenx)**
+* Fixed `codeceptjs gt` command to respect config pattern for tests. See [#2200](https://github.com/Codeception/CodeceptJS/issues/2200) and [#2204](https://github.com/Codeception/CodeceptJS/issues/2204) by **[matheo](https://github.com/matheo)**
+
+
 ## 2.4.3
 
 * Hotfix for interactive pause

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -118,7 +118,7 @@ exports.config = {
 
 ## Profile
 
-Using values from `process.profile` you can change the config dynamically.
+Using `process.env.profile` you can change the config dynamically.
 It provides value of `--profile` option passed to runner.
 Use its value to change config value on the fly.
 
@@ -134,7 +134,7 @@ exports.config = {
     WebDriver: {
       url: 'http://localhost:3000',
       // load value from `profile`
-      browser: process.profile || 'firefox'
+      browser: process.env.profile || 'firefox'
 
     }
   }

diff --git a/docs/custom-helpers.md b/docs/custom-helpers.md
@@ -3,6 +3,7 @@ permalink: /helpers
 title: Custom Helpers
 ---
 
+# Extending CodeceptJS with Custom Helopers
 
 Helpers is a core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them.
 
@@ -168,20 +169,64 @@ class MyHelper extends Helper {
 module.exports = MyHelper;
 ```
 
+## Accessing Elements
+
+WebDriver, Puppeteer, Playwright, and Protractor drivers provide API for web elements.
+However, CodeceptJS do not expose them to tests by design, keeping test to be action focused.
+If you need to get access to web elements, it is recommended to implement operations for web elements in a custom helper.
+
+To get access for elements, connect to a corresponding helper and use `_locate` function to match web elements by CSS or XPath, like you usually do:
+
+### Acessing Elements in WebDriver
+
+```js
+// inside a custom helper
+async clickOnEveryElement(locator) {
+  const { WebDriver } = this.helpers;
+  const els = await WebDriver._locate(locator);
+
+  for (let el of els) {
+    await el.click();
+  }
+}
+```
+In this case an an instance of webdriverio element is used.
+To get a [complete API of an element](https://webdriver.io/docs/api/) refer to webdriverio docs.
+
+### Accessing Elements in Playwright & Puppeteer
+
+Similar method can be implemented for Playwright & Puppeteer:
+
+```js
+// inside a custom helper
+async clickOnEveryElement(locator) {
+  const { Playwright } = this.helpers;
+  const els = await Playwright._locate(locator);
+
+  for (let el of els) {
+    await el.click();
+  }
+}
+```
+
+In this case `el` will be an instance of [ElementHandle](https://github.com/microsoft/playwright/blob/v0.12.1/docs/api.md#class-elementhandle) which is similar for Playwright & [Puppeteer](https://pptr.dev/#?product=Puppeteer&version=v2.1.1&show=api-class-elementhandle).
+
+> ℹ There are more `_locate*` methods in each helper. Take a look on documentation of a helper you use to see which exact method it exposes.
+
 ## Configuration
 
 Helpers should be enabled inside `codecept.json` or `codecept.conf.js` files. Command `generate helper`
 does that for you, however you can enable them manually by placing helper to `helpers` section inside config file.
 You can also pass additional config options to your helper from a config - **(please note, this example contains comments, while JSON format doesn't support them)**:
 
 ```js
-"helpers": {
+helpers: {
   // here goes standard helpers:
   // WebDriver, Protractor, Nightmare, etc...
   // and their configuration
-  "MyHelper": {
-    "require": "./my_helper.js", // path to module
-    "defaultHost": "http://mysite.com" // custom config param
+  MyHelper: {
+    require: "./my_helper.js", // path to module
+    defaultHost: "http://mysite.com" // custom config param
   }
 
 }

diff --git a/docs/helpers/Appium.md b/docs/helpers/Appium.md
@@ -1107,6 +1107,30 @@ I.waitForText('Thank you, form has been submitted', 5, '#modal');
 -   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait (optional, default `1`)
 -   `context` **([string][4] \| [object][6])?** (optional) element located by CSS|XPath|strict locator. (optional, default `null`)
 
+### \_isShadowLocator
+
+Check if locator is type of "Shadow"
+
+#### Parameters
+
+-   `locator` **[object][6]** 
+
+### \_locateShadow
+
+Locate Element within the Shadow Dom
+
+#### Parameters
+
+-   `locator` **[object][6]** 
+
+### \_smartWait
+
+Smart Wait to locate an element
+
+#### Parameters
+
+-   `locator` **[object][6]** 
+
 ### \_locate
 
 Get elements by different locator types, including strict locator.
@@ -1477,6 +1501,8 @@ I.moveCursorTo('#submit', 5,5);
 #### Parameters
 
 -   `locator` **([string][4] \| [object][6])** located by CSS|XPath|strict locator.
+-   `xOffset`  
+-   `yOffset`  
 -   `offsetX` **[number][8]** (optional, `0` by default) X-axis offset. (optional, default `0`)
 -   `offsetY` **[number][8]** (optional, `0` by default) Y-axis offset. (optional, default `0`)
 

diff --git a/docs/helpers/Nightmare.md b/docs/helpers/Nightmare.md
@@ -876,15 +876,23 @@ I.selectOption('Which OS do you use?', ['Android', 'iOS']);
 
 ### setCookie
 
-Sets a cookie.
+Sets cookie(s).
+
+Can be a single cookie object or an array of cookies:
 
 ```js
 I.setCookie({name: 'auth', value: true});
+
+// as array
+I.setCookie([
+  {name: 'auth', value: true},
+  {name: 'agree', value: true}
+]);
 ```
 
 #### Parameters
 
--   `cookie` **[object][4]** a cookie object.Wrapper for `.cookies.set(cookie)`.
+-   `cookie` **([object][4] | [array][11])** a cookie object or array of cookie objects.Wrapper for `.cookies.set(cookie)`.
     [See more][14]
 
 ### triggerMouseEvent