codeceptjs 3.5.12-beta.1 → 3.5.12-beta.2

package/docs/detox.md

@@ -0,0 +1,235 @@
+---
+permalink: /detox
+title: Testing React Native with Detox
+---
+
+> Warning! Detox support in CodeceptJS is experimental. Please try it and help us to test it and improve it. [See Detox helper repository](https://github.com/codeceptjs/detox-helper).
+
+Automated mobile testing can be slow, hard, and ineffective. The price of it goes high, if we take into account fragility of applications, slowness of emulators, and the complexity of debug. [Appium](/mobile) helps writing mobile tests but not all apps can be tested effectively with it. That's why you should consider using an alternative approach.
+
+Meet [Detox](https://github.com/wix/Detox) - grey-box testing solution for mobile testing by Wix.
+
+Unlike, Appium, Detox requires to update mobile application to include test instrumentation, so an application could receive commands from a test, and act accordingly. Let's see pros and cons of such approach:
+
+
+**Pros**:
+
+* faster tests
+* synchronization with application
+* plays nicely with React Native
+
+**Cons**:
+
+* application should be built in a special way
+* no hybrid applications
+* native Android apps not supported (except React Native)
+* no cloud testing with SauceLabs or BrowserStack
+
+CodeceptJS allows you to try different options and choose the one which works best for you. Both Appium and Detox helpers share the same syntax for testing mobile applications, interactive pause, automatic retries, and other useful features.
+
+CodeceptJS provides next features over standard Detox:
+
+* **Unified API**. The same test can be executed in Appium or Detox. Unified API helps different teams to use the same syntax and easy port tests from one engine to another.
+* [Interactive pause](/basics#pause). When starting/stopping an application takes a long time, debugging and writing tests can be hard. CodeceptJS solves this by pausing an execution and letting you try different commands and locators. With this feature a test can be writtern during one running session.
+* [Auto-retries](/basics#retries) using `retryFailedStepPlugin` and `I.retry()`
+* **Cross-Platform testing** - one test can be executed on different engines. When needed, platform-specific actions and locators can be easily applied.
+
+## A Test
+
+Compare a test written for Detox using its native syntax:
+
+```js
+await expect(element(by.text('Welcome'))).toBeVisible();
+await expect(element(by.id('createdAndVisibleText'))).toNotExist();
+await element(by.id('GoButton')).tap();
+await waitFor(element(by.id('createdAndVisibleText'))).toExist().withTimeout(20000);
+await expect(element(by.id('createdAndVisibleText'))).toExist();
+```
+
+with the same test written using CodeceptJS syntax:
+
+```js
+I.see('Welcome');
+I.dontSeeElement('#createdAndVisibleText');
+I.click('#GoButton');
+I.waitForElement('#createdAndVisibleText', 20);
+I.seeElement('#createdAndVisibleText');
+```
+
+As you see, CodeceptJS test is shorter and easier to follow. By simplifying the code and reducing visual noise we make tests easier to follow. But before writing a test we need to prepare an application to be testable with Detox.
+
+## Setup
+
+It is important to follow [Detox guide](https://github.com/wix/Detox/blob/master/docs/Introduction.GettingStarted.md) to build an application with Detox test instrouments included.
+
+After you install Detox, create configuration and build an application using `detox build` command, you are ready to integrate Detox with CodeceptJS.
+
+You need to install Detox CodeceptJS helper:
+
+```
+npm i @codeceptjs/detox-helper --save-dev
+```
+
+Then enable this helper in `codecept.conf.js`:
+
+```js
+helpers: {
+   Detox: {
+     require: '@codeceptjs/detox-helper',
+     configuration: '<detox app configuration name>',
+     reloadReactNative: true,
+   }
+}
+```
+
+Enable `reloadReactNative: true` if you test React Native application.
+
+## Actions
+
+Create test as usual, by running command:
+
+```
+npx codeceptjs gt
+```
+
+A test starts when emulator starts and loads an application. So you can begin testing an application.
+
+```js
+// inside a created test
+Scenario('test React Native app', ({ I }) => {
+  I.see('Welcome');
+  I.tap('Start');
+  I.see('Started!');
+});
+```
+
+The most common actions are:
+
+* `tap` (or `click`)
+* `multiTap` - perform multiple taps on element
+* `longPress` - longer press
+* `fillField` - fill in value of text field
+* `clearField` - clear value in text field
+* `appendField` - append value in a field
+* `swipeUp`, `swipeDown`, `swipeLeft`, `swipeRigth`
+
+There are also common assertions:
+
+* `see` - to check visibility of text
+* `seeElement` - to check visibility of element
+* `seeElementExists` - to check that element exists
+
+> For more details on actions refer to the [API reference of Detox helper](https://github.com/codeceptjs/detox-helper#api).
+
+## Locators
+
+To write a test you need to learn about available locators in Detox.
+Unlike, Appium there are no XPath locators. Possible locators limited to `text`, `id`, `accessibility id`, and element `type`. Thus, again, an application should be prepared for testing, to ensure that all active elements are accessible.
+
+Let's see how they can be used:
+
+* For **ID locators** use `#` prefix (same as in CSS). Example:
+
+```js
+I.seeElement('#WelcomeScreen')
+```
+* For **accessibility ID** use `~` prefix (as in Appium helper). Example:
+
+```js
+I.seeElement('~welcome')
+```
+
+* Locating elements **by text** requires no prefix, but can be applied only for actions accepting semantic locators.
+
+```js
+I.tap('Start')
+I.fillField('Username', 'davert')
+I.clearField('Username')
+I.see('Welcome, davert')
+```
+
+* Locating elements **by type** also use no prefix but can be used only where for elements.
+
+```js
+I.seeElement('Button')
+```
+
+Text locators can be combined with others, as methods `tap`, `click` and `see` can receive a second paramater, which defines a context where to perfrom a search.
+
+```js
+// tap "Start" inside "#Layout"
+I.tap('Start', '#Layout');
+// see text "Welcome" inside "~msg"
+I.see('Welcome', '~msg');
+```
+
+Alternatively, you can use specify locator by using *strict locator*, passing an object as a locator:
+
+```js
+I.click({ type: 'Button' });
+I.seeElement({ label: 'welcome' });
+```
+
+> If you are familiar with Detox API, this is how locators are actually translated: `{label: 'welcome'}` => `by.label('welcome')`.
+
+### Cross Platform Testing
+
+If element differs on on iOS and Android you can use **cross platform locators**.
+
+```js
+// locate element by text on Android
+// locate element by accessibility id on iOS
+I.click({ android: 'Start', ios: '~start' });
+```
+
+When application behavior differs on Android and iOS use platform-specific actions:
+
+```js
+I.runOnIOS(() => {
+  // this will be executed only on IOS
+  I.see('Hello iOS');
+});
+I.runOnAndroid(() => {
+  // this will be executed only on Android
+  I.see('Hello Android');
+});
+```
+
+### Sample Test
+
+Finally, you can get a test looking like this
+
+```js
+Feature('My Detox App');
+
+Scenario('save in application', ({ I }) => {
+  I.setLandscapeOrientation();
+  I.fillField('#text', 'a new text');
+  I.see('a new text', '#textValue');
+  I.dontSeeElement('#createdAndVisibleText');
+  I.click({ ios: '#GoButton', android: 'Button' });
+  I.waitForElement('#createdAndVisibleText', 20);
+  I.seeElement('#createdAndVisibleText');
+  I.runOnAndroid(() => {
+    I.click('Save');
+    I.see('Text Saved', '#message');
+  });
+  I.runOnIOS(() => {
+    I.click('SAVE');
+    I.see('SAVED!');
+  });
+});
+```
+
+To execute it use `codeceptjs run` command
+
+```
+npx codeceptjs run
+```
+If you want to use detox configuration other than is set in `codecept.conf.js` use `--configuration` argument:
+
+```
+npx codeceptjs run --configuration android.test.ci
+```
+
+You can also pass all [other arguments that Detox CLI supports](https://github.com/wix/Detox/blob/master/docs/APIRef.DetoxCLI.md#test).

package/docs/docker.md

@@ -0,0 +1,136 @@
+# Codeceptjs Docker
+
+CodeceptJS has an [official docker image](https://hub.docker.com/r/codeceptjs/codeceptjs) based on Playwright image. Image supports Playwright, Puppeteer, and WebDriver engines.
+
+## How to Use
+
+This image comes with the necessary dependencies and packages to execute CodeceptJS tests.
+Mount in your CodeceptJS config directory into the `/tests` directory in the docker container.
+
+Sample mount: `-v path/to/codecept.conf.js:/tests`
+
+CodeceptJS runner is available inside container as `codeceptjs`.
+
+### Locally
+
+You can execute CodeceptJS with Puppeteer locally with no extra configuration.
+
+```sh
+docker run --net=host -v $PWD:/tests codeceptjs/codeceptjs
+```
+
+To customize execution call `codeceptjs` command:
+
+```sh
+# run tests with steps
+docker run --net=host -v $PWD:/tests codeceptjs/codeceptjs codeceptjs run --steps
+
+# run tests with @user in a name
+docker run --net=host -v $PWD:/tests codeceptjs/codeceptjs codeceptjs run --grep "@user"
+```
+
+
+### Docker Compose
+
+```yaml
+version: '2'
+services:
+  codeceptjs:
+    image: codeceptjs/codeceptjs
+    depends_on:
+      - firefox
+      - web
+    volumes:
+      - .:/tests
+  web:
+    image: node
+    command: node app/server.js
+    volumes:
+      - .:/app
+  firefox:
+    image: selenium/standalone-firefox-debug:2.53.0
+    ports:
+      - '4444'
+      - '5900'
+```
+
+### Linking Containers
+
+If using the WebDriver driver, link the container with a Selenium Standalone docker container with an alias of `selenium`. Additionally, make sure your `codeceptjs.conf.js` contains the following to allow CodeceptJS to identify where Selenium is running.
+
+```javascript
+  ...
+  helpers: {
+    WebDriver: {
+      ...
+      host: process.env.HOST
+      ...
+    }
+  }
+  ...
+```
+
+```sh
+$ docker run -d -P --name selenium-chrome selenium/standalone-chrome
+
+# Alternatively, selenium/standalone-firefox can be used
+
+$ docker run -it --rm -v /<path_to_codeceptjs_test_dir>/:/tests/ --link selenium-chrome:selenium codeceptjs/codeceptjs
+```
+
+You may run use `-v $(pwd)/:tests/` if running this from the root of your CodeceptJS tests directory.
+_Note: The output of your test run will appear in your local directory if your output path is `./output` in the CodeceptJS config_
+
+### Build
+
+To build this image:
+
+```sh
+docker build -t codeceptjs/codeceptjs .
+```
+
+* this directory will be added as `/codecept` insde container
+* tests directory is expected to be mounted as `/tests`
+* `codeceptjs` is a synlink to `/codecept/bin/codecept.js`
+
+To build this image with your desired Node version:
+
+```sh
+docker build -t codeceptjs/codeceptjs . --build-arg NODE_VERSION=12.10.0
+```
+
+### Passing Options
+
+Options can be passed by calling `codeceptjs`:
+
+```
+docker run -v $PWD:/tests codeceptjs/codeceptjs codeceptjs run --debug
+```
+
+Alternatively arguments to `codecept run` command can be passed via `CODECEPT_ARGS` environment variable. For example to run your tests with debug
+output:
+
+```yaml
+version: '2'
+services:
+  codeceptjs:
+    image: codeceptjs/codeceptjs
+    environment:
+      - CODECEPT_ARGS=--debug
+    volumes:
+      - .:/tests
+```
+
+You can also use `run-workers`to run tests by passing `NO_OF_WORKERS`, additionally, you can pass more params like showing the debug info as the following example:
+
+```yaml
+version: '2'
+services:
+  codeceptjs:
+    image: codeceptjs/codeceptjs
+    environment:
+      - NO_OF_WORKERS=3
+      - CODECEPT_ARGS=--debug
+    volumes:
+      - .:/tests
+```

package/docs/email.md

@@ -0,0 +1,183 @@
+---
+permalink: /email
+title: Email Testing
+---
+
+# Email Testing
+
+In End 2 End testing we need to interact with emails.
+Email delivery can't be tested locally or mocked while testing.
+That's why for an end to end test you need real emails to be sent and real email address to receive that emails.
+
+Setting up an email server can be hard. So we recommend to use [MailSlurp](https://mailslurp.com/) - a service designed for testing emails. It creates disposable mailboxes and provides you an access to those mailboxes via REST API.
+
+> You no longer need to open your gmail account in a browser to check for an email!
+
+## Installation
+
+MailSlurp is a commercial service with a free plan available. To start, [create an account at MailSlurp](https://app.mailslurp.com/) and receive API key to use it. Once received install mailslurp helper from npm:
+
+```
+npm i @codeceptjs/mailslurp-helper --save-dev
+```
+
+Then enable a helper in `codecept.conf.js`:
+
+```js
+helpers: {
+
+  MailSlurp: {
+    require: '@codeceptjs/mailslurp-helper',
+    apiKey: '<apiKeyFromMailSlurp>'
+  }
+}
+```
+
+After a helper is added, regenerate TypeScript definitions for auto-completion support:
+
+```
+npx codeceptjs def
+```
+
+## Creating Mailbox
+
+MailSlurp allows you to create disposable mailboxes. It means that an email address is created for one test only and is deleted afterwards. So you can be confident that no other emails are received at that address.
+
+To create a mailbox use `I.haveNewMailbox()` command:
+
+```js
+// inside async/await function
+const mailbox = await I.haveNewMailbox();
+```
+
+mailbox object contains:
+
+* `id` - which is used in next commands
+* `emailAddress` - randomly generated address of a created mailbox.
+
+> See [MailSlurp's guide](https://www.mailslurp.com/guides/getting-started/#create-email-addresses) for details.
+
+Mailbox is opened on creation. If you need more than one mailbox and you want to switch between them use `openMailbox` method:
+
+```js
+const mailbox1 = await I.haveNewMailbox();
+const mailbox2 = await I.haveNewMailbox();
+// mailbox2 is now default mailbox
+// switch back to mailbox1
+I.openMailbox(mailbox1);
+```
+
+## Receiving An Email
+
+A last created mailbox will be activated. It means that it will be used by default to check for emails.
+
+After an action that triggers sending an email is performed on a website, you should wait for this email to be received.
+A timeout for waiting an email can be set globally for a helper or for a one call.
+
+Use `waitForLatestEmail` function to return the first email from a mailbox:
+
+```js
+// to wait for default time (10 secs by default)
+I.waitForLatestEmail();
+
+// or specify number of time to wait
+I.waitForLatestEmail(30);
+```
+
+To specify the exact email to match use `waitForEmailMatching` function:
+
+```js
+// wait for an email with partial match in subject
+I.waitForEmailMatching({ subject: 'Restore password' });
+
+// wait 30 seconds for email with exact subject
+I.waitForEmailMatching({ subject: '=Forgot password' }, 30);
+
+// wait a last email from any address @mysite.com
+I.waitForEmailMatching({
+ from: '@mysite.com', // find anything from mysite
+ subject: 'Restore password', // with Restore password in subject
+});
+```
+
+## Opening An Email
+
+All wait* functions return a matched email as a result. So you can use it in a test:
+
+```js
+const email = await I.waitForLatestEmail();
+```
+> Please note, that we use `await` to assign email. This should be declared inside async function
+
+An `email` object contains the following fields:
+
+* `subject`
+* `for`
+* `to`
+* `body`
+
+So you can analyze them inside a test. For instance, you can extract an URL from email body and open it.
+This is how we can emulate "click on this link" behavior in email:
+
+```js
+// clicking a link in email
+const email = await I.waitForLatestEmail();
+// extract a link by RegExp
+const url = email.body.match(/http(s):\/\/(.*?)\s/)[0];
+// open URL
+I.amOnPage(url);
+```
+
+## Assertions
+
+Assertions are performed on the currently opened email. Email is opened on `waitFor` email call, however, you can open an exact email by using `openEmail` function.
+
+```js
+const email1 = await I.waitForLatestEmail();
+// test proceeds...
+const email2 = await I.waitForLatestEmail();
+I.openEmail(email1); // open previous email
+```
+
+After opening an email assertion methods are available.
+
+* `seeInEmailSubject`
+* `seeEmailIsFrom`
+* `seeInEmailBody`
+* `dontSeeInEmailBody`
+* `seeNumberOfEmailAttachments`
+* `seeEmailAttachment`
+
+And here is an example of their usage:
+
+```js
+I.waitForLatestEmail()
+I.seeEmailIsFrom('@mysite.com');
+I.seeInEmailSubject('Awesome Proposal!');
+I.seeInEmailBody('To unsubscribe click here');
+I.seeNumberOfEmailAttachments(2);
+I.seeEmailAttachment('Attachment_1.pdf')
+I.seeEmailAttachment('Attachment_2.pdf')
+```
+
+> More methods are listed in [helper's API reference](https://github.com/codeceptjs/mailslurp-helper/blob/master/README.md#api)
+
+## Listing All Emails
+
+Use `grabAllEmailsFromMailbox` to get all emails from a current mailbox:
+
+```js
+const emails = await I.grabAllEmailsFromMailbox();
+```
+
+## Sending an Email
+
+You can also send an email from an active mailbox:
+
+```js
+I.sendEmail({
+  to: ['user@site.com'],
+  subject: 'Hello',
+  body: 'World'
+});
+```

package/docs/examples.md

@@ -0,0 +1,149 @@
+---
+permalink: /examples
+layout: Section
+sidebar: false
+title: Examples
+editLink: false
+---
+
+# Examples
+> Add your own examples to our [Wiki Page](https://github.com/codeceptjs/CodeceptJS/wiki/Examples)
+## [TodoMVC Examples](https://github.com/codecept-js/examples)
+
+![](https://github.com/codecept-js/examples/raw/master/todo.png)
+
+Playground repository where you can run tests in different helpers on a basic single-page website.
+
+Tests repository demonstrate usage of
+
+* Puppeteer helper
+* WebDriver helper
+* TestCafe plugin
+* Toggle headless mode with env variables
+* PageObjects
+* Cucumber syntax
+
+## [Basic Examples](https://github.com/Codeception/CodeceptJS/tree/master/examples)
+
+CodeceptJS repo contains basic tests (both failing and passing) just to show how it works.
+Our team uses it to test new features and run simple scenarios.
+
+
+## [CodeceptJS Cucumber E2E Framework](https://github.com/gkushang/codeceptjs-e2e)
+
+This repository contains complete E2E framework for CodeceptJS with Cucumber and SauceLabs Integration
+
+* CodecepJS-Cucumber E2E Framework
+* Saucelabs Integration
+* Run Cross Browser tests in Parallel on SauceLabs with a simple command
+* Run tests on `chrome:headless`
+* Page Objects
+* `Should.js` Assertion Library
+* Uses `wdio` service (selenium-standalone, sauce)
+* Allure HTML Reports
+* Uses shared Master configuration
+* Sample example and feature files of GitHub Features
+
+## [Enterprise Grade Tests](https://github.com/uc-cdis/gen3-qa)
+
+Complex testing solution by [Gen3](https://github.com/uc-cdis/gen3-qa) 
+
+Includes 
+
+* classical CodeceptJS tests
+* BDD tests
+* Jenkins integration
+* Complex Before/BeforeSuite scripts and more
+
+## [Testing Single Page Application](https://github.com/bugiratracker/codeceptjs-demo)
+
+End 2 end tests for Task management app (currently offline).
+
+Tests repository demonstrate usage of
+
+* Puppeteer helper
+* ApiDataFactory helper
+* autoLogin plugin
+* Dynamic config with profiles
+
+## [Practical E2E Tests](https://gitlab.com/paulvincent/codeceptjs-e2e-testing)
+
+Examples from the book [Practical End 2 End Testing with CodeceptJS](https://leanpub.com/codeceptjs/) by **Paul Vincent Beigang**. 
+
+This repository demonstrates usage of:
+
+* dynamic config with profiles
+* testing WYSIWYG editor
+* GitLab CI
+
+## [Amazon Tests v2](https://gitlab.com/thanhnguyendh/codeceptjs-wdio-services)
+
+Testing Amazon website using Selenium WebDriver.
+
+This repository demonstrates usage of:
+
+* WebDriver helper
+* Page Objects
+* wdio services (selenium-standalone)
+* Parallel execution
+* GitLab CI setup
+
+## [Tests with Docker Compose](https://github.com/mathesouza/codeceptjs-docker-compose)
+
+Running CodeceptJS tests with Docker Compose
+
+This repository demonstrates usage of:
+
+* CodeceptJS Docker image 
+* WebDriver helper
+* Allure plugin
+
+
+## [AngularJS Example Tests](https://github.com/armno/angular-e2e-codeceptjs-example)
+
+Based on [Setting up End-to-End Testing in Angular Project with CodeceptJS](https://medium.com/@armno/setting-up-end-to-end-testing-in-angular-project-with-codeceptjs-ac1784de3420) post by Armno Prommarak.
+
+This repository demonstrates usage of
+
+* Puppeteer helper
+* Working with Angular CLI
+* Reports with Mochawesome helper
+
+## [REST Example Tests](https://github.com/PeterNgTr/codeceptjs-rest-demo)
+
+This repository demonstrates usage of
+
+* REST helper
+
+## [Automation Starter](https://github.com/sjorrillo/automation-starter)
+
+The purpose of this application is for learning the basics and how to use good practices and useful tools in automation.
+
+* Puppeteer helper
+* Working with gherkin, also it has type definitions and to be able to use them inside when, given and then make sure you add `declare function inject(): { I: CodeceptJS.I, [key: string]: any; };`in the `steps.d.ts`file 
+* Linting `airbnb-base`, `codeceptjs/codeceptjs` and full ES6 support
+
+## [Example for using: Puppeteer, Gherkin, Allure with parallel execution](https://github.com/SchnuckySchuster/codeceptJSExample)
+
+This is a ready to use example that shows how to integrate CodeceptJS with Puppeteer and Allure as reporting tool.
+
+* detailed ReadMe
+* tests written in cucumber alongside tests written in the codeceptJS DSL
+* puppeteer helper example
+* test steps, pages, fragments
+* examples for sequential and parallel execution
+* generation of allure test results  
+
+## [Example for Advanced REST API testing: TypeScript, Axios, CodeceptJS, Jest Expect, Docker, Allure, Mock-Server, Prettier + Eslint, pre-commit, Jest Unit Tests ](https://github.com/EgorBodnar/rest-axios-codeceptjs-allure-docker-test-example)
+One button example with built-in mocked backend. 
+
+If you already have a UI testing solution based on the CodeceptJS and you need to implement advanced REST API testing you can just extend your existing framework. Use this implementation as an example.
+This is necessary if all integrations with TMS and CI/CD are already configured, and you do not want to reconnect and configure the plugins and libraries used for the new test runner. Use CodeceptJS!
+
+* Easy run
+* Detailed README
+* Well documented mocked backend's REST API endpoints
+* HTTP request client with session support and unit tests
+* Exemplary code control
+* Ready to launch in a CI/CD system as is
+* OOP, Test data models and builders, endpoint decorators