codeceptjs 2.4.3 → 2.6.2

package/docs/changelog.md

@@ -7,6 +7,122 @@ layout: Section
 
 # Releases
 
+## 2.6.2
+
+* [WebDriver][Puppeteer] Added `forceClick` method to emulate click event instead of using native events.
+* **[Playwright]** Updated to 0.14
+* **[Puppeteer]** Updated to Puppeteer v3.0
+* **[wdio]** Fixed undefined output directory for wdio plugns. Fix By **[PeterNgTr](https://github.com/PeterNgTr)**
+* **[Playwright]** Introduced `handleDownloads` method to download file. Please note, this method has slightly different API than the same one in Puppeteer.
+* **[allure]** Fixed undefined output directory for allure plugin on using custom runner. Fix by **[charliepradeep](https://github.com/charliepradeep)**
+* **[WebDriver]** Fixed `waitForEnabled` fix for webdriver 6. Fix by **[dsharapkou](https://github.com/dsharapkou)**
+* Workers: Fixed negative failure result if use scenario with the same names. Fix by **[Vorobeyko](https://github.com/Vorobeyko)**
+* **[MockRequest]** Updated documentation to match new helper version
+* Fixed: skipped tests are not reported if a suite failed in `before`. Refer [#2349](https://github.com/Codeception/CodeceptJS/issues/2349) & [#2354](https://github.com/Codeception/CodeceptJS/issues/2354). Fix by **[koushikmohan1996](https://github.com/koushikmohan1996)**
+
+## 2.6.1
+
+* [screenshotOnFail plugin] Fixed saving screenshot of active session.
+* [screenshotOnFail plugin] Fix issue [#2301](https://github.com/Codeception/CodeceptJS/issues/2301) when having the flag `uniqueScreenshotNames`=true results in `undefined` in screenshot file name by **[PeterNgTr](https://github.com/PeterNgTr)**
+* **[WebDriver]** Fixed `waitForElement` not applying the optional second argument to override the default timeout in webdriverio 6. Fix by **[Mooksc](https://github.com/Mooksc)**
+* **[WebDriver]** Updated `waitUntil` method which is used by all of the wait* functions. This updates the `waitForElement` by the same convention used to update `waitForVisible` and `waitInUrl` to be compatible with both WebDriverIO v5 & v6. See [#2313](https://github.com/Codeception/CodeceptJS/issues/2313) by **[Mooksc](https://github.com/Mooksc)**
+
+## 2.6.0
+
+* **[Playwright] Updated to Playwright 0.12** by **[Georgegriff](https://github.com/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
+  * `forceClick` - added
+  * Added support for custom locators. See [#2277](https://github.com/Codeception/CodeceptJS/issues/2277)
+  * Introduced [device emulation](/playwright/#device-emulation):
+    * globally via `emulate` config option
+    * per session
+
+**[WebDriver] Updated to webdriverio v6** by **[PeterNgTr](https://github.com/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](https://github.com/gkushang)**
+
+```js
+I.click({ shadow: ['my-app', 'recipe-hello', 'button'] });
+```
+
+* **Fixed parallel execution of `run-workers` for Gherkin** scenarios by **[koushikmohan1996](https://github.com/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](https://github.com/amonkc)**
+* Gherkin improvement: setting different tags per examples. See [#2208](https://github.com/Codeception/CodeceptJS/issues/2208) by **[acuper](https://github.com/acuper)**
+* **[TestCafe]** Updated `click` to take first visible element. Fixes [#2226](https://github.com/Codeception/CodeceptJS/issues/2226) by **[theTainted](https://github.com/theTainted)**
+* [Puppeteer][WebDriver] Updated `waitForClickable` method to check for element overlapping. See [#2261](https://github.com/Codeception/CodeceptJS/issues/2261) by **[PiQx](https://github.com/PiQx)**
+* **[Puppeteer]** Dropped `puppeteer-firefox` support, as Puppeteer supports Firefox natively.
+* **[REST]** Rrespect Content-Type header. See [#2262](https://github.com/Codeception/CodeceptJS/issues/2262) by **[pmarshall-legacy](https://github.com/pmarshall-legacy)**
+* [allure plugin] Fixes BeforeSuite failures in allure reports. See [#2248](https://github.com/Codeception/CodeceptJS/issues/2248) by **[Georgegriff](https://github.com/Georgegriff)**
+* [WebDriver][Puppeteer][Playwright] A screenshot of for an active session is saved in multi-session mode. See [#2253](https://github.com/Codeception/CodeceptJS/issues/2253) by **[ChexWarrior](https://github.com/ChexWarrior)**
+* Fixed `--profile` option by **[pablopaul](https://github.com/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](https://github.com/Codeception/CodeceptJS/issues/2302). Fixes [#1968](https://github.com/Codeception/CodeceptJS/issues/1968) [#1315](https://github.com/Codeception/CodeceptJS/issues/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**.
+
+> [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

package/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'
 
     }
   }

package/docs/custom-helpers.md

@@ -3,12 +3,13 @@ permalink: /helpers
 title: Custom Helpers
 ---
 
+# Extending CodeceptJS With Custom Helpers
 
-Helpers is a core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them.
+Helper is the core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them.
 
-Methods of Helper class will be available in tests in `I` object. This abstracts test scenarios from the implementation and allows easily switching between backends.
+Methods of Helper class will be available in tests in `I` object. This abstracts test scenarios from the implementation and allows switching between backends seamlessly.
 
-Functionality of CodeceptJS should be extended by writing a custom helpers.
+Functionality of CodeceptJS could be extended by writing custom helpers.
 
 Helpers can also be installed as Node packages and required by corresponding Node modules.
 
@@ -36,7 +37,7 @@ helpers: {
 ```
 
 Helpers are ES6 classes inherited from [corresponding abstract class](https://github.com/Codeception/CodeceptJS/blob/master/lib/helper.js).
-Generated Helper will be added to `codecept.conf.js` config. It should look like this:
+Generated Helper will be added to `codecept.conf.js` config file. It should look like this:
 
 ```js
 const Helper = codecept_helper;
@@ -112,7 +113,7 @@ module.exports = MyHelper;
 
 ## Puppeteer Example
 
-Puppeteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Access `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
+Puppeteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Accessing `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
 
 Let's see how we can use [emulate](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulateoptions) function to emulate iPhone browser in a test.
 
@@ -168,6 +169,50 @@ 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`
@@ -175,13 +220,13 @@ does that for you, however you can enable them manually by placing helper to `he
 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
   }
 
 }
@@ -282,4 +327,4 @@ Retry rules are available in array `recorder.retries`. The last retry rule can b
 
 ## Using Typescript
 
-When using typescript, replace `module.exports` with `export` for autocompletion.
+With Typescript, just simply replacing `module.exports` with `export` for autocompletion.

package/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.
@@ -1138,12 +1162,14 @@ this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').
 Find a clickable element by providing human readable text:
 
 ```js
-this.helpers['WebDriver']._locateClickable('Next page').then // ...
+const els = await this.helpers.WebDriver._locateClickable('Next page');
+const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages');
 ```
 
 #### Parameters
 
 -   `locator` **([string][4] \| [object][6])** element located by CSS|XPath|strict locator.
+-   `context`  
 
 ### \_locateFields
 
@@ -1187,6 +1213,38 @@ I.amOnPage('/login'); // opens a login page
 
 -   `url` **[string][4]** url path or global url.
 
+### forceClick
+
+Perform an emulated click on a link or a button, given by a locator.
+Unlike normal click instead of sending native event, emulates a click with JavaScript.
+This works on hidden, animated or inactive elements as well.
+
+If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+For images, the "alt" attribute and inner text of any parent links are searched.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+// simple link
+I.forceClick('Logout');
+// button of form
+I.forceClick('Submit');
+// CSS button
+I.forceClick('#form input[type=submit]');
+// XPath
+I.forceClick('//form/*[@type=submit]');
+// link in context
+I.forceClick('Logout', '#nav');
+// using strict locator
+I.forceClick({css: 'nav a.login'});
+```
+
+#### Parameters
+
+-   `locator` **([string][4] \| [object][6])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+-   `context` **([string][4]? | [object][6])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.{{ react }} (optional, default `null`)
+
 ### doubleClick
 
 Performs a double-click on an element matched by link|button|label|CSS or XPath.
@@ -1477,6 +1535,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`)
 
@@ -1496,6 +1556,24 @@ I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scro
 -   `fileName` **[string][4]** file name to save.
 -   `fullPage` **[boolean][15]** (optional, `false` by default) flag to enable fullscreen screenshot mode. (optional, default `false`)
 
+### type
+
+Types out the given string or the array of keys provided.
+_Note:_ Should only be used when using [`fillField`][19] is not an option.
+
+```js
+// When passing in a string
+I.type('Type this out.');
+// When passing in an array
+I.type(['T', 'E', 'X', 'T']);
+```
+
+#### Parameters
+
+-   `keys`  
+-   `key` **([string][4] \| [Array][14]<[string][4]>)** or array of keys to type.
+    Type out given array of keys or a string of text
+
 ### dragAndDrop
 
 Drag an item to a destination element.
@@ -1705,3 +1783,5 @@ Returns **[object][6]** Element bounding rectangle
 [17]: https://webdriver.io/docs/timeouts.html
 
 [18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
+
+[19]: #fillfield