codeceptjs 3.5.12-beta.3 → 3.5.12-beta.5

package/docs/typescript.md

@@ -0,0 +1,180 @@
+---
+permalink: /typescript
+title: TypeScript
+---
+
+# TypeScript
+
+CodeceptJS supports [type declaration](https://github.com/codeceptjs/CodeceptJS/tree/master/typings) for [TypeScript](https://www.typescriptlang.org/). It means that you can write your tests in TS. Also, all of your custom steps can be written in TS
+
+# Why TypeScript?
+
+With the TypeScript writing CodeceptJS tests becomes much easier. If you configure TS properly in your project as well as your IDE, you will get the following features:
+- [Autocomplete (with IntelliSense)](https://code.visualstudio.com/docs/editor/intellisense) - a tool that streamlines your work by suggesting when you typing what function or property which exists in a class, what arguments can be passed to that method, what it returns, etc.
+Example:
+
+![Auto Complete](/img/Auto_comlete.gif)
+
+- To show additional information for a step in a test. Example:
+
+![Quick Info](/img/Quick_info.gif)
+
+- Checks types - thanks to TypeScript support in CodeceptJS now allow to tests your tests. TypeScript can prevent some errors:
+  - invalid type of variables passed to function;
+  - calls no-exist method from PageObject or `I` object;
+  - incorrectly used CodeceptJS features;
+
+
+## Getting Started <Badge text="Since 3.3.5" type="warning"/>
+
+CodeceptJS can initialize tests as a TypeScript project.
+When starting a new project with a standard installation via 
+
+```
+npx codeceptjs init
+``` 
+Then select TypeScript as the first question:
+
+```
+? Do you plan to write tests in TypeScript? Yes
+```
+
+Then a config file and new tests will be created in TypeScript format.
+
+If a config file is set in TypeScript format (`codecept.conf.ts`) package `ts-node` will be used to run tests. 
+
+## Promise-Based Typings
+
+By default, CodeceptJS tests are written in synchronous mode. This is a regular CodeceptJS test:
+
+```js
+I.amOnPage('/')
+I.click('Login')
+I.see('Hello!')
+```
+
+Even thought we don't see any `await`, those commands are executed synchronously, one by one.
+All methods of `I` object actually return promise and TypeScript linter requires to use `await` operator for those promises.
+To trick TypeScript and allow writing tests in CodeceptJS manner we create typings where `void` is returned instead of promises. This way linter won't complain on async code without await, as no promise is returned. 
+
+Our philosophy here is: use `await` only when it is actually needed, don't add visual mess to your code prefixing each line with `await`. However, you might want to get a better control of your tests and follow TypeScript conventions.
+This is why you might want to **enable promise-based typings**.
+
+A previous test should be rewritten with `await`s:
+
+```js
+await I.amOnPage('/')
+await I.click('Login')
+await I.see('Hello!')
+```
+
+Using `await` explicitly provides a beter control of execution flow. Some CodeceptJS users report that they increased stability of tests by adopting `await` for all CodeceptJS commands in their codebase.
+
+If you select to use promise-based typings, type definitions will be generated so all actions to return a promise. 
+Otherwise they will still return promises but it won't be relfected in type definitions.
+
+To introduce promise-based typings into a current project edit `codecept.conf.ts`:
+
+```ts
+fullPromiseBased: true;
+```
+
+and rebuild type definitions with
+
+```
+npx codeceptjs def
+```
+
+## Types for custom helper or page object
+
+If you want to get types for your [custom helper](https://codecept.io/helpers/#configuration), you can add their automatically with CodeceptJS command `npx codeceptjs def`.
+
+For example, if you add the new step `printMessage` for your custom helper like this:
+```js
+// customHelper.ts
+export class CustomHelper extends Helper {
+  printMessage(msg: string) {
+    console.log(msg)
+  }
+}
+
+```
+
+Then you need to add this helper to your `codecept.conf.js` like in this [docs](https://codecept.io/helpers/#configuration).
+And then run the command `npx codeceptjs def`.
+
+As result our `steps.d.ts` file will be updated like this:
+```ts
+/// <reference types='codeceptjs' />
+type CustomHelper = import('./CustomHelper');
+
+declare namespace CodeceptJS {
+  interface SupportObject { I: I }
+  interface Methods extends Puppeteer, CustomHelper {}
+  interface I extends WithTranslation<Methods> {}
+  namespace Translation {
+    interface Actions {}
+  }
+}
+```
+
+And now you can use autocomplete on your test.
+
+Generation types for PageObject looks like for a custom helper, but `steps.d.ts` will look like:
+```ts
+/// <reference types='codeceptjs' />
+type loginPage = typeof import('./loginPage');
+type homePage = typeof import('./homePage');
+type CustomHelper = import('./CustomHelper');
+
+declare namespace CodeceptJS {
+  interface SupportObject { I: I, loginPage: loginPage, homePage: homePage }
+  interface Methods extends Puppeteer, CustomHelper {}
+  interface I extends WithTranslation<Methods> {}
+  namespace Translation {
+    interface Actions {}
+  }
+}
+```
+
+## Types for custom strict locators
+
+You can define [custom strict locators](https://codecept.io/locators/#custom-strict-locators) that can be used in all methods taking a locator (parameter type `LocatorOrString`).
+
+Example: A custom strict locator with a `data` property, which can be used like this:
+
+```ts
+I.click({ data: 'user-login' });
+```
+
+In order to use the custom locator in TypeScript code, its type shape needs to be registered in the interface `CustomLocators` in your `steps.d.ts` file:
+
+```ts
+/// <reference types='codeceptjs' />
+...
+
+declare namespace CodeceptJS {
+  ...
+
+  interface CustomLocators {
+    data: { data: string };
+  }
+}
+```
+
+The property keys used in the `CustomLocators` interface do not matter (only the *types* of the interface properties are used). For simplicity it is recommended to use the name that is also used in your custom locator itself.
+
+You can also define more complicated custom locators with multiple (also optional) properties:
+
+```ts
+/// <reference types='codeceptjs' />
+...
+
+declare namespace CodeceptJS {
+  ...
+
+  interface CustomLocators {
+    data: { data: string, value?: number, flag?: boolean };
+  }
+}
+```

package/docs/ui.md

@@ -0,0 +1,59 @@
+---
+title: CodeceptUI
+permalink: /ui
+---
+
+
+<img src="/img/codeceptui.png" alt="CodeceptUI" style="width: 100%; border-radius: 5px; box-shadow: 0px 5px 10px rgba(0,0,0,0.1)" />
+
+
+## CodeceptUI
+
+CodeceptJS has an interactive, graphical test runner. We call it CodeceptUI. It works in your browser and helps you to manage your tests.
+
+CodeceptUI can be used for
+
+* running tests by groups or single
+* get test reports
+* review tests
+* edit tests and page objects
+* write new tests
+* reuse one browser session accross multiple test runs
+* easily switch to headless/headful mode
+
+
+![](https://user-images.githubusercontent.com/220264/93860826-4d5fbc80-fcc8-11ea-99dc-af816f3db466.png)
+
+## Installation
+
+CodeceptUI is already installed with `create-codeceptjs` command but you can install it manually via:
+
+```
+npm i @codeceptjs/ui --save
+```
+
+## Usage
+
+To start using CodeceptUI you need to have CodeceptJS project with a few tests written.
+If CodeceptUI was installed by `create-codecept` command it can be started with:
+
+```
+npm run codeceptjs:ui
+```
+
+CodeceptUI can be started in two modes:
+
+* **Application** mode - starts Electron application in a window. Designed for desktop systems.
+* **Server** mode - starts a webserver. Deigned for CI systems.
+
+To start CodeceptUI in application mode:
+
+```
+npx codecept-ui --app
+```
+
+To start CodeceptUI in server mode:
+
+```
+npx codecept-ui
+```

package/docs/videos.md

@@ -0,0 +1,28 @@
+---
+permalink: /videos
+layout: Section
+sidebar: false
+title: Videos
+editLink: false
+---
+
+> Add your own videos to our [Wiki Page](https://github.com/codeceptjs/CodeceptJS/wiki/Videos)
+[![](http://i3.ytimg.com/vi/BRMWstiOTks/maxresdefault.jpg)](https://www.youtube.com/watch?v=BRMWstiOTks)
+
+## [An Introduction, Getting started and working with CodeceptJS & Puppeteer (EAWeekend)](https://www.youtube.com/watch?v=BRMWstiOTks)
+
+## [CodeceptJS Official YouTube Channel](https://www.youtube.com/channel/UCEs4030bmtonyDhTHEXa_2g)
+
+## [Introductory Videos](https://www.youtube.com/watch?v=FPFG1rBNJ64&list=PLcFXthgti9Lt4SjSvL1ALDg6dOeTC0TvT)
+
+Free educational videos provided by our community member **[@ontytoom](http://github.com/ontytoom)**.
+
+1. [Installation](https://www.youtube.com/watch?v=FPFG1rBNJ64)
+1. [Creating a Test](https://www.youtube.com/watch?v=mdQZjL3h9d0)
+1. [Using Page Objects](https://www.youtube.com/watch?v=s677_6VctjQ)
+
+## [Practical E2E Testing with CodeceptJS](https://www.udemy.com/practical-e2e-testing-with-codeceptjs/)
+
+Udemy course by Luke Beilharz
+
+

package/docs/visual.md

@@ -0,0 +1,202 @@
+---
+permalink: /visual
+title: Visual Testing
+---
+
+# Visual Testing
+
+How does one test if the UI being rendered appears correctly to the users or how to test if each UI element appears in the right position and size? The traditional way to test the UI of the application has always been manually, which is time consuming.
+
+Visual testing with help of CodeceptJS will help in improving such use cases for the QA folks.
+
+By default CodeceptJS uses [WebDriver](/helpers/WebDriver/) helper and **Selenium** to automate browser. It is also capable of taking screenshots of the application and this could be used for visual testing.
+
+Currently there are two helpers available for Visual testing with CodeceptJS
+
+## Using Resemble helper
+
+[Resemble.js](https://github.com/rsmbl/Resemble.js) is a great tool for image comparison and analysis, which can be used with CodeceptJS
+
+### Setup
+
+To install the package, just run
+
+```
+npm install codeceptjs-resemblehelper --save
+```
+
+### Configuring
+
+This helper should be added to `codecept.conf.js` config file.
+
+Example:
+
+```json
+{
+   "helpers": {
+     "ResembleHelper" : {
+       "require": "codeceptjs-resemblehelper",
+       "screenshotFolder" : "./tests/output/",
+       "baseFolder": "./tests/screenshots/base/",
+       "diffFolder": "./tests/screenshots/diff/"
+     }
+   }
+}
+```
+
+To use the Helper, users must provide the three parameters:
+
+* `screenshotFolder` : This will always have the same value as `output` in Codecept configuration, this is the folder where WebDriver saves a screenshot when using `I.saveScreenshot` method
+* `baseFolder`: This is the folder for base images, which will be used with screenshot for comparison
+* `diffFolder`: This will the folder where resemble would try to store the difference image, which can be viewed later.
+
+### Usage
+
+Details about the helper can be found on the [Github Repo](https://github.com/puneet0191/codeceptjs-resemblehelper)
+
+Base Image is compared with the screenshot image and test results are derived based on the `mismatch tolerance` level provided by the user for the comparison
+
+### Example
+
+Lets consider visual testing for [CodeceptJS Home](https://codecept.io)
+
+```js
+Feature('To test screen comparison with resemble Js Example test');
+
+Scenario('Compare CodeceptIO Home Page @visual-test', async ({ I }) => {
+    I.amOnPage("/");
+    I.saveScreenshot("Codecept_IO_Screenshot_Image.png");
+    I.seeVisualDiff("Codecept_IO_Screenshot_Image.png", {tolerance: 2, prepareBaseImage: false});
+});
+```
+
+In this example, we are setting the expected mismatch tolerance level as `2`
+
+`Base Image` (Generated by User)
+![Base Image](/img/Codecept_IO_Base_Image.png)
+
+`Screenshot Image` (Generated by Test)
+![Screenshot Image](/img/Codecept_IO_Screenshot_Image.png)
+
+Clearly the difference in both the images visible to human eye is the section about `Scenario Driven`
+
+![Difference Image](/img/difference_Image_Codecept_Home.png)
+
+`Diff Image` generated by the helper clearly highlights the section which don't match
+
+![Highlight](/img/Difference%20Image%20Focus.png)
+
+`Failed Test output`
+```
+To test screen comparison with resemble Js Example test --
+  Compare CodeceptIO Home Page @visual-test
+    I see Visual Diff "Codecept_IO_Screenshot_Image.png", {tolerance: 2, prepareBaseImage: false}
+MisMatch Percentage Calculated is 2.85
+  ✖ FAILED in 418ms
+
+
+-- FAILURES:
+
+  1) To test screen comparison with resemble Js Example test
+       Compare CodeceptIO Home Page @visual-test:
+
+      MissMatch Percentage 2.85
+      + expected - actual
+
+      -false
+      +true
+```
+
+`Codeceptjs-resemblehelper` basically comes with two major functions
+
+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 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.
+
+### Setup
+
+Create an account at [Applitools](https://applitools.com/users/register) and install the npm packages
+
+```
+npm i codeceptjs-applitoolshelper --save
+npm i webdriverio@5 --save
+```
+
+### Configuring
+
+```js
+...
+  helpers: {
+    WebDriver: {
+      url: 'https://applitools.com/helloworld',
+      browser: 'chrome',
+      desiredCapabilities: {
+        chromeOptions: {
+          args: [ '--headless', '--disable-extensions', '--disable-gpu', '--no-sandbox', '--disable-dev-shm-usage']
+        }
+      },
+      windowSize: '1920x600',
+      smartWait: 5000,
+      timeouts: {
+        'script': 60000,
+        'page load': 10000
+      },
+    },
+    ApplitoolsHelper: {
+      require: 'codeceptjs-applitoolshelper',
+      applitoolsKey: 'YOUR_API_KEY'
+    }
+  },
+...
+```
+
+#### To use this helper you need to provide the following info:
+
+- applitoolsKey (Required): You can find your API key under the user menu located at the right hand side of the test manager toolbar
+- windowSize (Optional): the windows size as for instance 1440x700, if not provided, the default 1920x600 will be used. The windowSize will follow this precedence: ApplitoolsHelper, Webdriver.
+- appName (Optional): you can either provide your desired application name, if not provided, the default 'Application Under Test' will be used.
+
+### Usage
+
+```javascript
+/**
+ * @param pageToCheck {string} Name of page you want to check
+ */
+I.eyeCheck(pageToCheck);
+
+```
+
+The first time you run this test a new baseline will be created, and subsequent test runs will be compared to this baseline. If any screenshot mismatch its baseline image in a perceptible way, there will be a `DiffsFoundException` which includes a URL that points to a detailed report where you can see the detected differences and take appropriate actions such as reporting bugs, updating the baseline and more.
+
+```js
+-- FAILURES:
+
+  1) Applitools functionality
+       Check home page @test:
+     Test 'Applitools functionality' of 'Application Under Test' detected differences!. See details at: https://eyes.applitools.com/app/batches/00000251831777088983/00000251831777088717?accountId=KO-Oh9tXI0e8VF8Ha_GLVA~~
+```
+
+> You can find the latest documentation here [Applitools Docs](https://applitools.com/tutorials/webdriverio5.html#run-your-first-test)
+
+### Example
+
+Lets consider visual testing for [CodeceptJS Home](https://codecept.io).
+You can also find example repo here: https://github.com/PeterNgTr/codeceptjs-applitoolshelper
+
+```js
+const { I } = inject();
+
+Feature('Applitools functionality');
+
+Before(() => {
+    I.amOnPage('https://applitools.com/helloworld');
+});
+
+Scenario('Check home page @test', async ({  }) => {
+    await I.eyeCheck('Homepage');
+});
+```
+

package/docs/vue.md

@@ -0,0 +1,143 @@
+---
+permalink: /vue
+layout: Section
+sidebar: false
+title: Testing Vue Apps
+---
+
+
+# vue-cli-plugin-e2e-codeceptjs
+
+*Hey, how about some end 2 end testing for your Vue apps?* 🤔
+
+*Let's do it together! Vue, me, [CodeceptJS](https://codecept.io) & [Puppeteer](https://pptr.dev).* 🤗
+
+*Browser testing was never that simple. Just see it!* 😍
+
+```js
+I.amOnPage('/');
+I.click('My Component Button');
+I.see('My Component');
+I.say('I am happy!');
+// that's right, this is a valid test!
+```
+
+## How to try it?
+
+**Requirements:**
+
+* NodeJS >= 8.9
+* NPM / Yarn
+* Vue CLI installed globally
+
+```
+npm i vue-cli-plugin-codeceptjs-puppeteer --save-dev
+```
+
+This will install CodeceptJS, CodeceptUI & Puppeteer with Chrome browser.
+
+To add CodeceptJS to your project invoke installer:
+
+```
+vue invoke vue-cli-plugin-codeceptjs-puppeteer
+```
+
+> You will be asked about installing a demo component. If you start a fresh project **it is recommended to agree and install a demo component**, so you could see tests passing.
+
+
+## Running Tests
+
+We added npm scripts:
+
+* `test:e2e` - will execute tests with browser opened. If you installed test component, and started a test server, running this command will show you a brower window passed test.
+  * Use `--headless` option to run browser headlessly
+  * Use `--serve` option to start a dev server before tests
+
+
+Examples:
+
+```
+npm run test:e2e
+npm run test:e2e -- --headless
+npm run test:e2e -- --serve
+```
+
+> This command is a wrapper for `codecept run --steps`. You can use the [Run arguments and options](/commands#run) here.
+
+* `test:e2e:parallel` - will execute tests headlessly in parallel processes (workers). By default runs tests in 2 workers.
+  * Use an argument to set number of workers
+  * Use `--serve` option to start dev server before running
+
+Examples:
+
+```
+npm run test:e2e:parallel
+npm run test:e2e:parallel -- 3
+npm run test:e2e:parallel -- 3 --serve
+```
+
+> This command is a wrapper for `codecept run-workers 2`. You can use the [Run arguments and options](/commands#run-workers) here.
+
+* `test:e2e:open` - this opens interactive web test runner. So you could see, review & run your tests from a browser.
+
+![](https://user-images.githubusercontent.com/220264/70399222-b7a1bc00-1a2a-11ea-8f0b-2878b0328161.gif)
+
+```
+npm run test:e2e:open
+```
+
+## Directory Structure
+
+Generator has created these files:
+
+```js
+codecept.conf.js          👈 codeceptjs config
+jsconfig.json             👈 enabling type definitons
+tests
+├── e2e
+│   ├── app_test.js       👈 demo test, edit it!
+│   ├── output            👈 temp directory for screenshots, reports, etc
+│   └── support
+│       └── steps_file.js 👈 common steps
+└── steps.d.ts            👈 type definitions
+```
+
+If you agreed to create a demo component, you will also see `TestMe` component in `src/components` folder.
+
+## Locators
+
+For Vue apps a special `vue` locator is available. It allows to select an element by its component name, and props.
+
+```js
+{ vue: 'MyComponent' }
+{ vue: 'Button', props: { title: 'Click Me' }}
+```
+
+With Playwright, you can use Vue locators in any method where locator is required:
+
+```js
+I.click({ vue: 'Tab', props: { title: 'Click Me!' }});
+I.seeElement({ vue: 't', props: { title: 'Clicked' }});
+```
+
+To find Vue element names and props in a tree use [Vue DevTools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd) extension.
+
+> Turn off minification for application builds otherwise component names will be uglified as well
+
+Vue locators work via [Playwright Vue Locator](https://playwright.dev/docs/other-locators#vue-locator).
+
+## How to write tests?
+
+* Open `tests/e2e/app_js` and see the demo test
+* Execute a test & use interactive pause to see how CodeceptJS works
+* [Learn CodeceptJS basics](/basics)
+* [Learn how to write CodeceptJS tests with Puppeteer](/puppeteer)
+* [See full reference for CodeceptJS Puppeteer Helper](/helpers/Puppeteer)
+* Ask your questions in [Slack](https://bit.ly/chat-codeceptjs) & [Forum](https://codecept.discourse.group/)
+
+## Enjoy testing!
+
+Testing is simple & fun, enjoy it!
+
+With ❤ [CodeceptJS Team](https://codecept.io)
+

package/docs/webapi/amOnPage.mustache

@@ -0,0 +1,11 @@
+Opens a web page in a browser. Requires relative or absolute url.
+If url starts with `/`, opens a web page of a site defined in `url` config parameter.
+
+```js
+I.amOnPage('/'); // opens main page of website
+I.amOnPage('https://github.com'); // opens github
+I.amOnPage('/login'); // opens a login page
+```
+
+@param {string} url url path or global url.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/appendField.mustache

@@ -0,0 +1,11 @@
+Appends text to a input field or textarea.
+Field is located by name, label, CSS or XPath
+
+```js
+I.appendField('#myTextField', 'appended');
+// typing secret
+I.appendField('password', secret('123456'));
+```
+@param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
+@param {string} value text value to append.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/attachFile.mustache

@@ -0,0 +1,12 @@
+Attaches a file to element located by label, name, CSS or XPath
+Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located).
+File will be uploaded to remote system (if tests are running remotely).
+
+```js
+I.attachFile('Avatar', 'data/avatar.jpg');
+I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
+```
+
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@param {string} pathToFile local file path relative to codecept.conf.ts or codecept.conf.js config file.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/blur.mustache

@@ -0,0 +1,18 @@
+Remove focus from a text input, button, etc.
+Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+
+Examples:
+
+```js
+I.blur('.text-area')
+```
+```js
+//element `#product-tile` is focused
+I.see('#add-to-cart-btn');
+I.blur('#product-tile')
+I.dontSee('#add-to-cart-btn');
+```
+
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/checkOption.mustache

@@ -0,0 +1,13 @@
+Selects a checkbox or radio button.
+Element is located by label or name or CSS or XPath.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+I.checkOption('#agree');
+I.checkOption('I Agree to Terms and Conditions');
+I.checkOption('agree', '//form');
+```
+@param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/clearCookie.mustache

@@ -0,0 +1,9 @@
+Clears a cookie by name,
+if none provided clears all cookies.
+
+```js
+I.clearCookie();
+I.clearCookie('test'); // Playwright currently doesn't support clear a particular cookie name
+```
+
+@param {?string} [cookie=null] (optional, `null` by default) cookie name