codeceptjs 2.2.0 → 2.2.1

package/docs/basics.md

@@ -30,20 +30,23 @@ Here is the diagram of CodeceptJS architecture
 All helpers share the same API so it's easy to migrate tests from one backend to other.
 However, because of difference in backends and their limitations, they are not guaranteed to be compatible with each other. For instance, you can't set request headers in WebDriver or Protractor, but you can do so in Puppteer or Nightmare.
 
-Please note, you can't run tests by different helpers at once. You can't use some APIs from WebDriver and some from Nightmare. You should **pick one helper, as it defines how tests are executed.** If requirements change it's easy to migrate to another, but don't use few helpers at once. It's just not possible.
+**Pick one helper, as it defines how tests are executed.** If requirements change it's easy to migrate to another, but don't use few helpers of same kind at once.
 
-A helper should be enabled in main config. Configuration (like base url) should be provided as well:
+---
 
-```json
-  "helpers": {
-    "WebDriver": {
-      "url": "http://localhost",
-      "browser": "chrome"
-    }
-  }
-```
+Refer to following guides to more information on:
+
+* [▶ WebDriver](https://codecept.io/webdriver)
+* [▶ Protractor](https://codecept.io/angular)
+* [▶ Puppeteer](https://codecept.io/puppeteer)
+* [▶ Nightmare](https://codecept.io/nightmare)
+* TestCafe
+
+> ℹ Depending on a helper selected a list of available actions may change.
+
+To list all available commands for current configuration run `codeceptjs list`
+or enable [auto-completion by generating TypeScript definitions](#intellisense).
 
-In this config config all methods of `I` will be taken from `WebDriver` helper.
 
 ## Writing Tests
 
@@ -56,11 +59,221 @@ I.see('Please Login', 'h1');
 // ...
 ```
 
-To list all available commands for current configuration run `codeceptjs list`
-or enable [auto-completion by generating TypeScript definitions](#intellisense).
+### Opening a Page
+
+A test should usually start with navigating browser to the website.
+
+Start a test by opening a page. Use `I.amOnPage()` command for this:
+
+```js
+// When "http://site.com" is url in config
+I.amOnPage('/'); // -> opens http://site.com/
+I.amOnPage('/about'); // -> opens http://site.com/about
+I.amOnPage('https://google.com'); // -> https://google.com
+```
+
+When URL doesn't start with a protocol (http:// or https://) it is considered to be a relative URL and appended to URL which was initially set in the config.
+
+> It is recommended to use relative URLs and keep base URL in config file, so you could easily switch between development, staging, and production environments.
+
+
+### Locating Element
+
+Element can be found by CSS or XPath locators.
+
+```js
+I.seeElement('.user'); // element with CSS class user
+I.seeElement('//button[contains(., "press me")]'); // button
+```
+
+By default CodeceptJS tries to guess the locator type.
+In order to specify exact locator type you can pass an object called **strict locator**.
+
+```js
+I.seeElement({css: 'div.user'});
+I.seeElement({xpath: '//div[@class=user]'});
+```
+
+Strict locators allow to specify additional locator types:
+
+```js
+// locate form element by name
+I.seeElement({name: 'password'});
+// locate element by id
+I.seeElement({id: 'users'});
+// locate element by React component and props
+I.seeElement({react: 'user-profile', props: {name: 'davert'}});
+```
+
+In [mobile testing](http://codecept.io/mobile/#locating-elements) you can use `~` to specify accessibility id to locate an element. In web application you can locate element by their `aria-label` value.
+
+```js
+// locate element by [aria-label] attribute in web
+// or by accessibility id in mobile
+I.seeElement('~username');
+```
+
+> [▶ Learn more about using locators in CodeceptJS](https://codecept.io/locators).
+
+### Clicking
+
+CodeceptJS provides a flexible syntax to specify an element to click.
+
+By default CodeceptJS tries to find button or link with exact text on it
+
+```js
+// search for link or button
+I.click('Login');
+```
+
+If none found, CodeceptJS tries to find link or button containing that text. In case an image is clickable its `alt` attribute will be checked for text inclusion. Form buttons will also be searched by name.
+
+To narrow down the results you can specify a context in second parameter.
+
+```js
+I.click('Login', '.nav'); // search only in .nav
+I.click('Login', {css: 'footer'}); // search only in footer
+```
+
+> To skip guessing locator type pass in a strict locator. A locator starting with '#' or '.' is considered to be CSS. Locator starting with '//' or './/' is considered to be XPath.
+
+You are not limited to buttons and links. Any element can be found by passing in valid CSS or XPath:
+
+```js
+// click element by CSS
+I.click('#signup');
+// click element located by special test-id attribute
+I.click('//dev[@test-id="myid"]');
+```
+
+### Filling Fields
+
+Clicking the links is not what takes the most time during testing a web site. If your site consists only of links you can skip test automation. The most routine waste of time goes into the testing of forms. CodeceptJS provides several ways of doing that.
+
+Let's submit this sample form for a test:
+
+```html
+<form method="post" action="/update" id="update_form">
+     <label for="user_name">Name</label>
+     <input type="text" name="user[name]" id="user_name" />
+     <label for="user_email">Email</label>
+     <input type="text" name="user[email]" id="user_email" />
+     <label for="user_gender">Gender</label>
+     <select id="user_gender" name="user[gender]">
+          <option value="m">Male</option>
+          <option value="f">Female</option>
+     </select>
+     <input type="submit" name="submitButton" value="Update" />
+</form>
+```
+
+We need to fill in all those fields and click "Update" button. CodeceptJS matches form elements by their label, name, or by CSS or XPath locators.
+
+```js
+// we are using label to match user_name field
+I.fillField('Name', 'Miles');
+// we can use input name
+I.fillField('user[email]','miles@davis.com');
+// select element by label, choose option by text
+I.selectOption('Gender','Male');
+// click 'Update' button, found by text
+I.click('Update');
+```
+
+Alternative scenario:
+
+```js
+// we are using CSS
+I.fillField('#user_name', 'Miles');
+I.fillField('#user_email','miles@davis.com');
+// select element by label, option by value
+I.selectOption('#user_gender','m');
+// click 'Update' button, found by name
+I.click('submitButton', '#update_form');
+```
+
+To fill in sensitive data use `secret` function:
+
+```js
+I.fillField('password', secret('123456'));
+```
 
-> For most helpers basic actions like `amOnPage`, `fillField`, `click` are the same.
-Proceed to [Acceptance Testing Chapter](https://codecept.io/acceptance/) to learn how to use them.
+### Assertions
+
+In order to verify the expected behavior of a web application, a content should be checked.
+CodeceptJS provides built-in assertions for that. They start with `see` (or `dontSee`) prefix.
+
+The most general and common assertion is `see`, which checks visilibility of a text on a page:
+
+```js
+// Just a visible text on a page
+I.see('Hello');
+// text inside .msg element
+I.see('Hello', '.msg');
+// opposite
+I.dontSee('Bye');
+```
+
+You should provide a text as first argument and optionally a locator to search for a text in a context.
+
+You can check that specific element exists (or not) on a page, as it was described in [Locating Element](#locating-element) section.
+
+```js
+I.seeElement('.notice');
+I.dontSeeElement('.error');
+```
+
+Additional assertions:
+
+```js
+I.seeInCurrentUrl('/user/miles');
+I.seeInField('user[name]', 'Miles');
+I.seeInTitle('My Website');
+```
+
+To see all possible assertions see the helper's reference.
+
+### Grabbing
+
+Sometimes you need to retrieve a data from a page to use it in next steps of a scenario.
+Imagine, application generates a password and you want to ensure that user can login using this password.
+
+```js
+Scenario('login with generated password', async (I) => {
+  I.fillField('email', 'miles@davis.com');
+  I.click('Generate Password');
+  const password = await I.grabTextFrom('#password');
+  I.click('Login');
+  I.fillField('email', 'miles@davis.com');
+  I.fillField('password', password);
+  I.click('Log in!');
+  I.see('Hello, Miles');
+});
+```
+
+`grabTextFrom` action is used here to retrieve text from an element. All actions starting with `grab` prefix are expected to return data. In order to synchronize this step with a scenario you should pause test execution with `await` keyword of ES6. To make it work your test should be written inside a async function (notice `async` in its definition).
+
+```js
+Scenario('use page title', async (I) => {
+  // ...
+  const password = await I.grabTextFrom('#password');
+  I.fillField('password', password);
+});
+```
+
+### Waiting
+
+In modern web applications rendering is happen on client side.
+Sometimes that may cause delays. A test may fail while trying to click an element which has not appeared on a page yet.
+To handle this cases `wait*` methods introduced.
+
+```js
+I.waitForElement('#agree_button', 30); // secs
+// clicks a button only when it is visible
+I.click('#agree_button');
+```
+
+> ℹ See [helpers reference](https://codecept.io/reference) for a complete list of all available commands for a helper you use.
 
 ## How It Works
 
@@ -197,6 +410,76 @@ This can be configured in [screenshotOnFail Plugin](https://codecept.io/plugins/
 To see how the test was executed, use [stepByStepReport Plugin](https://codecept.io/plugins/#stepbystepreport). It saves a screenshot of each passed step and shows them in a nice slideshow.
 
 
+## Retries
+
+### Retry Step
+
+If you have a step which often fails you can retry execution for this single step.
+Use `retry()` function before an action to ask CodeceptJS to retry this step on failure:
+
+```js
+I.retry().see('Welcome');
+```
+
+If you'd like to retry step more than once pass the amount as parameter:
+
+```js
+I.retry(3).see('Welcome');
+```
+
+Additional options can be provided to retry so you can set the additional options (defined in [promise-retry](https://www.npmjs.com/package/promise-retry) library).
+
+
+```js
+// retry action 3 times waiting for 0.1 second before next try
+I.retry({ retries: 3, minTimeout: 100 }).see('Hello');
+
+// retry action 3 times waiting no more than 3 seconds for last retry
+I.retry({ retries: 3, maxTimeout: 3000 }).see('Hello');
+
+// retry 2 times if error with message 'Node not visible' happens
+I.retry({
+  retries: 2,
+  when: err => err.message === 'Node not visible'
+}).seeElement('#user');
+```
+
+Pass a function to `when` option to retry only when error matches the expected one.
+
+### Auto Retry
+
+You can auto-retry a failed step by enabling [retryFailedStep Plugin](https://codecept.io/plugins/#retryfailedstep).
+
+### Retry Scenario
+
+When you need to rerun scenarios few times just add `retries` option added to `Scenario` declaration.
+
+CodeceptJS implements retries the same way [Mocha do](https://mochajs.org#retry-tests);
+You can set number of a retries for a feature:
+
+```js
+Scenario('Really complex', (I) => {
+  // test goes here
+}).retry(2);
+
+// alternative
+Scenario('Really complex', { retries: 2 }, (I) => {});
+```
+
+This scenario will be restarted two times on a failure.
+
+### Retry Feature
+
+To set this option for all scenarios in a file, add retry to a feature:
+
+```js
+Feature('Complex JS Stuff').retry(3);
+```
+
+Every Scenario inside this feature will be rerun 3 times.
+You can make an exception for a specific scenario by passing `retries` option to a Scenario.
+
+
 ## Before
 
 Common preparation steps like opening a web page, logging in a user, can be placed in `Before` or `Background` hook:
@@ -258,7 +541,23 @@ within('.js-signup-form', () => {
 I.see('There were problems creating your account.');
 ```
 
-`within` can also work with [iframes](/acceptance/#iframes)
+`within` can also work with IFrames. Special `frame` locator is required to locate the iframe and get into its context.
+
+See example:
+
+```js
+within({frame: "#editor"}, () => {
+  I.see('Page');
+});
+```
+
+Nested IFrames can be set by passing array *(WebDriver, Nightmare & Puppeteer only)*:
+
+```js
+within({frame: [".content", "#editor"]}, () => {
+  I.see('Page');
+});
+```
 
 When running steps inside a within block will be shown with a shift:
 
@@ -293,102 +592,105 @@ I.say('This is blue', 'blue'); //blue is used
 I.say('This is by default'); //cyan is used
 ```
 
-## IntelliSense
+## Multiple Sessions
 
-If you are using Visual Studio Code or other IDE that supports TypeScript Definitions,
-you can generate step definitions with
-
-```sh
-codeceptjs def
-```
+CodeceptJS allows to run several browser sessions inside a test. This can be useful for testing communication between users inside a system, for instance in chats. To open another browser use `session()` function as shown in example:
 
-Now you should create `tsconfig.json` in your project root directory.
-
-```tsconfig.json
-{
-  "compilerOptions": {
-    "allowJs": true,
-  }
-}
+```js
+Scenario('test app', (I) => {
+  I.amOnPage('/chat');
+  I.fillField('name', 'davert');
+  I.click('Sign In');
+  I.see('Hello, davert');
+  session('john', () => {
+    // another session started
+    I.amOnPage('/chat');
+    I.fillField('name', 'john');
+    I.click('Sign In');
+    I.see('Hello, john');
+  });
+  // switching back to default session
+  I.fillField('message', 'Hi, john');
+  // there is a message from current user
+  I.see('me: Hi, john', '.messages');
+  session('john', () => {
+    // let's check if john received it
+    I.see('davert: Hi, john', '.messages');
+  });
+});
 ```
-but in usually case, this file has already generated when you execute `codeceptjs init`.
-
-Alternatively, you can include `/// <reference path="./steps.d.ts" />` into your test files 
-to get method autocompletion while writing tests.
-
-## Skipping
-
-Like in Mocha you can use `x` and `only` to skip tests or making a single test to run.
-
-* `xScenario` - skips current test
-* `Scenario.only` - executes only the current test
-
 
-## Retries
-
-### Retry Step
+`session` function expects a first parameter to be a name of a session. You can switch back to session by using the same name.
 
-If you have a step which often fails you can retry execution for this single step.
-Use `retry()` function before an action to ask CodeceptJS to retry this step on failure:
+You can override config for session by passing second parameter:
 
 ```js
-I.retry().see('Welcome');
+session('john', { browser: 'firefox' } , () => {
+  // run this steps in firefox
+  I.amOnPage('/');
+});
 ```
 
-If you'd like to retry step more than once pass the amount as parameter:
+or just start session without switching to it. Call `session` passing only its name:
 
 ```js
-I.retry(3).see('Welcome');
-```
+Scenario('test', (I) => {
+  // opens 3 additional browsers
+  session('john');
+  session('mary');
+  session('jane');
 
-Additional options can be provided to retry so you can set the additional options (defined in [promise-retry](https://www.npmjs.com/package/promise-retry) library).
+  I.amOnPage('/');
 
+  // switch to session by its name
+  session('mary', () => {
+    I.amOnPage('/login');
+  });
+}
+```
+`session` can return value which can be used in scenario:
 
 ```js
-// retry action 3 times waiting for 0.1 second before next try
-I.retry({ retries: 3, minTimeout: 100 }).see('Hello');
-
-// retry action 3 times waiting no more than 3 seconds for last retry
-I.retry({ retries: 3, maxTimeout: 3000 }).see('Hello');
-
-// retry 2 times if error with message 'Node not visible' happens
-I.retry({
-  retries: 2,
-  when: err => err.message === 'Node not visible'
-}).seeElement('#user');
+// inside async function
+const val = await session('john', () => {
+  I.amOnPage('/info');
+  return I.grabTextFrom({ css: 'h1' });
+});
+I.fillField('Description', val);
 ```
 
-Pass a function to `when` option to retry only when error matches the expected one.
+Function passed into session can use `I`, page objects, and any objects declared for the scenario.
+This function can also be declared as async (but doesn't work as generator).
 
-### Auto Retry
+Also, you can use `within` inside a session but you can't call session from inside `within`.
 
-You can auto-retry a failed step by enabling [retryFailedStep Plugin](https://codecept.io/plugins/#retryfailedstep).
 
-### Retry Scenario
+## IntelliSense
 
-When you need to rerun scenarios few times just add `retries` option added to `Scenario` declaration.
+If you are using Visual Studio Code or other IDE that supports TypeScript Definitions,
+you can generate step definitions with
 
-CodeceptJS implements retries the same way [Mocha do](https://mochajs.org#retry-tests);
-You can set number of a retries for a feature:
+```sh
+codeceptjs def
+```
 
-```js
-Scenario('Really complex', (I) => {
-  // test goes here
-}).retry(2);
+Now you should create `jsconfig.json` in your project root directory.
 
-// alternative
-Scenario('Really complex', { retries: 2 }, (I) => {});
+```jsconfig.json
+{
+  "compilerOptions": {
+    "allowJs": true,
+  }
+}
 ```
+but in usually case, this file has already generated when you execute `codeceptjs init`.
 
-This scenario will be restarted two times on a failure.
-
-### Retry Feature
+Alternatively, you can include `/// <reference path="./steps.d.ts" />` into your test files
+to get method autocompletion while writing tests.
 
-To set this option for all scenarios in a file, add retry to a feature:
+## Skipping
 
-```js
-Feature('Complex JS Stuff').retry(3);
-```
+Like in Mocha you can use `x` and `only` to skip tests or making a single test to run.
 
-Every Scenario inside this feature will be rerun 3 times.
-You can make an exception for a specific scenario by passing `retries` option to a Scenario.
+* `xScenario` - skips current test
+* `Scenario.only` - executes only the current test

package/docs/bdd.md

@@ -138,11 +138,12 @@ This scenarios are nice as live documentation but they do not test anything yet.
 Steps can be defined by executing `gherkin:snippets` command:
 
 ```bash
-codeceptjs gherkin:snippets [--path=PATH]
+codeceptjs gherkin:snippets [--path=PATH] [--feature=PATH]
 ```
 
-This will produce code templates for all undefined steps in all feature files of this suite.
-It will also place stub definitions into `step_definitions/steps.js` file. However, you may also target a specific file to place all undefined steps in. This file must exist and be placed in the gherkin steps in the current config.
+This will produce code templates for all undefined steps in the .feature files.
+By default, it will scan all of the .feature files specified in the gherkin.features section of the config and produce code templates for all undefined steps. If the `--feature` option is specified, it will scan the specified .feature file(s).
+The stub definitions by default will be placed into the first file specified in the gherkin.steps section of the config. However, you may also use `--path` to specify a specific file in which to place all undefined steps. This file must exist and be in the gherkin.steps array of the config.
 Our next step will be to define those steps and transforming feature-file into a valid test.
 
 ### Step Definitions

package/docs/build/Nightmare.js

@@ -81,6 +81,9 @@ class Nightmare extends Helper {
   static _config() {
     return [
       { name: 'url', message: 'Base url of site to be tested', default: 'http://localhost' },
+      {
+        name: 'show', message: 'Show browser window', default: true, type: 'confirm',
+      },
     ];
   }
 

package/docs/build/Polly.js

@@ -58,7 +58,7 @@ class Polly extends Helper {
 
   // Start mocking network requests/responses
   async _startMocking(title = 'Test') {
-    if (!this.helpers && !this.helpers.Puppeteer) {
+    if (!(this.helpers && this.helpers.Puppeteer)) {
       throw new Error('Puppeteer is the only supported helper right now');
     }
     await this._connectPuppeteer(title);
@@ -67,20 +67,21 @@ class Polly extends Helper {
   // Connect Puppeteer helper to mock future requests.
   async _connectPuppeteer(title) {
     const adapter = require('@pollyjs/adapter-puppeteer');
-
     PollyJS.register(adapter);
+
     const { page } = this.helpers.Puppeteer;
+    if (!page) {
+      throw new Error('Looks like, there is no open tab');
+    }
     await page.setRequestInterception(true);
 
     this.polly = new PollyJS(title, {
+      mode: 'passthrough',
       adapters: ['puppeteer'],
       adapterOptions: {
         puppeteer: { page },
       },
     });
-
-    // By default let pass through all network requests
-    if (this.polly) this.polly.server.any().passthrough();
   }
 
   /**
@@ -90,6 +91,7 @@ class Polly extends Helper {
    * I.mockRequest('GET', '/api/users', 200);
    * I.mockRequest('ANY', '/secretsRoutes/*', 403);
    * I.mockRequest('POST', '/secrets', { secrets: 'fakeSecrets' });
+   * I.mockRequest('GET', '/api/users/1', 404, 'User not found');
    * ```
    *
    * Multiple requests
@@ -97,17 +99,27 @@ class Polly extends Helper {
    * ```js
    * I.mockRequest('GET', ['/secrets', '/v2/secrets'], 403);
    * ```
+   * @param {string} method request method. Can be `GET`, `POST`, `PUT`, etc or `ANY`.
+   * @param {string|array} oneOrMoreUrls url(s) to mock. Can be exact URL, a pattern, or an array of URLs.
+   * @param {number|string|object} dataOrStatusCode status code when number provided. A response body otherwise
+   * @param {string|object} additionalData response body when a status code is set by previous parameter.
+   *
    */
-  async mockRequest(method, oneOrMoreUrls, dataOrStatusCode) {
+  async mockRequest(method, oneOrMoreUrls, dataOrStatusCode, additionalData = null) {
     await this._checkAndStartMocking();
+    const puppeteerConfigUrl = this.helpers.Puppeteer && this.helpers.Puppeteer.options.url;
+
     const handler = this._getRouteHandler(
       method,
       oneOrMoreUrls,
-      this.options.url,
+      this.options.url || puppeteerConfigUrl,
     );
 
     if (typeof dataOrStatusCode === 'number') {
       const statusCode = dataOrStatusCode;
+      if (additionalData) {
+        return handler.intercept((_, res) => res.status(statusCode).send(additionalData));
+      }
       return handler.intercept((_, res) => res.sendStatus(statusCode));
     }
     const data = dataOrStatusCode;
@@ -148,16 +160,18 @@ class Polly extends Helper {
    */
   async stopMocking() {
     if (!this._checkIfMockingStarted()) return;
-
     await this._disconnectPuppeteer();
-    await this.polly.flush();
-    await this.polly.stop();
-    this.polly = undefined;
+
+    const { polly } = this;
+    if (!polly) return;
+    await polly.flush();
+    await polly.stop();
+    delete this.polly;
   }
 
   async _disconnectPuppeteer() {
     const { page } = this.helpers.Puppeteer;
-    await page.setRequestInterception(false);
+    if (page) await page.setRequestInterception(false);
   }
 }