preparing for 1.1.0 release: changelog, docs updates, deps removal (#831)

Author: DavertMik

CHANGELOG.md

@@ -1,3 +1,52 @@
+## 1.1.0
+
+Major update to CodeceptJS. **NodeJS v 8.9.1** is now minimal Node version required.
+This brings native async-await support to CodeceptJS. It is recommended to start using await for tests instead of generators:
+
+```js
+async () => {
+  I.amOnPage('/page');
+  const url = await I.grabTextFrom('.nextPage');
+  I.amOnPage(url);
+}
+```
+
+Thanks to [@Apshenkin](https://github.com/apshenkin) for implementation. Also, most helpers were refactored to use async-await. This made our code simpler. We hope that this encourages more users to send pull requests!
+
+We also introduced strict ESLint policies for our codebase. Thanks to **[@Galkin](https://github.com/galkin)** for that.
+
+* **[Puppeteer] Helper introduced**. [Learn how to run tests headlessly with Google Chrome's Puppeteer](http://codecept.io/puppeteer/).
+* **[SeleniumWebdriver] Helper is deprecated**, it is recommended to use Protractor with config option `angular: false` instead.
+* [WebDriverIO] nested iframe support in the within block by @reubenmiller. Example:
+
+```js
+within({frame: ['#wrapperId', '[name=content]']}, () => {
+  I.click('Sign in!');
+  I.see('Email Address');
+});
+I.see('Nested Iframe test');
+I.dontSee('Email Address');
+});
+```
+* [WebDriverIO] Support for `~` locator to find elements by `aria-label`. This behavior is similar as it is in Appium and helps testing cross-platform React apps. Example:
+
+```html
+<Text accessibilityLabel="foobar">
+    CodeceptJS is awesome
+</Text>
+```
+↑ This element can be located with `~foobar` in WebDriverIO and Appium helpers. Thanks to @flyskywhy
+
+* Allow providing arbitrary objects in config includes by @rlewan
+* [REST] Prevent from mutating default headers by @alexashley. See [#789](https://github.com/Codeception/CodeceptJS/pull/789)
+* [REST] Fixed sending empty helpers with `haveRequestHeaders` in `sendPostRequest`. By @petrisorionel
+* Fixed displaying undefined args in output by @APshenkin
+* Fixed NaN instead of seconds in output by @APshenkin
+* Add browser name to report file for `multiple-run` by @trollr
+* Mocha updated to 4.x
+
+
+
 ## 1.0.3
 
 * [WebDriverIO][Protractor][Nightmare] method `waitUntilExists` implemented by @sabau

docs/acceptance.md

@@ -256,9 +256,9 @@ within({frame: [".content", "#editor"]}, () => {
   I.see('Page');
 });
 ```
-
 ---
 
 ### done()
 
 CodeceptJS through helpers provides user friendly API to interact with a webpage. In this section we described using WebDriverIO helper which allows to control browser through Selenium WebDriver.
+

docs/angular.md

@@ -1,9 +1,9 @@
-# AngularJS E2E Testing with CodeceptJS
+# Protractor Testing with CodeceptJS
 
 ## Introduction
 
 CodeceptJS is an acceptance testing framework. In diversified world of JavaScript testing libraries it aims to create a unified high level API for end-to-end testing, powered by different backends.
-CodeceptJS allows you to write a test and switch in config execution drivers: will it be *wedriverio*, *selenium-webdriver*, or *protractor* depends on you.
+CodeceptJS allows you to write a test and switch in config execution drivers: will it be *wedriverio*, *puppeteer*, or *protractor* depends on you.
 This way you aren't be bound to implementation, and your acceptance tests will work no matter of framework running them.
 
 As you know, [Protractor](http://www.protractortest.org/#/) is an official tool for testing AngularJS applications.
@@ -96,7 +96,7 @@ For TodoMVC application you will have following config created in `codecept.json
     "Protractor": {
       "url": "http://todomvc.com/examples/angularjs/",
       "driver": "hosted",
-      "browser": "firefox",
+      "browser": "chrome",
       "rootElement": "body"
     }
   },
@@ -264,6 +264,21 @@ Scenario('create todo item', (I) => {
 
 To learn more about refactoring options in CodeceptJS read [PageObjects guide](http://codecept.io/pageobjects/).
 
+### Testing non-Angular Applications
+
+Sure, Protractor can be used to test applications built without AngularJS. In this case you need to disable angular synchronization feature in config:
+
+```js
+"helpers": {
+  "Protractor": {
+    "url": "http://todomvc.com/examples/angularjs/",
+    "driver": "hosted",
+    "browser": "firefox",
+    "angular": false
+  }
+}
+```
+
 ### Extending
 
 What if CodeceptJS doesn't provide some of Protractor functionality you actually need? Sure its API is to general,

docs/basics.md

@@ -19,7 +19,7 @@ I object is an **actor**, an abstraction for a testing user. I is a proxy object
   "helpers": {
     "WebDriverIO": {
       "url": "http://localhost",
-      "browser": "firefox"
+      "browser": "chrome"
     }
   }
 ```
@@ -36,15 +36,15 @@ However, behind the scene **all actions are wrapped in promises** inside the `I`
 If you want to get information from a running test you can use `yield` inside a **generator function** and special methods of helpers started with `grab` prefix.
 
 ```js
-Scenario('try grabbers', function* (I) {
-  var title = yield I.grabTitle();
+Scenario('try grabbers', async (I) => {
+  var title = await I.grabTitle();
 });
 ```
 
 then you can use those variables in assertions:
 
 ```js
-var title = yield I.grabTitle();
+var title = await I.grabTitle();
 var assert = require('assert');
 assert.equal(title, 'CodeceptJS');
 ```

docs/helpers.md

@@ -83,23 +83,22 @@ class MyHelper extends Helper {
   /**
    * checks that authentication cookie is set
    */
-  seeAuthentication() {
+  async seeAuthentication() {
     // access current client of WebDriverIO helper
     let client = this.helpers['WebDriverIO'].browser;
 
     // get all cookies according to http://webdriver.io/api/protocol/cookie.html
     // any helper method should return a value in order to be added to promise chain
-    return client.cookie(function(err, res) {
-      // get values
-      let cookies = res.value;
-      for (let k in cookies) {
-        // check for a cookie
-        if (cookies[k].name != 'logged_in') continue;
-        assert.equal(cookies[k].value, 'yes');
-        return;
-      }
-      assert.fail(cookies, 'logged_in', "Auth cookie not set");
-    });
+    const res = await client.cookie();
+    // get values
+    let cookies = res.value;
+    for (let k in cookies) {
+      // check for a cookie
+      if (cookies[k].name != 'logged_in') continue;
+      assert.equal(cookies[k].value, 'yes');
+      return;
+    }
+    assert.fail(cookies, 'logged_in', "Auth cookie not set");
   }
 }
 

docs/installation.md

@@ -1,40 +1,8 @@
 # Installation
 
-## Global
-
-CodeceptJS can be installed via NPM globally
-
-```sh
-[sudo] npm install -g codeceptjs
-```
-
-then it can be started as
-
-```sh
-codeceptjs
-```
-
-To use it with WebDriverIO install webdriverio package globally:
-
-```sh
-[sudo] npm install -g webdriverio
-```
-
-To use it with Protractor install protractor package globally:
-
-```sh
-[sudo] npm install -g protractor
-```
-
-To use it with Nightmare install nightmare and nightmare-upload packages globally:
-
-```sh
-[sudo] npm install -g nightmare nightmare-upload
-```
-
 ### Local
 
-CodeceptJS can also be installed locally
+Use NPM install CodeceptJS:
 
 ```sh
 npm install --save-dev codeceptjs
@@ -64,14 +32,34 @@ To use it with Nightmare install nightmare and nightmare-upload packages:
 npm install nightmare nightmare-upload --save-dev
 ```
 
+To use it with Puppeteer install puppeteer package:
+
+```sh
+npm install puppeteer --save-dev
+```
+
+
 ## Meta Packages
 
 By default it doesn't install any backends like Webdriverio, Protractor, or Nightmare, so you need to install corresponding packages manually, or install one of the provided meta-packages:
 
 * [codeceptjs-webdriverio](https://www.npmjs.com/package/codeceptjs-webdriverio) - installs CodeceptJS + WebDriverIO
 * [codeceptjs-protractor](https://www.npmjs.com/package/codeceptjs-protractor) - installs CodeceptJS + Protractor
+* [codeceptjs-puppeteer](https://www.npmjs.com/package/codeceptjs-puppeteer) - installs CodeceptJS + Puppeteer
 * [codeceptjs-nightmare](https://www.npmjs.com/package/codeceptjs-nightmare) - installs CodeceptJS + Nightmare
 
+Install them using NPM:
+
+```sh
+[sudo] npm install codeceptjs-webdriverio
+# or
+[sudo] npm install codeceptjs-protractor
+# or
+[sudo] npm install codeceptjs-puppeteer
+# or
+[sudo] npm install codeceptjs-nightmare
+```
+
 They can be installed either globally or locally
 
 ## WebDriver
@@ -89,4 +77,24 @@ Launch Selenium with Chrome browser inside a Docker container:
 
 ```sh
 docker run --net=host selenium/standalone-chrome
-```
+```
+
+## Global
+
+CodeceptJS can be installed via NPM globally, in this case it is recommended to use meta-packages for installation:
+
+```sh
+[sudo] npm install -g codeceptjs-webdriverio
+# or
+[sudo] npm install -g codeceptjs-protractor
+# or
+[sudo] npm install -g codeceptjs-puppeteer
+# or
+[sudo] npm install -g codeceptjs-nightmare
+```
+
+then it can be started as
+
+```sh
+codeceptjs
+```

docs/nightmare.md

@@ -187,24 +187,23 @@ so you can access them in next calls to `evaluate`:
 
 ```js
 // inside a custom helper class
-seeAttributeContains(locator, attribute, expectedValue) {
+async seeAttributeContains(locator, attribute, expectedValue) {
   // let's use chai assertion library
-  let assert = require('chai').assert;
+  const assert = require('chai').assert;
   // get nightmare instance
-  let browser = this.helpers['Nightmare'].browser;
+  const browser = this.helpers['Nightmare'].browser;
   // find an element by CSS or XPath:
-  return this.helpers['Nightmare']._locate(locator).then(function(els) {
+  const els = await this.helpers['Nightmare']._locate(locator);
     // we received an array with IDs of matched elements
     // now let's execute client-side script to get attribute for the first element
-    return browser.evaluate(function(el, attribute) {
+  const attributeValue = await browser.evaluate(function(el, attribute) {
       // this is executed inside a web page!
       return codeceptjs.fetchElement(el).getAttribute(attribute);
-    }, els[0], attribute); // function + its params
-  }).then(function(attributeValue) {
+  }, els[0], attribute); // function + its params
+
     // get attribute value and back to server side
     // execute an assertion
-    assert.include(attributeValue, expectedValue);
-  });
+  assert.include(attributeValue, expectedValue);
 }
 ```
 

docs/pageobjects.md

@@ -130,15 +130,15 @@ module.exports = {
   },
 
   // introducing methods
-  openMainArticle: function* () {
+  openMainArticle: async () => {
     I.waitForVisible(this.container)
     let _this = this
     let title;
-    yield within(this.container, function*(){
-      title = yield I.grabTextFrom(_this.mainItem.number);
-      let subtitle = yield I.grabTextFrom(_this.mainItem.title);
+    await within(this.container, async () => {
+      title = await I.grabTextFrom(_this.mainItem.number);
+      let subtitle = await I.grabTextFrom(_this.mainItem.title);
       title = title + " " + subtitle.charAt(0).toLowerCase() + subtitle.slice(1);
-      yield I.click(_this.mainItem.title)
+      await I.click(_this.mainItem.title)
     })
     return title;
   }
@@ -148,8 +148,8 @@ module.exports = {
 and use them in your tests:
 
 ```js
-Scenario('login2', function* (I, loginPage, basePage) {
-  let title = yield* mainPage.openMainArticle()
+Scenario('login2', async (I, loginPage, basePage) => {
+  let title = await mainPage.openMainArticle()
   basePage.pageShouldBeOpened(title)
 });
 ```

docs/quickstart.md

@@ -1,6 +1,6 @@
 # QuickStart
 
-**NodeJS v 6.11.1** and higher required to start.
+**NodeJS v 8.9** and higher required to start.
 CodeceptJS is multi-backend testing framework. In this guide we will use webdriverio as backend but the same rules applies to other backends like Protractor or Nightmare.
 
 Install **CodeceptJS** with WebDriverIO using `codeceptjs-webdriverio` meta package from NPM.
@@ -17,8 +17,9 @@ or locally
 npm install codeceptjs-webdriverio --save-dev
 ```
 
-* To test with Nightmare install `codeceptjs-nightmare` package
+* To test with Puppeteer install `codeceptjs-puppeteer` package
 * To test with Protractor install `codeceptjs-protractor` package
+* To test with Nightmare install `codeceptjs-nightmare` package
 * For additional options see [Installation guide](http://codecept.io/installation/).
 
 ## Setup
@@ -42,7 +43,7 @@ No matter what helper you've chosen they will be similar in use.
 ? What helpers do you want to use?
 ❯◉ WebDriverIO
  ◯ Protractor
- ◯ SeleniumWebdriver
+ ◯ Puppeteer
  ◯ Nightmare
  ◯ FileSystem
 ```

lib/command/run-multiple.js

@@ -110,7 +110,7 @@ function runSuite(suite, suiteConf, browser) {
   // tweaking default output directories and for mochawesome
   overriddenConfig = replaceValue(overriddenConfig, 'output', path.join(config.output, outputDir));
   overriddenConfig = replaceValue(overriddenConfig, 'reportDir', path.join(config.output, outputDir));
-  overriddenConfig = replaceValue(overriddenConfig, 'mochaFile', path.join(config.output, outputDir, browser + '_report.xml'));
+  overriddenConfig = replaceValue(overriddenConfig, 'mochaFile', path.join(config.output, outputDir, `${browser}_report.xml`));
 
   // override grep param and collect all params
   const params = ['run',