codeceptjs 2.4.3 → 2.6.2

package/docs/locators.md

@@ -12,6 +12,8 @@ CodeceptJS provides flexible strategies for locating elements:
 * [Locator Builder](#locator-builder)
 * [ID locators](#id-locators): by CSS id or by accessibility id
 * [Custom Locator Strategies](#custom-locators): by data attributes or whatever you prefer.
+* [Shadow DOM](/shadow): to access shadow dom elements
+* [React](/react): to access React elements by component names and props
 
 Most methods in CodeceptJS use locators which can be either a string or an object.
 

package/docs/playwright.md

@@ -0,0 +1,306 @@
+---
+permalink: /playwright
+title: Testing with Playwright
+---
+
+# Testing with Playwright <Badge text="Since 2.5" type="warning"/>
+
+Playwright is a Node library to automate the [Chromium](https://www.chromium.org/Home), [WebKit](https://webkit.org/) and [Firefox](https://www.mozilla.org/en-US/firefox/new/) browsers with a single API. It enables **cross-browser** web automation that is **ever-green**, **capable**, **reliable** and **fast**.
+
+Playwright was built similarly to [Puppeteer](https://github.com/puppeteer/puppeteer), using its API and so is very different in usage. However, Playwright has cross browser support with better design for test automaiton.
+
+Take a look at a sample test:
+
+```js
+I.amOnPage('https://github.com');
+I.click('Sign in', '//html/body/div[1]/header');
+I.see('Sign in to GitHub', 'h1');
+I.fillField('Username or email address', 'something@totest.com');
+I.fillField('Password', '123456');
+I.click('Sign in');
+I.see('Incorrect username or password.', '.flash-error');
+```
+
+It's readable and simple and working using Playwright API!
+
+## Setup
+
+To start you need CodeceptJS with Playwright packages installed
+
+```bash
+npm install codeceptjs playwright@^0.12.1 --save
+```
+
+Or see [alternative installation options](http://codecept.io/installation/)
+
+> If you already have CodeceptJS project, just install `playwright` package and enable a helper it in config.
+
+And a basic project initialized
+
+```sh
+npx codeceptjs init
+```
+
+You will be asked for a Helper to use, you should select Playwright and provide url of a website you are testing.
+
+## Configuring
+
+Make sure `Playwright` helper is enabled in `codecept.conf.js` config:
+
+```js
+{ // ..
+  helpers: {
+    Playwright: {
+      url: "http://localhost",
+      show: true,
+      browser: 'chromium'
+    }
+  }
+  // ..
+}
+```
+
+> Turn off the `show` option if you want to run test in headless mode.
+> If you don't specify the browser here, `chromium` will be used. Possible browsers are: `chromium`, `firefox` and `webkit`
+
+Playwright uses different strategies to detect if a page is loaded. In configuration use `waitForNavigation` option for that:
+
+When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
+- `load` - consider navigation to be finished when the load event is fired.
+- `domcontentloaded` - consider navigation to be finished when the DOMContentLoaded event is fired.
+- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
+- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.
+
+```js
+  helpers: {
+    Playwright: {
+      url: "http://localhost",
+      show: true,
+      browser: 'chromium',
+      waitForNavigation: "networkidle0"
+    }
+  }
+```
+
+When a test runs faster than application it is recommended to increase `waitForAction` config value.
+It will wait for a small amount of time (100ms) by default after each user action is taken.
+
+> ▶ More options are listed in [helper reference](http://codecept.io/helpers/Playwright/).
+
+## Writing Tests
+
+Additional CodeceptJS tests should be created with `gt` command:
+
+```sh
+npx codeceptjs gt
+```
+
+As an example we will use `ToDoMvc` app for testing.
+
+### Actions
+
+Tests consist with a scenario of user's action taken on a page. The most widely used ones are:
+
+* `amOnPage` - to open a webpage (accepts relative or absolute url)
+* `click` - to locate a button or link and click on it
+* `fillField` - to enter a text inside a field
+* `selectOption`, `checkOption` - to interact with a form
+* `wait*` to wait for some parts of page to be fully rendered (important for testing SPA)
+* `grab*` to get values from page sources
+* `see`, `dontSee` - to check for a text on a page
+* `seeElement`, `dontSeeElement` - to check for elements on a page
+
+> ℹ  All actions are listed in [Playwright helper reference](http://codecept.io/helpers/Playwright/).*
+
+All actions which interact with elements can use **[CSS or XPath locators](https://codecept.io/locators/#css-and-xpath)**. Actions like `click` or `fillField` can locate elements by their name or value on a page:
+
+```js
+// search for link or button
+I.click('Login');
+// locate field by its label
+I.fillField('Name', 'Miles');
+// we can use input name
+I.fillField('user[email]','miles@davis.com');
+```
+
+You can also specify the exact locator type with strict locators:
+
+```js
+I.click({css: 'button.red'});
+I.fillField({name: 'user[email]'},'miles@davis.com');
+I.seeElement({xpath: '//body/header'});
+```
+
+### Interactive Pause
+
+It's easy to start writing a test if you use [interactive pause](/basics#debug). Just open a web page and pause execution.
+
+```js
+Feature('Sample Test');
+
+Scenario('open my website', (I) => {
+  I.amOnPage('http://todomvc.com/examples/react/');
+  pause();
+});
+```
+
+This is just enough to run a test, open a browser, and think what to do next to write a test case.
+
+When you execute such test with `codeceptjs run` command you may see the browser is started
+
+```
+npx codeceptjs run --steps
+```
+
+After a page is opened a full control of a browser is given to a terminal. Type in different commands such as `click`, `see`, `fillField` to write the test. A successful commands will be saved to `./output/cli-history` file and can be copied into a test.
+
+A complete ToDo-MVC test may look like:
+
+```js
+Feature('ToDo');
+
+Scenario('create todo item', (I) => {
+  I.amOnPage('http://todomvc.com/examples/react/');
+  I.dontSeeElement('.todo-count');
+  I.fillField('What needs to be done?', 'Write a guide');
+  I.pressKey('Enter');
+  I.see('Write a guide', '.todo-list');
+  I.see('1 item left', '.todo-count');
+});
+```
+
+### Grabbers
+
+If you need to get element's value inside a test you can use `grab*` methods. They should be used with `await` operator inside `async` function:
+
+```js
+const assert = require('assert');
+Scenario('get value of current tasks', async (I) => {
+  I.createTodo('do 1');
+  I.createTodo('do 2');
+  let numTodos = await I.grabTextFrom('.todo-count strong');
+  assert.equal(2, numTodos);
+});
+```
+
+### Within
+
+In case some actions should be taken inside one element (a container or modal window or iframe) you can use `within` block to narrow the scope.
+Please take a note that you can't use within inside another within in Playwright helper:
+
+```js
+within('.todoapp', () => {
+  I.createTodo('my new item');
+  I.see('1 item left', '.todo-count');
+  I.click('.todo-list input.toggle');
+});
+I.see('0 items left', '.todo-count');
+```
+
+> [▶ Learn more about basic commands](/basics#writing-tests)
+
+CodeceptJS allows you to implement custom actions like `I.createTodo` or use **PageObjects**. Learn how to improve your tests in [PageObjects](http://codecept.io/pageobjects/) guide.
+
+## Multi Session Testing
+
+TO launch additional browser context (or incognito window) use `session` command.
+
+```js
+Scenario('I try to open this site as anonymous user', () => {
+  I.amOnPage('/');
+  I.dontSee('Agree to cookies');
+  session('anonymous user', () => {
+    I.amOnPage('/');
+    I.see('Agree to cookies');
+  });
+})
+```
+
+> ℹ Learn more about [multi-session testing](/basics/#multiple-sessions)
+
+## Device Emulation
+
+Playwright can emulate browsers of mobile devices. Instead of paying for expensive devices for mobile tests you can adjust Playwright settings so it could emulate mobile browsers on iPhone, Samsung Galaxy, etc.
+
+Device emulation can be enabled in CodeceptJS globally in a config or per session.
+
+Playwright contains a [list of predefined devices](https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts) to emulate, for instance this is how you can enable iPhone 6 emulation for all tests:
+
+```js
+const { devices } = require('playwright');
+
+helpers: {
+  Playwright: {
+    // regular config goes here
+    emulate: devices['iPhone 6'],
+  }
+}
+```
+To adjust browser settings you can pass [custom options](https://github.com/microsoft/playwright/blob/v0.12.1/docs/api.md#browsernewcontextoptions)
+
+```js
+helpers: {
+  Playwright: {
+    // regular config goes here
+    // put on mobile device
+    emulate: { isMobile: true, deviceScaleFactor: 2 }
+  }
+}
+```
+
+To enable device emulation for a specific test, create an additional browser session and pass in config as a second parameter:
+
+```js
+const { devices } = require('playwright');
+
+Scenario('website looks nice on iPhone', () => {
+  session('mobile user', devices['iPhone 6'], () => {
+    I.amOnPage('/');
+    I.see('Hello, iPhone user!')
+  })
+});
+```
+
+## Extending
+
+Playwright has a very [rich and flexible API](https://github.com/microsoft/playwright/blob/v0.12.1/docs/api.md). Sure, you can extend your test suites to use the methods listed there. CodeceptJS already prepares some objects for you and you can use them from your you helpers.
+
+Start with creating an `MyPlaywright` helper using `generate:helper` or `gh` command:
+
+```sh
+npx codeceptjs gh
+```
+
+Then inside a Helper you can access `Playwright` helper of CodeceptJS.
+Let's say you want to create `I.grabDimensionsOfCurrentPage` action. In this case you need to call `evaluate` method of `page` object
+
+```js
+// inside a MyPlaywright helper
+async grabDimensionsOfCurrentPage() {
+  const { page } = this.helpers.Playwright;
+  await page.goto('https://www.example.com/');
+  return page.evaluate(() => {
+    return {
+      width: document.documentElement.clientWidth,
+      height: document.documentElement.clientHeight,
+      deviceScaleFactor: window.devicePixelRatio
+    }
+  })
+}
+```
+
+The same way you can also access `browser` object to implement more actions or handle events. For instance, you want to set the permissions, you can approach it with:
+
+```js
+// inside a MyPlaywright helper
+async setPermissions() {
+  const { browser } = this.helpers.Playwright;
+  const context = browser.defaultContext()
+  return context.setPermissions('https://html5demos.com', ['geolocation']);
+}
+```
+
+> [▶ Learn more about BrowserContext](https://github.com/microsoft/playwright/blob/v0.12.1/docs/api.md#class-browsercontext)
+
+> [▶ Learn more about Helpers](http://codecept.io/helpers/)
+

package/docs/plugins.md

@@ -305,6 +305,109 @@ Scenario('login', async (I, login) => {
 
 -   `config`  
 
+## commentStep
+
+Add descriptive nested steps for your tests:
+
+```js
+Scenario('project update test', async (I) => {
+  __`Given`;
+  const projectId = await I.have('project');
+
+  __`When`;
+  projectPage.update(projectId, { title: 'new title' });
+
+  __`Then`;
+  projectPage.open(projectId);
+  I.see('new title', 'h1');
+})
+```
+
+Steps prefixed with `__` will be printed as nested steps in `--steps` output:
+
+      Given
+        I have "project"
+      When
+        projectPage update
+      Then
+        projectPage open
+        I see "new title", "h1"
+
+Also those steps will be exported to allure reports.
+
+This plugin can be used
+
+### Config
+
+-   `enabled` - (default: false) enable a plugin
+-   `regusterGlobal` - (default: false) register `__` template literal function globally. You can override function global name by providing a name as a value.
+
+### Examples
+
+Registering `__` globally:
+
+```js
+plugins: {
+  commentStep: {
+    enabled: true,
+    registerGlobal: true
+  }
+}
+```
+
+Registering `Step` globally:
+
+```js
+plugins: {
+  commentStep: {
+    enabled: true,
+    registerGlobal: 'Step'
+  }
+}
+```
+
+Using only local function names:
+
+```js
+plugins: {
+  commentStep: {
+    enabled: true
+  }
+}
+```
+
+Then inside a test import a comment function from a plugin.
+For instance, you can prepare Given/When/Then functions to use them inside tests:
+
+```js
+// inside a test
+const step = codeceptjs.container.plugins('commentStep');
+
+const Given = () => step`Given`;
+const When = () => step`When`;
+const Then = () => step`Then`;
+```
+
+Scenario('project update test', async (I) => {
+  Given();
+  const projectId = await I.have('project');
+
+  When();
+  projectPage.update(projectId, { title: 'new title' });
+
+  Then();
+  projectPage.open(projectId);
+  I.see('new title', 'h1');
+});
+
+```
+
+```
+
+### Parameters
+
+-   `config`  
+
 ## customLocator
 
 Creates a [custom locator][3] by using special attributes in HTML.

package/docs/reports.md

@@ -199,6 +199,18 @@ Allure reports can also be generated for `dry-run` command. So you can get the f
 npx codeceptjs dry-run --debug -p allure
 ```
 
+## ReportPortal
+
+Allure is a great reportin tool, however, if you are running tests on different machines it is hard to merge its XML result files to build a proper report. So, for enterprise grade reporting we recommend using [ReportPortal](https://reportportal.io).
+
+![](https://camo.githubusercontent.com/6550c0365f1d0ce1e29c53f1860b12957d1fc529/68747470733a2f2f692e6962622e636f2f516d353247306e2f53637265656e73686f742d323031392d30342d31312d61742d31352d35372d34302e706e67)
+
+[ReportPortal](https://reportportal.io) is open-source self-hosted service for aggregating test execution reports.
+Think of it as Kibana but for test reports.
+
+Use official [CodeceptJS Agent for ReportPortal](https://github.com/reportportal/agent-js-codecept/) to start publishing your test results.
+
+
 ## XML
 
 Use default xunit reporter of Mocha to print xml reports. Provide `--reporter xunit` to get the report to screen.

package/docs/shadow.md

@@ -0,0 +1,68 @@
+---
+permalink: /shadow
+title: Locating Shadow Dom Elements
+---
+
+# Locating Shadow Dom Elements
+
+> ℹ Shadow DOM locators is supported only in WebDriver helper
+
+Shadow DOM is one of the key browser features that make up web components. Web components are a really great way to build reusable elements, and are able to scale all the way up to complete web applications. Style encapsulation, the feature that gives shadow DOM it's power, has been a bit of a pain when it comes to E2E or UI testing. Things just got a little easier though, as CodeceptJS introduced built-in support for shadow DOM via locators of type `shadow`. Let's dig into what they're all about.
+
+Generated HTML code may often look like this (ref: [Salesforce's Lighting Web Components](https://github.com/salesforce/lwc)):
+
+```js
+<body>
+  <my-app>
+    <recipe-hello>
+      <button>Click Me!</button>
+    </recipe-hello>
+    <recipe-hello-binding>
+      <ui-input>
+        <input type="text" class="input">
+      </ui-input>
+    </recipe-hello-binding>
+  </my-app>
+</body>
+```
+
+This uses custom elements, `my-app`, `recipe-hello`, `recipe-hello-binding` and `ui-input`. It's quite common that clickable elements are not actual `a` or `button` elements but custom elements. This way `I.click('Click Me!');` won't work, as well as `fillField('.input', 'value)`. Finding a correct locator for such cases turns to be almost impossible until `shadow` element support is added to CodeceptJS.
+
+## Locate Shadow Dom
+
+For Web Components or [Salesforce's Lighting Web Components](https://github.com/salesforce/lwc) with Shadow DOM's, a special `shadow` locator is available. It allows to select an element by its shadow dom sequences and sequences are defined as an Array of `elements`. Elements defined in the array of `elements` must be in the ordered the shadow elements appear in the DOM.
+
+```js
+{ shadow: ['my-app', 'recipe-hello', 'button'] }
+{ shadow: ['my-app', 'recipe-hello-binding', 'ui-input', 'input.input'] }
+```
+
+In WebDriver, you can use shadow locators in any method where locator is required.
+
+For example, to fill value in `input` field or to click the `Click Me!` button, in above HTML code:
+
+```js
+I.fillField({ shadow: ['my-app', 'recipe-hello-binding', 'ui-input', 'input.input'] }, 'value');
+I.click({ shadow: ['my-app', 'recipe-hello', 'button'] });
+```
+
+## Example
+
+```js
+Feature('Shadow Dom Locators');
+
+Scenario('should fill input field within shadow elements', I => {
+
+  // navigate to LWC webpage containing shadow dom
+  I.amOnPage('https://recipes.lwc.dev/');
+
+  // click Click Me! button
+  I.click({ shadow: ['my-app', 'recipe-hello', 'button'] });
+
+  // fill the input field
+  I.fillField({ shadow: ['my-app', 'recipe-hello-binding', 'ui-input', 'input.input'] }, 'value');
+
+});
+
+
+```

package/docs/visual.md

@@ -112,79 +112,6 @@ MisMatch Percentage Calculated is 2.85
 1) `seeVisualDiff` which can be used to compare two images and calculate the misMatch percentage.
 2) `seeVisualDiffForElement` which can be used to compare elements on the two images and calculate misMatch percentage.
 
-## Using Visual Knight
-
-Visual Knight is a SaaS product which strongly supports CodeceptJS with multiple use cases. It provides an user interface to handle mismatches, statistics and more. It was designed to support Designer, Product Owner and other roles which are not familiar with coding and all this tools. All captured images are saved in a secure cloud system to not mess up your git repository.
-
-### Setup
-
-Create an account at [Visual Knight](https://www.visual-knight.io) and install the npm package
-
-```
-npm install @visual-knight/codeceptjs -D
-```
-
-### Configuring
-
-```json
-{
-    "helpers": {
-        "VisualKnight": {
-            "require": "@visual-knight/codeceptjs",
-            "key": "YOUR_API_KEY",
-            "project": "YOUR_PROJECT_ID OR PROJECT_NAME"
-        }
-    }
-}
-```
-
-### Usage
-
-```javascript
-/**
- * @param testName {string} Is provided to visual knight (must be unique)
- * @param options {ScreenshotOptions} Contains additional settings
- */
-I.compareFullpageScreenshot(testName, options)
-/**
- * @param testName {string} Is provided to visual knight (must be unique)
- * @param options {ScreenshotOptions} Contains additional settings
- */
-I.compareViewportScreenshot(testName, options)
-/**
- * @param cssSelector {string} Is provided to visual knight
- * @param testName {string} Is provided to visual knight (must be unique)
- * @param options {ScreenshotOptions} Contains additional settings
- */
-I.compareElementScreenshot(cssSelector, testName, options)
-
-/*
-ScreenshotOptions {
-  hide?: string[] // Array of css selectors which gets hidden by "opacity: 0",
-  remove?: string[] // Array of css selectors which gets hidden by "display: none",
-  additional?: object // Data is saved as relation to the variation. (Future: can be used for filtering)
-}
-*/
-```
-
-> You can find the latest documentation here [CodeceptJS helper page](https://doc.visual-knight.io/adapters/codeceptjs)
-
-### Example
-
-Lets consider visual testing for [CodeceptJS Home](http://codecept.io)
-
-```js
-Feature('To test screen comparison with Visual Knight Example test');
-
-Scenario('Compare CodeceptIO Home Page @visual-test', async (I, adminPage) => {
-    I.amOnPage("/");
-    I.compareFullpageScreenshot("CodeceptIO Home Page")
-});
-```
-
-Depending of your configuration this test will fail if no baseline exists and log the link to the image to accept or automatically accept the first run as baseline.
-> You can accept the first image as baseline automatically via ```autoBaseline: true``` _default is false_
-
 ## Using Applitools
 
 Applitools helps Test Automation engineers, DevOps, and FrontEnd Developers continuously test and validate visually perfect mobile, web, and native apps. Now it can be used with CodeceptJS.

package/docs/webapi/forceClick.mustache

@@ -0,0 +1,27 @@
+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'});
+```
+
+@param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.

package/docs/webapi/seeInPopup.mustache

@@ -0,0 +1,7 @@
+Checks that the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`, contains the
+given string.
+
+```js
+I.seeInPopup('Popup text');
+```
+@param {string} text value to check.

package/docs/webapi/setCookie.mustache

@@ -1,7 +1,15 @@
-Sets a cookie.
+Sets cookie(s).
+
+Can be a single cookie object or an array of cookies:
 
 ```js
 I.setCookie({name: 'auth', value: true});
+
+// as array
+I.setCookie([
+  {name: 'auth', value: true},
+  {name: 'agree', value: true}
+]);
 ```
 
-@param {object} cookie a cookie object.
+@param {object|array} cookie a cookie object or array of cookie objects.

package/docs/webapi/type.mustache

@@ -0,0 +1,12 @@
+
+Types out the given string or the array of keys provided.
+_Note:_ Should only be used when using [`fillField`](#fillfield) 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']);
+```
+
+@param {string|string[]} key or array of keys to type.