codeceptjs 2.3.4 → 2.4.1

package/docs/changelog.md

@@ -1,8 +1,64 @@
 ---
-id: changelog
+permalink: /changelog
 title: Releases
+sidebar: false
+layout: Section
 ---
 
+# Releases
+
+## 2.4.1
+
+* **[Hotfix]** - Add missing lib that prevents codeceptjs from initializing.
+
+## 2.4.0
+
+* Improved setup wizard with `npx codecept init`:
+  * **enabled [retryFailedStep](/plugins/#retryfailedstep) plugin for new setups**.
+  * enabled [@codeceptjs/configure](/configuration/#common-configuration-patterns) to toggle headless/window mode via env variable
+  * creates a new test on init
+  * removed question on "steps file", create it by default.
+* Added [pauseOnFail plugin](/plugins/#pauseonfail). *Sponsored by Paul Vincent Beigang and his book "[Practical End 2 End Testing with CodeceptJS](https://leanpub.com/codeceptjs/)"*.
+* Added [`run-rerun` command](/commands/#run-rerun) to run tests multiple times to detect and fix flaky tests. By **[Ilrilan](https://github.com/Ilrilan)** and **[Vorobeyko](https://github.com/Vorobeyko)**.
+* Added [`Scenario.todo()` to declare tests as pending](/basics#todotest). See [#2100](https://github.com/Codeception/CodeceptJS/issues/2100) by **[Vorobeyko](https://github.com/Vorobeyko)**
+* Added support for absolute path for `output` dir. See [#2049](https://github.com/Codeception/CodeceptJS/issues/2049) by **[elukoyanov](https://github.com/elukoyanov)**
+* Fixed error in `npx codecept init` caused by calling `console.print`. See [#2071](https://github.com/Codeception/CodeceptJS/issues/2071) by **[Atinux](https://github.com/Atinux)**.
+* **[Filesystem]** Methods added by **[aefluke](https://github.com/aefluke)**:
+  * `seeFileNameMatching`
+  * `grabFileNames`
+* **[Puppeteer]** Fixed grabbing attributes with hyphen by **[Holorium](https://github.com/Holorium)**
+* **[TestCafe]** Fixed `grabAttributeFrom` method by **[elukoyanov](https://github.com/elukoyanov)**
+* **[MockRequest]** Added support for [Polly config options](https://netflix.github.io/pollyjs/#/configuration?id=configuration) by **[ecrmnn](https://github.com/ecrmnn)**
+* **[TestCafe]** Fixes exiting with zero code on failure. Fixed [#2090](https://github.com/Codeception/CodeceptJS/issues/2090) with [#2106](https://github.com/Codeception/CodeceptJS/issues/2106) by **[koushikmohan1996](https://github.com/koushikmohan1996)**
+* [WebDriver][Puppeteer] Added basicAuth support via config. Example: `basicAuth: {username: 'username', password: 'password'}`. See [#1962](https://github.com/Codeception/CodeceptJS/issues/1962) by **[PeterNgTr](https://github.com/PeterNgTr)**
+* [WebDriver][Appium] Added `scrollIntoView` by **[pablopaul](https://github.com/pablopaul)**
+* Fixed [#2118](https://github.com/Codeception/CodeceptJS/issues/2118): No error stack trace for syntax error by **[senthillkumar](https://github.com/senthillkumar)**
+* Added `parse()` method to data table inside Cucumber tests. Use it to obtain rows and hashes for test data. See [#2082](https://github.com/Codeception/CodeceptJS/issues/2082) by **[Sraime](https://github.com/Sraime)**
+
+## 2.3.6
+
+* Create better Typescript definition file through JSDoc. By **[lemnis](https://github.com/lemnis)**
+* `run-workers` now can use glob pattern. By **[Ilrilan](https://github.com/Ilrilan)**
+```js
+// Example:
+exports.config = {
+  tests: '{./workers/base_test.workers.js,./workers/test_grep.workers.js}',
+}
+```
+* Added new command `npx codeceptjs info` which print information about your environment and CodeceptJS configs. By **[jamesgeorge007](https://github.com/jamesgeorge007)**
+* Fixed some typos in documantation. By **[pablopaul](https://github.com/pablopaul)** **[atomicpages](https://github.com/atomicpages)** **[EricTendian](https://github.com/EricTendian)**
+* Added PULL_REQUEST template.
+* [Puppeteer][WebDriver] Added `waitForClickable` for waiting clickable element on page.
+* **[TestCafe]** Added support for remote connection. By **[jvdieten](https://github.com/jvdieten)**
+* **[Puppeteer]** Fixed `waitForText` XPath context now works correctly. By **[Heavik](https://github.com/Heavik)**
+* **[TestCafe]** Fixed `clearField` clear field now awaits TestCafe's promise. By **[orihomie](https://github.com/orihomie)**
+* **[Puppeteer]** Fixed fails when executing localStorage on services pages. See [#2026](https://github.com/Codeception/CodeceptJS/issues/2026)
+* Fixed empty tags in test name. See [#2038](https://github.com/Codeception/CodeceptJS/issues/2038)
+
+## 2.3.5
+
+* Set "parse-function" dependency to "5.2.11" to avoid further installation errors.
+
 ## 2.3.4
 
 * Fixed installation error "Cannot find module '@babel/runtime/helpers/interopRequireDefault'". The issue came from `parse-function` package. Fixed by **[pablopaul](https://github.com/pablopaul)**.

package/docs/commands.md

@@ -1,8 +1,9 @@
 ---
-id: commands
+permalink: /commands
 title: Commands
 ---
 
+# Commands
 
 ## Run
 
@@ -87,6 +88,36 @@ Run tests in parallel threads.
 npx codeceptjs run-workers 3
 ```
 
+## Run Rerun <Badge text="Since 2.4" type="warning"/>
+
+Run tests multiple times to detect and fix flaky tests.
+
+```
+npx codeceptjs run-rerun
+```
+
+For this command configuration is required:
+
+```js
+{
+  // inside codecept.conf.js
+  rerun: {
+    // how many times all tests should pass
+    minSuccess: 2,
+
+    // how many times to try to rerun all tests
+    maxReruns: 4,
+  }
+}
+```
+
+Use Cases:
+
+* `minSuccess: 1, maxReruns: 5` - run all tests no more than 5 times, until first successful run.
+* `minSuccess: 3, maxReruns: 5` - run all tests no more than 5 times, until reaching 3 successfull runs.
+* `minSuccess: 10, maxReruns: 10` - run all tests exactly 10 times, to check their stability.
+
+
 ## Dry Run
 
 Prints test scenarios without executing them
@@ -116,7 +147,7 @@ npx codeceptjs dry-run --steps --bootstrap
 ## Run Multiple
 
 Run multiple suites. Unlike `run-workers` spawns processes to execute tests.
-[Requires additional configuration](https://codecept.io/advanced#multiple-browsers-execution) and can be used to execute tests in multiple browsers.
+[Requires additional configuration](/advanced#multiple-browsers-execution) and can be used to execute tests in multiple browsers.
 
 ```sh
 npx codeceptjs run-multiple smoke:chrome regression:firefox
@@ -197,3 +228,11 @@ Prints all available methods of `I` to console
 ```sh
 npx codeceptjs list
 ```
+
+## Local Environment Information
+
+Prints debugging information concerning the local environment
+
+```sh
+npx codeceptjs info
+```

package/docs/community-helpers.md

@@ -1,8 +1,10 @@
 ---
-id: community-helpers
+permalink: /community-helpers
 title: Community Helpers
+editLink: false
 ---
 
+# Community Helpers
 > Share your helpers at our [Wiki Page](https://github.com/Codeception/CodeceptJS/wiki/Community-Helpers)
 
 Here is the list of helpers created by our community.
@@ -35,5 +37,14 @@ Please **add your own** by editing this page.
 
 ## Page Object Code Generator
 * [codeceptjs-CodeGenerator](https://github.com/senthillkumar/CodeCeptJS-PageObject) is a CodeceptJS custom wrapper which can create page class with action methods from the page object file(JSON) and project setup(Folder Structure).
+
+## Browser request control
+* [codeceptjs-resources-check](https://github.com/luarmr/codeceptjs-resources-check) Load a URL with Puppeteer and listen to the requests while the page is loading. Enabling count the number or check the sizes of the requests.
+
+## Assertion & Validations
+* [codeceptjs-chai](https://www.npmjs.com/package/codeceptjs-chai) is a CodeceptJS helper which wraps
+[chai](https://www.chaijs.com/) library to complete chai assertion steps with CodeceptJS logging.
+
 ## Other
 
+* [eslint-plugin-codeceptjs](https://www.npmjs.com/package/eslint-plugin-codeceptjs) Eslint rules for CodeceptJS.

package/docs/configuration.md

@@ -1,8 +1,9 @@
 ---
-id: configuration
+permalink: /configuration
 title: Configuration
 ---
 
+# Configuration
 
 CodeceptJS configuration is set in `codecept.conf.js` file.
 
@@ -10,7 +11,7 @@ After running `codeceptjs init` it should be saved in test root.
 
 Here is an overview of available options with their defaults:
 
-* **tests**: `"./*_test.js"` - pattern to locate tests
+* **tests**: `"./*_test.js"` - pattern to locate tests. Allows to enter [glob pattern](https://github.com/isaacs/node-glob).
 * **grep**: - pattern to filter tests by name
 * **include**: `{}` - actors and page objects to be registered in DI container and included in tests. Accepts objects and module `require` paths
 * **timeout**: `10000` - default tests timeout
@@ -98,6 +99,8 @@ codeceptjs run --config=./path/to/my/config.js
 
 ## Common Configuration Patterns
 
+> 📺 [Watch this material](https://www.youtube.com/watch?v=onBnfo_rJa4&t=4s) on YouTube
+
 [`@codeceptjs/configure` package](https://github.com/codecept-js/configure) contains shared recipes for common configuration patterns. This allows to set meta-configuration, independent from a current helper enabled.
 
 Install it and enable to easily switch to headless/window mode, change window size, etc.

package/docs/continuous-integration.md

@@ -0,0 +1,22 @@
+---
+permalink: /continuous-integration
+title: Continuous Integration
+---
+
+<!-- this file is auto generated from CI category https://codecept.discourse.group/c/CodeceptJS-issues-in-general/ci/9 -->
+
+# Continuous Integration
+
+> Help us improve this article. [Write how did you set up CodeceptJS for CI](https://codecept.discourse.group/c/CodeceptJS-issues-in-general/ci/9) and see your post listed here!
+
+Continuous Integration services allows you to delegate the control of running tests to external system.
+CodeceptJS plays well with all types of CI even when there is no documentation on this topic, it is still easy to set up with any kind of hosted or cloud CI.
+Our community prepared some valuable recipes for setting up CI systems with CodeceptJS.
+
+## Recipes
+
+* ### [CodeceptJS - Codefresh Integration](https://codecept.discourse.group/t/codeceptjs-codefresh-integration/)
+* ### [CodeceptJS GitLab Integration](https://codecept.discourse.group/t/codeceptjs-gitlab-integration/)
+* ### [CodeceptJS - Jenkins Integration](https://codecept.discourse.group/t/codeceptjs-jenkins-integration/)
+* ### [CodeceptJS Integration with TeamCity](https://codecept.discourse.group/t/codeceptjs-integration-with-teamcity/)
+

package/docs/{helpers.md → custom-helpers.md}

@@ -1,14 +1,16 @@
 ---
-id: helpers
+permalink: /helpers
 title: Custom Helpers
 ---
 
 
-Helpers is a core concept of CodeceptJS. Helper is a wrapper around various libraries providing unified interface around them.
-Methods of Helper class will be available in tests in `I` object. This abstracts test scenarios from the implementation and allows easy switching between backends.
+Helpers is a core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them.
+
+Methods of Helper class will be available in tests in `I` object. This abstracts test scenarios from the implementation and allows easily switching between backends.
+
 Functionality of CodeceptJS should be extended by writing a custom helpers.
 
-Helpers can also be installed as Node packages and required by corresponding Node modules
+Helpers can also be installed as Node packages and required by corresponding Node modules.
 
 You can either access core Helpers (and underlying libraries) or create a new from scratch.
 
@@ -17,7 +19,7 @@ You can either access core Helpers (and underlying libraries) or create a new fr
 Helpers can be created by running a generator command:
 
 ```bash
-codeceptjs gh
+npx codeceptjs gh
 ```
 
 *(or `generate helper`)*
@@ -65,7 +67,7 @@ Every method should return a value in order to be appended into promise chain.
 After writing your own custom helpers here you can always update CodeceptJS TypeScript Type Definitions running:
 
 ```sh
-codeceptjs def .
+npx codeceptjs def .
 ```
 
 This way, if your tests are written with TypeScript, your IDE will be able to leverage features like autocomplete and so on.
@@ -110,7 +112,7 @@ module.exports = MyHelper;
 
 ## Puppeteer Example
 
-Puppteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Access `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
+Puppeteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Access `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
 
 Let's see how we can use [emulate](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulateoptions) function to emulate iPhone browser in a test.
 
@@ -209,6 +211,7 @@ Implement corresponding methods to them.
 * `_init` - before all tests
 * `_finishTest` - after all tests
 * `_before` - before a test
+* `_after` - after a test
 * `_beforeStep` - before each step
 * `_afterStep` - after each step
 * `_beforeSuite` - before each suite
@@ -220,7 +223,7 @@ Each implemented method should return a value as they will be added to global pr
 
 ### Hook Usage Examples
 
-1)  Failing if JS error occur in WebDriver:
+1)  Failing if JS error occurs in WebDriver:
 
 ```js
 class JSFailure extends codecept_helper {
@@ -231,7 +234,7 @@ class JSFailure extends codecept_helper {
   }
 
   _afterStep() {
-    if (this.err) throw new Error('Browser JS error '+this.err);
+    if (this.err) throw new Error(`Browser JS error ${this.err}`);
   }
 }
 
@@ -259,7 +262,7 @@ module.exports = JSWait;
 It is possible to execute global conditional retries to handle unforseen errors.
 Lost connections and network issues are good candidates to be retried whenever they appear.
 
-This can be done inside a helper using the global [promise recorder](https://codecept.io/hooks/#api):
+This can be done inside a helper using the global [promise recorder](/hooks/#api):
 
 Example: Retrying rendering errors in Puppeteer.
 
@@ -277,3 +280,6 @@ _before() {
 
 Retry rules are available in array `recorder.retries`. The last retry rule can be disabled by running `recorder.retries.pop()`;
 
+## Using Typescript
+
+When using typescript, replace `module.exports` with `export` for autocompletion.

package/docs/data.md

@@ -1,8 +1,9 @@
 ---
-id: data
+permalink: /data
 title: Data Management
 ---
 
+# Data Management
 
 > This chapter describes data management for external sources. If you are looking for using Data Sets in tests, see [Data Driven Tests](http://codecept.io/advanced/#data-drivern-tests) section*
 
@@ -153,8 +154,8 @@ Scenario('check post page', async (I)  => {
 // cleanup created data
 After((I) => {
   I.sendMutation(
-    'mutation deletePost($id: ID!) { deletePost(id: $id) }',
-    { id: postData.id},
+    'mutation deletePost($permalink: /ID!) { deletePost(permalink: /$id) }',
+    { permalink: /postData.id},
   );
 });
 ```
@@ -195,7 +196,7 @@ The way for setting data for a test is as simple as writing:
 ```js
 // inside async function
 let post = await I.have('post');
-I.haveMultiple('comment', 5, { postId: post.id});
+I.haveMultiple('comment', 5, { postpermalink: /post.id});
 ```
 
 After completing the preparations under 'Data Generation with Factories', create a factory module which will export a factory.
@@ -247,7 +248,7 @@ This way for setting data for a test is as simple as writing:
 ```js
 // inside async function
 let post = await I.mutateData('createPost');
-I.mutateMultiple('createComment', 5, { postId: post.id});
+I.mutateMultiple('createComment', 5, { postpermalink: /post.id});
 ```
 
 
@@ -287,7 +288,7 @@ GraphQLDataFactory: {
       query: 'mutation createUser($input: UserInput!) { createUser(input: $input) { id name }}',
       factory: './factories/users',
       revert: (data) => ({
-        query: 'mutation deleteUser($id: ID!) { deleteUser(id: $id) }',
+        query: 'mutation deleteUser($permalink: /ID!) { deleteUser(permalink: /$id) }',
         variables: { id : data.id},
       }),
     },

package/docs/detox.md

@@ -1,11 +1,11 @@
 ---
-id: detox
+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/Codeception/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](https://codecept.io/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.
+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.
 
@@ -30,8 +30,8 @@ CodeceptJS allows you to try different options and choose the one which works be
 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](https://codecept.io/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](https://codecept.io/basics#retries) using `retryFailedStepPlugin` and `I.retry()`
+* [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
@@ -179,7 +179,7 @@ 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' });
+I.click({ andropermalink: /'Start', ios: '~start' });
 ```
 
 When application behavior differs on Android and iOS use platform-specific actions:
@@ -207,7 +207,7 @@ Scenario('save in application', (I) => {
   I.fillField('#text', 'a new text');
   I.see('a new text', '#textValue');
   I.dontSeeElement('#createdAndVisibleText');
-  I.click({ ios: '#GoButton', android: 'Button' });
+  I.click({ ios: '#GoButton', andropermalink: /'Button' });
   I.waitForElement('#createdAndVisibleText', 20);
   I.seeElement('#createdAndVisibleText');
   I.runOnAndroid(() => {

package/docs/email.md

@@ -1,8 +1,10 @@
 ---
-id: email
+permalink: /email
 title: Email Testing
 ---
 
+# Email Testing
+
 In End 2 End testing we need to interact with emails.
 Email delivery can't tested locally or mocked while testing.
 That's why for an end to end test you need to use a real emails to be sent and real email address to receive that emails.
@@ -53,7 +55,7 @@ mailbox object contains:
 * `id` - which is used in next commands
 * `emailAddress` - randomly generated address of a created mailbox.
 
-> See [Mailslsurp Guide](https://www.mailslurp.com/developers/guides/#create-email-addresses) for details.
+> 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 mailboxes and you want to switch between them use `openMailbox` method:
 

package/docs/examples.md

@@ -1,9 +1,28 @@
 ---
-id: examples
+permalink: /examples
+layout: Section
+sidebar: false
 title: Examples
+editLink: false
 ---
 
+# Examples
 > Add your own examples to our [Wiki Page](https://github.com/Codeception/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.
@@ -14,9 +33,9 @@ Our team uses it to test new features and run simple scenarios.
 
 ![](https://user-images.githubusercontent.com/220264/56353972-56975080-61db-11e9-8b23-06e8b4620995.png)
 
-End 2 end tests for [Bugira Bugtracker](https://bugira.com) app built with Rails & EmberJS. Bugira is a SaaS application which helps to collect user feedback and transform it into professional bugreports.
+End 2 end tests for [Bugira Bugtracker](https://bugira.com) app built with Rails & EmberJS. Bugira is a SaaS application that helps collecting users' feedbacks and transforming them into professional bug reports.
 
-Tests repository deomstrate usage of
+Tests repository demonstrate usage of
 
 * Puppeteer helper
 * ApiDataFactory helper

package/docs/helpers/ApiDataFactory.md

@@ -1,5 +1,7 @@
 ---
-id: ApiDataFactory
+permalink: /helpers/ApiDataFactory
+editLink: false
+sidebar: auto
 title: ApiDataFactory
 ---
 
@@ -7,7 +9,7 @@ title: ApiDataFactory
 
 ## ApiDataFactory
 
-Extends Helper
+**Extends Helper**
 
 Helper for managing remote data using REST API.
 Uses data generators like [rosie][1] or factory girl to create new record.
@@ -189,25 +191,25 @@ By default `id` property of response is taken. This behavior can be changed by s
 
 -   `config`  
 
-### \_requestCreate
+### _requestCreate
 
 Executes request to create a record in API.
 Can be replaced from a in custom helper.
 
 #### Parameters
 
--   `factory` any 
--   `data` any 
+-   `factory` **any** 
+-   `data` **any** 
 
-### \_requestDelete
+### _requestDelete
 
 Executes request to delete a record in API
 Can be replaced from a custom helper.
 
 #### Parameters
 
--   `factory` any 
--   `id` any 
+-   `factory` **any** 
+-   `id` **any** 
 
 ### have
 
@@ -223,8 +225,8 @@ const user = await I.have('user', { email: 'user@user.com'});
 
 #### Parameters
 
--   `factory` any factory to use
--   `params` any predefined parameters
+-   `factory` **any** factory to use
+-   `params` **any** predefined parameters
 
 ### haveMultiple
 
@@ -240,9 +242,9 @@ I.haveMultiple('post', 3, { author: 'davert' });
 
 #### Parameters
 
--   `factory` any 
--   `times` any 
--   `params` any 
+-   `factory` **any** 
+-   `times` **any** 
+-   `params` **any** 
 
 [1]: https://github.com/rosiejs/rosie