codeceptjs 2.1.3 → 2.2.1

package/docs/helpers/Puppeteer.md

@@ -2,11 +2,12 @@
 id: Puppeteer
 title: Puppeteer
 ---
+
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
 ## Puppeteer
 
-**Extends Helper**
+Extends Helper
 
 Uses [Google Chrome's Puppeteer][1] library to run tests inside headless Chrome.
 Browser control is executed via DevTools Protocol (instead of Selenium).
@@ -14,26 +15,30 @@ This helper works with a browser out of the box with no additional tools require
 
 Requires `puppeteer` package to be installed.
 
+> Experiemental Firefox support [can be activated][2].
+
 ## Configuration
 
 This helper should be configured in codecept.json or codecept.conf.js
 
 -   `url`: base url of website to be tested
--   `show`: (optional, default: false) - show Google Chrome window for debug.
--   `restart`: (optional, default: true) - restart browser between tests.
--   `disableScreenshots`: (optional, default: false)  - don't save screenshot on failure.
--   `fullPageScreenshots` (optional, default: false) - make full page screenshots on failure.
--   `uniqueScreenshotNames`: (optional, default: false)  - option to prevent screenshot override if you have scenarios with the same name in different suites.
--   `keepBrowserState`: (optional, default: false) - keep browser state between tests when `restart` is set to false.
--   `keepCookies`: (optional, default: false) - keep cookies between tests when `restart` is set to false.
+-   `show`:  - show Google Chrome window for debug.
+-   `restart`:  - restart browser between tests.
+-   `disableScreenshots`:   - don't save screenshot on failure.
+-   `fullPageScreenshots`  - make full page screenshots on failure.
+-   `uniqueScreenshotNames`:   - option to prevent screenshot override if you have scenarios with the same name in different suites.
+-   `keepBrowserState`:  - keep browser state between tests when `restart` is set to false.
+-   `keepCookies`:  - keep cookies between tests when `restart` is set to false.
 -   `waitForAction`: (optional) how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
--   `waitForNavigation`: (optional, default: 'load'). When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API][2]. Array values are accepted as well.
--   `getPageTimeout` (optional, default: '0') config option to set maximum navigation time in milliseconds.
--   `waitForTimeout`: (optional) default wait\* timeout in ms. Default: 1000.
+-   `waitForNavigation`: . When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API][3]. Array values are accepted as well.
+-   `pressKeyDelay`: . Delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
+-   `getPageTimeout`  config option to set maximum navigation time in milliseconds.
+-   `waitForTimeout`: (optional) default wait\ timeout in ms. Default: 1000.
 -   `windowSize`: (optional) default window size. Set a dimension like `640x480`.
 -   `userAgent`: (optional) user-agent string.
--   `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
--   `chrome`: (optional) pass additional [Puppeteer run options][3].
+-   `manualStart`:  - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
+-   `browser`:  - can be changed to `firefox` when using [puppeteer-firefox][2].
+-   `chrome`: (optional) pass additional [Puppeteer run options][4].
 
 #### Example #1: Wait for 0 network connections.
 
@@ -78,7 +83,7 @@ This helper should be configured in codecept.json or codecept.conf.js
 }
 ```
 
-#### Example #4: Connect to remote browser by specifying [websocket endpoint][4]
+#### Example #4: Connect to remote browser by specifying [websocket endpoint][5]
 
 ```json
 {
@@ -134,6 +139,12 @@ Should be used in custom helpers:
 const elements = await this.helpers['Puppeteer']._locate({name: 'password'});
 ```
 
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
+
 #### Parameters
 
 -   `locator`  
@@ -150,7 +161,7 @@ this.helpers['Puppeteer']._locateCheckable('I agree with terms and conditions').
 #### Parameters
 
 -   `locator`  
--   `providedContext`   (optional, default `null`)
+-   `providedContext`   
 
 ### \_locateClickable
 
@@ -182,13 +193,13 @@ Set current page
 
 #### Parameters
 
--   `page` **[object][5]** page to set
+-   `page` [object][6] page to set
 
 ### acceptPopup
 
 Accepts the active JavaScript native popup window, as created by window.alert|window.confirm|window.prompt.
 Don't confuse popups with modal windows, as created by [various
-libraries][6].
+libraries][7].
 
 ### amAcceptingPopups
 
@@ -226,7 +237,9 @@ I.amOnPage('/login'); // opens a login page
 
 #### Parameters
 
--   `url`  url path or global url.
+-   `url` [string][8] url path or global url.
+    
+
 
 ### appendField
 
@@ -239,8 +252,14 @@ I.appendField('#myTextField', 'appended');
 
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator
--   `value`  text value to append.
+-   `field` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator
+-   `value` [string][8] text value to append.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### attachFile
 
@@ -255,8 +274,10 @@ I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
 
 #### Parameters
 
--   `locator`  field located by label|name|CSS|XPath|strict locator.
--   `pathToFile`  local file path relative to codecept.json config file.
+-   `locator` ([string][8] \| [object][6]) field located by label|name|CSS|XPath|strict locator.
+-   `pathToFile` [string][8] local file path relative to codecept.json config file.
+    
+
 
 ### cancelPopup
 
@@ -277,8 +298,10 @@ I.checkOption('agree', '//form');
 
 #### Parameters
 
--   `field`  checkbox located by label | name | CSS | XPath | strict locator.
--   `context`  (optional) element located by CSS | XPath | strict locator.
+-   `field` ([string][8] \| [object][6]) checkbox located by label | name | CSS | XPath | strict locator.
+-   `context` [string][8] (optional, `null` by default) element located by CSS | XPath | strict locator.
+    
+ 
 
 ### clearCookie
 
@@ -293,7 +316,9 @@ I.clearCookie('test');
 #### Parameters
 
 -   `name`  
--   `cookie`  (optional) cookie name.
+-   `cookie` [string][8] (optional, `null` by default) cookie name
+    
+
 
 ### clearField
 
@@ -307,7 +332,10 @@ I.clearField('#email');
 
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator.
+-   `field`  
+-   `editable` ([string][8] \| [object][6]) field located by label|name|CSS|XPath|strict locator.
+    
+
 
 ### click
 
@@ -326,7 +354,7 @@ I.click('Submit');
 // CSS button
 I.click('#form input[type=submit]');
 // XPath
-I.click('//form/*[@type=submit]');
+I.click('//form/[@type=submit]');
 // link in context
 I.click('Logout', '#nav');
 // using strict locator
@@ -335,21 +363,33 @@ I.click({css: 'nav a.login'});
 
 #### Parameters
 
--   `locator`  clickable link or button located by text, or any element located by CSS|XPath|strict locator.
--   `context`  (optional) element to search in CSS|XPath|Strict locator.
+-   `locator` ([string][8] \| [object][6]) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+-   `context` ([string][8] \| [object][6]) (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### clickLink
 
 Performs a click on a link and waits for navigation before moving on.
 
 ```js
-I.click('Logout', '#nav');
+I.clickLink('Logout', '#nav');
 ```
 
 #### Parameters
 
--   `locator`  clickable link or button located by text, or any element located by CSS|XPath|strict locator
--   `context`  (optional) element to search in CSS|XPath|Strict locator
+-   `locator` ([string][8] \| [object][6]) clickable link or button located by text, or any element located by CSS|XPath|strict locator
+-   `context` ([string][8] \| [object][6]) (optional, `null` by default) element to search in CSS|XPath|Strict locator
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### closeCurrentTab
 
@@ -373,54 +413,98 @@ Opposite to `see`. Checks that a text is not present on a page.
 Use context parameter to narrow down the search.
 
 ```js
-I.dontSee('Login'); // assume we are already logged in
+I.dontSee('Login'); // assume we are already logged in.
+I.dontSee('Login', '.nav'); // no login inside .nav element
 ```
 
 #### Parameters
 
--   `text`  is not present.
--   `context`  (optional) element located by CSS|XPath|strict locator in which to perfrom search.
+-   `text` [string][8] which is not present.
+-   `context` ([string][8] \| [object][6]) (optional) element located by CSS|XPath|strict locator in which to perfrom search.
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### dontSeeCheckboxIsChecked
 
 Verifies that the specified checkbox is not checked.
 
+```js
+I.dontSeeeCheckboxIsChedcked('#agree'); // located by ID
+I.dontSeeeCheckboxIsChedcked('I agree to terms'); // located by label
+I.dontSeeeCheckboxIsChedcked('agree'); // located by name
+```
+
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator.
+-   `field` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator.
+    
+
 
 ### dontSeeCookie
 
 Checks that cookie with given name does not exist.
 
+```js
+I.dontSeeCookie('auth'); // no auth cookie
+```
+
 #### Parameters
 
--   `name`  cookie name.
+-   `name` [string][8] cookie name.
+    
+
 
 ### dontSeeCurrentUrlEquals
 
 Checks that current url is not equal to provided one.
 If a relative url provided, a configured url will be prepended to it.
 
+```js
+I.dontSeeCurrentUrlEquals('/login'); // relative url are ok
+I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also ok
+```
+
 #### Parameters
 
--   `url`  value to check.
+-   `url` [string][8] value to check.
+    
+
 
 ### dontSeeElement
 
 Opposite to `seeElement`. Checks that element is not visible (or in DOM)
 
+```js
+I.dontSeeElement('.modal'); // modal is not shown
+```
+
 #### Parameters
 
--   `locator`  located by CSS|XPath|Strict locator.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|Strict locator.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### dontSeeElementInDOM
 
 Opposite to `seeElementInDOM`. Checks that element is not on page.
 
+```js
+I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
+```
+
 #### Parameters
 
--   `locator`  located by CSS|XPath|Strict locator.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|Strict locator.
+    
+
 
 ### dontSeeInCurrentUrl
 
@@ -428,33 +512,55 @@ Checks that current url does not contain a provided fragment.
 
 #### Parameters
 
--   `url`  value to check.
+-   `url` [string][8] value to check.
+    
+
 
 ### dontSeeInField
 
 Checks that value of input field or textare doesn't equal to given value
 Opposite to `seeInField`.
 
+```js
+I.dontSeeInField('email', 'user@user.com'); // field by name
+I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
+```
+
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator.
--   `value`  value to check.
+-   `field` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator.
+-   `value` [string][8] value to check.
+    
+
 
 ### dontSeeInSource
 
 Checks that the current page does not contains the given string in its raw source code.
 
+```js
+I.dontSeeInSource('<!--'); // no comments in source
+```
+
 #### Parameters
 
--   `text`  value to check.
+-   `text`  
+-   `value` [string][8] to check.
+    
+
 
 ### dontSeeInTitle
 
 Checks that title does not contain text.
 
+```js
+I.dontSeeInTitle('Error');
+```
+
 #### Parameters
 
--   `text`  text value to check.
+-   `text` [string][8] value to check.
+    
+
 
 ### doubleClick
 
@@ -470,24 +576,25 @@ I.doubleClick('.btn.edit');
 
 #### Parameters
 
--   `locator`  clickable link or button located by text, or any element located by CSS|XPath|strict locator.
--   `context`  (optional) element to search in CSS|XPath|Strict locator.
+-   `locator` ([string][8] \| [object][6]) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+-   `context` ([string][8] \| [object][6]) (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### downloadFile
 
-Performs a download file on an element matched by link|button|CSS or XPath.
-File is downloaded by default to output folder.
-If no custom file name is provided, the default name will be used
+This method is depreacted.
 
-```js
-I.downloadFile('td[class="text-right file-link"] a', 'thisIsCustomName');
-```
+Please use `handleDownloads()` instead.
 
 #### Parameters
 
--   `locator`  clickable link or button located by CSS|XPath locator.
+-   `locator`  
 -   `customName`  
--   `string`  custom file name.
 
 ### dragAndDrop
 
@@ -499,8 +606,10 @@ I.dragAndDrop('#dragHandle', '#container');
 
 #### Parameters
 
--   `srcElement`  located by CSS|XPath|strict locator.
--   `destElement`  located by CSS|XPath|strict locator.
+-   `srcElement` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+-   `destElement` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+    
+
 
 ### dragSlider
 
@@ -514,19 +623,26 @@ I.dragSlider('#slider', -70);
 
 #### Parameters
 
--   `locator`  located by label|name|CSS|XPath|strict locator.
--   `offsetX`  position to drag.
+-   `locator` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator.
+-   `offsetX` [number][9] position to drag.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### executeAsyncScript
 
 Executes async script on page.
 Provided function should execute a passed callback (as first argument) to signal it is finished.
 
-Example: In Vue.js to make components completely rendered we are waiting for [nextTick][7].
+Example: In Vue.js to make components completely rendered we are waiting for [nextTick][10].
 
 ```js
 I.executeAsyncScript(function(done) {
-Vue.nextTick(done); // waiting for next tick
+  Vue.nextTick(done); // waiting for next tick
 });
 ```
 
@@ -535,14 +651,14 @@ Additional arguments can be passed as well, while `done` function is always last
 
 ```js
 let val = await I.executeAsyncScript(function(url, done) {
-// in browser context
-$.ajax(url, { success: (data) => done(data); }
+  // in browser context
+  $.ajax(url, { success: (data) => done(data); }
 }, 'http://ajax.callback.url/');
 ```
 
 #### Parameters
 
--   `fn`  function to be executed in browser context.
+-   `fn` ([string][8] \| [function][11]) function to be executed in browser context.
 
 ### executeScript
 
@@ -556,8 +672,8 @@ Example with jQuery DatePicker:
 ```js
 // change date of jQuery DatePicker
 I.executeScript(function() {
-// now we are inside browser context
-$('date').datetimepicker('setDate', new Date());
+  // now we are inside browser context
+  $('date').datetimepicker('setDate', new Date());
 });
 ```
 
@@ -565,14 +681,14 @@ Can return values. Don't forget to use `await` to get them.
 
 ```js
 let date = await I.executeScript(function(el) {
-// only basic types can be returned
-return $(el).datetimepicker('getDate').toString();
+  // only basic types can be returned
+  return $(el).datetimepicker('getDate').toString();
 }, '#date'); // passing jquery selector
 ```
 
 #### Parameters
 
--   `fn`  function to be executed in browser context.
+-   `fn` ([string][8] \| [function][11]) function to be executed in browser context.
 
 ### fillField
 
@@ -592,14 +708,21 @@ I.fillField({css: 'form#login input[name=username]'}, 'John');
 
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator.
--   `value`  text value to fill.
+-   `field` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator.
+-   `value` [string][8] text value to fill.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### grabAttributeFrom
 
 Retrieves an attribute from an element located by CSS or XPath and returns it to test.
 An array as a result will be returned if there are more than one matched element.
-Resumes test execution, so **should be used inside async with `await`** operator.
+Resumes test execution, so should be used inside async with `await` operator.
 
 ```js
 let hint = await I.grabAttributeFrom('#tooltip', 'title');
@@ -607,8 +730,17 @@ let hint = await I.grabAttributeFrom('#tooltip', 'title');
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `attr`  attribute name.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `attr` [string][8] attribute name.
+
+Returns [Promise][12]&lt;[string][8]> attribute value
+
+
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### grabBrowserLogs
 
@@ -623,7 +755,8 @@ console.log(JSON.stringify(logs))
 
 Gets a cookie object by name.
 If none provided gets all cookies.
-Resumes test execution, so **should be used inside async with `await`** operator.
+
+-   Resumes test execution, so should be used inside async with `await` operator.
 
 ```js
 let cookie = await I.grabCookie('auth');
@@ -632,12 +765,16 @@ assert(cookie.value, '123456');
 
 #### Parameters
 
--   `name`  (optional) cookie name.Returns cookie in JSON format. If name not passed returns all cookies for this domain.
+-   `name`  cookie name. 
+
+Returns [Promise][12]&lt;[string][8]> attribute value
+
+Returns cookie in JSON format. If name not passed returns all cookies for this domain.
 
 ### grabCssPropertyFrom
 
 Grab CSS property for given locator
-Resumes test execution, so **should be used inside an async function with `await`** operator.
+Resumes test execution, so should be used inside an async function with `await` operator.
 
 ```js
 const value = await I.grabCssPropertyFrom('h3', 'font-weight');
@@ -645,8 +782,17 @@ const value = await I.grabCssPropertyFrom('h3', 'font-weight');
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `cssProperty`  CSS property name.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `cssProperty` [string][8] CSS property name.
+
+Returns [Promise][12]&lt;[string][8]> CSS value
+
+
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### grabCurrentUrl
 
@@ -658,10 +804,40 @@ let url = await I.grabCurrentUrl();
 console.log(`Current URL is [${url}]`);
 ```
 
+Returns [Promise][12]&lt;[string][8]> current URL
+
+
+
+### grabDataFromPerformanceTiming
+
+Grab the data from performance timing using Navigation Timing API.
+The returned data will contain following things in ms:
+
+-   responseEnd,
+-   domInteractive,
+-   domContentLoadedEventEnd,
+-   loadEventEnd
+    Resumes test execution, so should be used inside an async function with `await` operator.
+
+```js
+await I.amOnPage('https://example.com');
+let data = await I.grabDataFromPerformanceTiming();
+//Returned data
+{ // all results are in [ms]
+  responseEnd: 23,
+  domInteractive: 44,
+  domContentLoadedEventEnd: 196,
+  loadEventEnd: 241
+}
+```
+
+
+
+
 ### grabHTMLFrom
 
 Retrieves the innerHTML from an element located by CSS or XPath and returns it to test.
-Resumes test execution, so **should be used inside async function with `await`** operator.
+Resumes test execution, so should be used inside async function with `await` operator.
 If more than one element is found - an array of HTMLs returned.
 
 ```js
@@ -672,35 +848,56 @@ let postHTML = await I.grabHTMLFrom('#post');
 
 -   `locator`  element located by CSS|XPath|strict locator.
 
+Returns [Promise][12]&lt;[string][8]> HTML code for an element
+
+
+
 ### grabNumberOfOpenTabs
 
 Grab number of open tabs.
 
 ```js
-I.grabNumberOfOpenTabs();
+let tabs = await I.grabNumberOfOpenTabs();
 ```
 
+Returns [Promise][12]&lt;[number][9]> number of open tabs
+
+
+
 ### grabNumberOfVisibleElements
 
 Grab number of visible elements by locator.
 
 ```js
-I.grabNumberOfVisibleElements('p');
+let numOfElements = await I.grabNumberOfVisibleElements('p');
 ```
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+
+Returns [Promise][12]&lt;[number][9]> number of visible elements
+
+
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### grabPageScrollPosition
 
 Retrieves a page scroll position and returns it to test.
-Resumes test execution, so **should be used inside an async function with `await`** operator.
+Resumes test execution, so should be used inside an async function with `await` operator.
 
 ```js
 let { x, y } = await I.grabPageScrollPosition();
 ```
 
+Returns [Promise][12]&lt;[object][6]> scroll position
+
+
+
 ### grabPopupText
 
 Grab the text within the popup. If no popup is visible then it will return null
@@ -718,10 +915,14 @@ Resumes test execution, so should be used inside an async function.
 let pageSource = await I.grabSource();
 ```
 
+Returns [Promise][12]&lt;[string][8]> source code
+
+
+
 ### grabTextFrom
 
 Retrieves a text from an element located by CSS or XPath and returns it to test.
-Resumes test execution, so **should be used inside async with `await`** operator.
+Resumes test execution, so should be used inside async with `await` operator.
 
 ```js
 let pin = await I.grabTextFrom('#pin');
@@ -733,19 +934,32 @@ If multiple elements found returns an array of texts.
 
 -   `locator`  element located by CSS|XPath|strict locator.
 
+Returns [Promise][12]&lt;[string][8]> attribute value
+
+
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
+
 ### grabTitle
 
 Retrieves a page title and returns it to test.
-Resumes test execution, so **should be used inside async with `await`** operator.
+Resumes test execution, so should be used inside async with `await` operator.
 
 ```js
 let title = await I.grabTitle();
 ```
 
+Returns [Promise][12]&lt;[string][8]> title
+
+
+
 ### grabValueFrom
 
 Retrieves a value from a form element located by CSS or XPath and returns it to test.
-Resumes test execution, so **should be used inside async function with `await`** operator.
+Resumes test execution, so should be used inside async function with `await` operator.
 
 ```js
 let email = await I.grabValueFrom('input[name=email]');
@@ -753,7 +967,30 @@ let email = await I.grabValueFrom('input[name=email]');
 
 #### Parameters
 
--   `locator`  field located by label|name|CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) field located by label|name|CSS|XPath|strict locator.
+
+Returns [Promise][12]&lt;[string][8]> attribute value
+
+
+
+### handleDownloads
+
+Sets a directory to where save files. Allows to test file downloads.
+Should be used with [FileSystem helper][13] to check that file were downloaded correctly.
+
+By default files are saved to `output/downloads`.
+This directory is cleaned on every `handleDownloads` call, to ensure no old files are kept.
+
+```js
+I.handleDownloads();
+I.click('Download Avatar');
+I.amInPath('output/downloads');
+I.seeFile('avatar.jpg');
+```
+
+#### Parameters
+
+-   `downloadPath` [string][8] change this parameter to set another directory for saving 
 
 ### haveRequestHeaders
 
@@ -767,7 +1004,7 @@ I.haveRequestHeaders({
 
 #### Parameters
 
--   `customHeaders`  
+-   `customHeaders` [object][6] headers to set
 
 ### moveCursorTo
 
@@ -781,9 +1018,16 @@ I.moveCursorTo('#submit', 5,5);
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
--   `offsetX`  (optional) X-axis offset.
--   `offsetY`  (optional) Y-axis offset.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+-   `offsetX` [number][9] (optional, `0` by default) X-axis offset. 
+-   `offsetY` [number][9] (optional, `0` by default) Y-axis offset.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### openNewTab
 
@@ -796,7 +1040,7 @@ I.openNewTab();
 ### pressKey
 
 Presses a key on a focused element.
-Special keys like 'Enter', 'Control', [etc][8]
+Special keys like 'Enter', 'Control', [etc][14]
 will be replaced with corresponding unicode.
 If modifier key is used (Control, Command, Alt, Shift) in array, it will be released afterwards.
 
@@ -807,7 +1051,42 @@ I.pressKey(['Control','a']);
 
 #### Parameters
 
--   `key`  key or array of keys to press.
+-   `key` ([string][8] \| [array][15]) key or array of keys to press.
+    
+
+
+
+[Valid key names](https://w3c.github.io/webdriver/#keyboard-actions) are:
+
+- `'Add'`,
+- `'Alt'`,
+- `'ArrowDown'` or `'Down arrow'`,
+- `'ArrowLeft'` or `'Left arrow'`,
+- `'ArrowRight'` or `'Right arrow'`,
+- `'ArrowUp'` or `'Up arrow'`,
+- `'Backspace'`,
+- `'Command'`,
+- `'Control'`,
+- `'Del'`,
+- `'Divide'`,
+- `'End'`,
+- `'Enter'`,
+- `'Equals'`,
+- `'Escape'`,
+- `'F1 to F12'`,
+- `'Home'`,
+- `'Insert'`,
+- `'Meta'`,
+- `'Multiply'`,
+- `'Numpad 0'` to `'Numpad 9'`,
+- `'Pagedown'` or `'PageDown'`,
+- `'Pageup'` or `'PageUp'`,
+- `'Pause'`,
+- `'Semicolon'`,
+- `'Shift'`,
+- `'Space'`,
+- `'Subtract'`,
+- `'Tab'`.
 
 ### refreshPage
 
@@ -817,6 +1096,9 @@ Reload the current page.
 I.refreshPage();
 ```
 
+
+
+
 ### resizeWindow
 
 Resize the current window to provided width and height.
@@ -824,8 +1106,10 @@ First parameter can be set to `maximize`.
 
 #### Parameters
 
--   `width`  width in pixels or `maximize`.
--   `height`  height in pixels.Unlike other drivers Puppeteer changes the size of a viewport, not the window!
+-   `width` [number][9] width in pixels or `maximize`.
+-   `height` [number][9] height in pixels.
+    
+Unlike other drivers Puppeteer changes the size of a viewport, not the window!
     Puppeteer does not control the window of a browser so it can't adjust its real size.
     It also can't maximize a window.
 
@@ -844,13 +1128,19 @@ I.rightClick('Click me', '.context');
 
 #### Parameters
 
--   `locator`  clickable element located by CSS|XPath|strict locator.
--   `context`  (optional) element located by CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) clickable element located by CSS|XPath|strict locator.
+-   `context` ([string][8] \| [object][6]) (optional, `null` by default) element located by CSS|XPath|strict locator.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### saveScreenshot
 
 Saves a screenshot to ouput folder (set in codecept.json or codecept.conf.js).
-Filename is relative to output folder. 
+Filename is relative to output folder.
 Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
 
 ```js
@@ -860,8 +1150,10 @@ I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scro
 
 #### Parameters
 
--   `fileName`  file name to save.
--   `fullPage`  (optional) flag to enable fullscreen screenshot mode.
+-   `fileName` [string][8] file name to save.
+-   `fullPage` [boolean][16] (optional, `false` by default) flag to enable fullscreen screenshot mode.
+    
+
 
 ### scrollPageToBottom
 
@@ -871,6 +1163,9 @@ Scroll page to the bottom.
 I.scrollPageToBottom();
 ```
 
+
+
+
 ### scrollPageToTop
 
 Scroll page to the top.
@@ -879,6 +1174,9 @@ Scroll page to the top.
 I.scrollPageToTop();
 ```
 
+
+
+
 ### scrollTo
 
 Scrolls to element matched by locator.
@@ -891,9 +1189,11 @@ I.scrollTo('#submit', 5, 5);
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
--   `offsetX`  (optional) X-axis offset.
--   `offsetY`  (optional) Y-axis offset.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+-   `offsetX` [number][9] (optional, `0` by default) X-axis offset. 
+-   `offsetY` [number][9] (optional, `0` by default) Y-axis offset.
+    
+ 
 
 ### see
 
@@ -908,21 +1208,34 @@ I.see('Register', {css: 'form.register'}); // use strict locator
 
 #### Parameters
 
--   `text`  expected on page.
--   `context`  (optional) element located by CSS|Xpath|strict locator in which to search for text.
+-   `text` [string][8] expected on page.
+-   `context` ([string][8] \| [object][6]) (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
 
 ### seeAttributesOnElements
 
 Checks that all elements with given locator have given attributes.
 
 ```js
-I.seeAttributesOnElements('//form', {'method': "post"});
+I.seeAttributesOnElements('//form', { method: "post"});
 ```
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
--   `attributes`  object with attributes and their values to check.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+-   `attributes` [object][6] attributes and their values to check.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### seeCheckboxIsChecked
 
@@ -936,7 +1249,9 @@ I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
 
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator.
+-   `field` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator.
+    
+
 
 ### seeCookie
 
@@ -948,7 +1263,9 @@ I.seeCookie('Auth');
 
 #### Parameters
 
--   `name`  cookie name.
+-   `name` [string][8] cookie name.
+    
+
 
 ### seeCssPropertiesOnElements
 
@@ -960,8 +1277,15 @@ I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
--   `cssProperties`  object with CSS properties and their values to check.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+-   `cssProperties` [object][6] object with CSS properties and their values to check.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### seeCurrentUrlEquals
 
@@ -976,7 +1300,9 @@ I.seeCurrentUrlEquals('http://my.site.com/register');
 
 #### Parameters
 
--   `url`  value to check.
+-   `url` [string][8] value to check.
+    
+
 
 ### seeElement
 
@@ -989,7 +1315,14 @@ I.seeElement('#modal');
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) located by CSS|XPath|strict locator.
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### seeElementInDOM
 
@@ -1002,7 +1335,9 @@ I.seeElementInDOM('#modal');
 
 #### Parameters
 
--   `locator`  located by CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+    
+
 
 ### seeInCurrentUrl
 
@@ -1014,7 +1349,9 @@ I.seeInCurrentUrl('/register'); // we are on registration page
 
 #### Parameters
 
--   `url`  value to check.
+-   `url` [string][8] a fragment to check
+    
+
 
 ### seeInField
 
@@ -1030,8 +1367,10 @@ I.seeInField('#searchform input','Search');
 
 #### Parameters
 
--   `field`  located by label|name|CSS|XPath|strict locator.
--   `value`  value to check.
+-   `field` ([string][8] \| [object][6]) located by label|name|CSS|XPath|strict locator.
+-   `value` [string][8] value to check.
+    
+
 
 ### seeInPopup
 
@@ -1052,19 +1391,27 @@ I.seeInSource('<h1>Green eggs &amp; ham</h1>');
 
 #### Parameters
 
--   `text`  value to check.
+-   `text` [string][8] value to check.
+    
+
 
 ### seeInTitle
 
 Checks that title contains text.
 
+```js
+I.seeInTitle('Home Page');
+```
+
 #### Parameters
 
--   `text`  text value to check.
+-   `text` [string][8] text value to check.
+    
+
 
 ### seeNumberOfElements
 
-asserts that an element appears a given number of times in the DOM
+Asserts that an element appears a given number of times in the DOM.
 Element is located by label or name or CSS or XPath.
 
 ```js
@@ -1073,8 +1420,14 @@ I.seeNumberOfElements('#submitBtn', 1);
 
 #### Parameters
 
--   `selector`  
--   `num`  
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `num` [number][9] number of elements.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### seeNumberOfVisibleElements
 
@@ -1087,8 +1440,14 @@ I.seeNumberOfVisibleElements('.buttons', 3);
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `num`  number of elements.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `num` [number][9] number of elements.
+    
+
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### seeTextEquals
 
@@ -1101,7 +1460,7 @@ I.seeTextEquals('text', 'h1');
 #### Parameters
 
 -   `text`  
--   `context`   (optional, default `null`)
+-   `context`   
 
 ### seeTitleEquals
 
@@ -1138,8 +1497,10 @@ I.selectOption('Which OS do you use?', ['Android', 'iOS']);
 
 #### Parameters
 
--   `select`  field located by label|name|CSS|XPath|strict locator.
--   `option`  visible text or value of option.
+-   `select` ([string][8] \| [object][6]) field located by label|name|CSS|XPath|strict locator.
+-   `option` ([string][8] \| [array][15]) visible text or value of option.
+    
+
 
 ### setCookie
 
@@ -1151,15 +1512,24 @@ I.setCookie({name: 'auth', value: true});
 
 #### Parameters
 
--   `cookie`  cookie JSON object.
+-   `cookie` [object][6] a cookie object.
+    
+
 
 ### switchTo
 
 Switches frame or in case of null locator reverts to parent.
 
+```js
+I.switchTo('iframe'); // switch to first iframe
+I.switchTo(); // switch back to main page
+```
+
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) (optional, `null` by default) element located by CSS|XPath|strict locator.
+    
+
 
 ### switchToNextTab
 
@@ -1172,7 +1542,7 @@ I.switchToNextTab(2);
 
 #### Parameters
 
--   `num`   (optional, default `1`)
+-   `num` [number][9]  
 
 ### switchToPreviousTab
 
@@ -1185,7 +1555,7 @@ I.switchToPreviousTab(2);
 
 #### Parameters
 
--   `num`   (optional, default `1`)
+-   `num` [number][9]  
 
 ### uncheckOption
 
@@ -1202,8 +1572,10 @@ I.uncheckOption('agree', '//form');
 
 #### Parameters
 
--   `field`  checkbox located by label | name | CSS | XPath | strict locator.
--   `context`  (optional) element located by CSS | XPath | strict locator.
+-   `field` ([string][8] \| [object][6]) checkbox located by label | name | CSS | XPath | strict locator.
+-   `context` [string][8] (optional, `null` by default) element located by CSS | XPath | strict locator.
+    
+ 
 
 ### wait
 
@@ -1215,19 +1587,25 @@ I.wait(2); // wait 2 secs
 
 #### Parameters
 
--   `sec`  time in seconds to wait.
+-   `sec` [number][9] number of second to wait.
+    
+
 
 ### waitForDetached
 
 Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
 Element can be located by CSS or XPath.
 
-    I.waitForDetached('#popup');
+```js
+I.waitForDetached('#popup');
+```
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `sec`  (optional) time in seconds to wait, 1 by default.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+
 
 ### waitForElement
 
@@ -1241,8 +1619,15 @@ I.waitForElement('.btn.continue', 5); // wait for 5 secs
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `sec`  (optional) time in seconds to wait, 1 by default.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### waitForEnabled
 
@@ -1251,8 +1636,10 @@ Element can be located by CSS or XPath.
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
 -   `sec`  (optional) time in seconds to wait, 1 by default.
+    
+
 
 ### waitForFunction
 
@@ -1271,31 +1658,37 @@ I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and
 
 #### Parameters
 
--   `fn`  to be executed in browser context.
--   `argsOrSec`  (optional) arguments for function or seconds.
--   `sec`  (optional) time in seconds to wait, 1 by default.
+-   `fn` ([string][8] \| [function][11]) to be executed in browser context.
+-   `argsOrSec` ([array][15] \| [number][9]) (optional, `1` by default) arguments for function or seconds. 
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+ 
 
 ### waitForInvisible
 
 Waits for an element to be removed or become invisible on a page (by default waits for 1sec).
 Element can be located by CSS or XPath.
 
-    I.waitForInvisible('#popup');
+```js
+I.waitForInvisible('#popup');
+```
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `sec`  (optional) time in seconds to wait, 1 by default.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+
 
 ### waitForNavigation
 
 Waits for navigation to finish. By default takes configured `waitForNavigation` option.
 
-See [Pupeteer's reference][2]
+See [Pupeteer's reference][3]
 
 #### Parameters
 
--   `opts` **any**  (optional, default `{}`)
+-   `opts` any  
 
 ### waitForRequest
 
@@ -1308,8 +1701,8 @@ I.waitForRequest(request => request.url() === 'http://example.com' && request.me
 
 #### Parameters
 
--   `urlOrPredicate` **any** 
--   `sec` **any**  (optional, default `null`)
+-   `urlOrPredicate` ([string][8] \| [function][11]) 
+-   `sec` [number][9]? seconds to wait 
 
 ### waitForResponse
 
@@ -1322,8 +1715,8 @@ I.waitForResponse(request => request.url() === 'http://example.com' && request.m
 
 #### Parameters
 
--   `urlOrPredicate` **any** 
--   `sec` **any**  (optional, default `null`)
+-   `urlOrPredicate` ([string][8] \| [function][11]) 
+-   `sec` [number][9]? number of seconds to wait 
 
 ### waitForText
 
@@ -1338,9 +1731,11 @@ I.waitForText('Thank you, form has been submitted', 5, '#modal');
 
 #### Parameters
 
--   `text`  to wait for.
--   `sec`  (optional) time in seconds to wait.
--   `context`  (optional) element located by CSS|XPath|strict locator.
+-   `text` [string][8] to wait for.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait 
+-   `context` ([string][8] \| [object][6]) (optional) element located by CSS|XPath|strict locator.
+    
+ 
 
 ### waitForValue
 
@@ -1352,21 +1747,27 @@ I.waitForValue('//input', "GoodValue");
 
 #### Parameters
 
--   `field`  input field.
--   `value`  expected value.
--   `sec`  (optional) time in seconds to wait, 1 sec by default.
+-   `field` ([string][8] \| [object][6]) input field.
+-   `value` [string][8] expected value.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+
 
 ### waitForVisible
 
 Waits for an element to become visible on a page (by default waits for 1sec).
 Element can be located by CSS or XPath.
 
-    I.waitForVisible('#popup');
+```js
+I.waitForVisible('#popup');
+```
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `sec`  (optional) time in seconds to wait, 1 by default.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+This method accepts [React selectors][17].
 
 ### waitInUrl
 
@@ -1378,8 +1779,10 @@ I.waitInUrl('/info', 2);
 
 #### Parameters
 
--   `urlPart`  value to check.
--   `sec`  (optional) time in seconds to wait.
+-   `urlPart` [string][8] value to check.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+ 
 
 ### waitNumberOfVisibleElements
 
@@ -1391,21 +1794,32 @@ I.waitNumberOfVisibleElements('a', 3);
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `num`  number of elements.
--   `sec`  (optional) time in seconds to wait.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `num` [number][9] number of elements.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+
+    
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+
 
 ### waitToHide
 
 Waits for an element to hide (by default waits for 1sec).
 Element can be located by CSS or XPath.
 
-    I.waitToHide('#popup');
+```js
+I.waitToHide('#popup');
+```
 
 #### Parameters
 
--   `locator`  element located by CSS|XPath|strict locator.
--   `sec`  (optional) time in seconds to wait, 1 by default.
+-   `locator` ([string][8] \| [object][6]) element located by CSS|XPath|strict locator.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+
 
 ### waitUntil
 
@@ -1418,9 +1832,11 @@ I.waitUntil(() => window.requests == 0, 5);
 
 #### Parameters
 
--   `fn`  function which is executed in browser context.
--   `sec`  (optional) time in seconds to wait, 1 by default.
--   `timeoutMsg`  (optional) message to show in case of timeout fail.
+-   `fn` ([function][11] \| [string][8]) function which is executed in browser context.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait 
+-   `timeoutMsg` [string][8] message to show in case of timeout fail.
+    
+ 
 
 ### waitUrlEquals
 
@@ -1433,21 +1849,41 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 
 #### Parameters
 
--   `urlPart`  value to check.
--   `sec`  (optional) time in seconds to wait.
+-   `urlPart` [string][8] value to check.
+-   `sec` [number][9] (optional, `1` by default) time in seconds to wait
+    
+ 
 
 [1]: https://github.com/GoogleChrome/puppeteer
 
-[2]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions
+[2]: https://codecept.io/helpers/Puppeteer-firefox
+
+[3]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions
+
+[4]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions
+
+[5]: https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
+
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[7]: http://jster.net/category/windows-modals-popups
+
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[10]: https://vuejs.org/v2/api/#Vue-nextTick
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[3]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[4]: https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
+[13]: https://codecept.io/helpers/FileSystem
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[14]: https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value
 
-[6]: http://jster.net/category/windows-modals-popups
+[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[7]: https://vuejs.org/v2/api/#Vue-nextTick
+[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[8]: https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value
+[17]: https://codecept.io/react