codeceptjs 2.2.0 → 2.2.1

package/docs/locators.md

@@ -64,6 +64,8 @@ I.seeElement({ css: 'button' });
 I.seeElement({ xpath: 'descendant::table/tr' });
 ```
 
+> ℹ Use [Locator Advicer](https://davertmik.github.io/locator/) to check quality of your locators.
+
 ## Semantic Locators
 
 CodeceptJS can guess an element's locator from context.

package/docs/mobile.md

@@ -173,6 +173,8 @@ In both Android and iPhone elements are defined in XML format and can be searche
 I.seeElement('//android.widget.ScrollView/android.widget.LinearLayout')'
 ```
 
+> Despite showing XPath in this guide we **do not recommend using XPath for testing iOS native apps. XPath runs very slow on iOS. Consider using ID or Accessibility ID locators instead.
+
 CSS locators are not supported in native mobile apps, you need to switch to web context to use them.
 
 Elements can also be located by their accessability id, available both at Android and iOS.
@@ -181,7 +183,9 @@ Accessibility id is recommended to use for locating element, as it rarely change
 * iOS uses [UIAccessibilityIdentification](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification)
 * Android `accessibility id` matches the content-description
 * Web view uses `[aria-label]` attribute as accessibility id
-* ReactNative for Android has some caveats you could find more [here](mobile-react-native-locators.md)
+* For [React Native for Android see our special guide](mobile-react-native-locators.md).
+
+> If you test React Native application, consider using [Detox helper](/detox) for faster tests.
 
 Add `~` prefix to search for element by its accessibility id:
 

package/docs/puppeteer.md

@@ -36,7 +36,7 @@ Or see [alternative installation options](http://codecept.io/installation/)
 And a basic project initialized
 
 ```sh
-codeceptjs init
+npx codeceptjs init
 ```
 
 You will be asked for a Helper to use, you should select Puppeteer and provide url of a website you are testing.
@@ -52,14 +52,14 @@ Make sure `Puppeteer` helper is enabled in `codecept.conf.js` config:
   helpers: {
     Puppeteer: {
       url: "http://localhost",
-      show: false
+      show: true
     }
   }
   // ..
 }
 ```
 
-Turn on the `show` option if you want to follow test progress in a window. This is very useful for debugging.
+> Turn off the `show` option if you want to run test in headless mode.
 
 Puppeteer uses different strategies to detect if a page is loaded. In configuration use `waitForNavigation` option for that:
 
@@ -69,6 +69,7 @@ By default it is set to `domcontentloaded` which waits for `DOMContentLoaded` ev
   helpers: {
     Puppeteer: {
       url: "http://localhost",
+      show: true,
       waitForNavigation: "networkidle0"
     }
   }
@@ -77,14 +78,14 @@ By default it is set to `domcontentloaded` which waits for `DOMContentLoaded` ev
 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/Puppeteer/).
+> ▶ More options are listed in [helper reference](http://codecept.io/helpers/Puppeteer/).
 
 ## Writing Tests
 
 CodeceptJS test should be created with `gt` command:
 
 ```sh
-codeceptjs gt
+npx codeceptjs gt
 ```
 
 As an example we will use `ToDoMvc` app for testing.
@@ -102,7 +103,7 @@ Tests consist with a scenario of user's action taken on a page. The most widely
 * `see`, `dontSee` - to check for a text on a page
 * `seeElement`, `dontSeeElement` - to check for elements on a page
 
-*All actions are listed in [helper reference](http://codecept.io/helpers/Puppeteer/).*
+> ℹ  All actions are listed in [Puppeteer helper reference](http://codecept.io/helpers/Puppeteer/).*
 
 All actions which interact with elements **support CSS and XPath locators**. Actions like `click` or `fillField` by locate elements by their name or value on a page:
 
@@ -155,7 +156,7 @@ Scenario('get value of current tasks', async (I) => {
 
 ### Within
 
-In case some actions should be taken inside one element (a container or modal window) you can use `within` block to narrow the scope.
+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 Puppeteer helper:
 
 ```js
@@ -167,15 +168,58 @@ within('.todoapp', () => {
 I.see('0 items left', '.todo-count');
 ```
 
+> [▶ Learn more about basic commands](https://codecept.io/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.
 
-`within` can also work with [iframes](/acceptance/#iframes)
+> [▶ Demo project is available on GitHub](https://github.com/DavertMik/codeceptjs-todomvc-puppeteer)
+
+## Mocking Requests
+
+Web application sends various requests to local services (Rest API, GraphQL) or to 3rd party services (CDNS, Google Analytics, etc).
+When you run tests with Puppeteer you can control those requests by mocking them. For instance, you can speed up your tests by blocking trackers, Google Analytics, and other services you don't control.
 
-When running steps inside a within block will be shown with a shift.
+Also you can replace real request with a one explicitly defined. This is useful when you want to isolate application testing from a backend. For instance, if you don't want to save data to database, and you know the request which performs save, you can mock the request, so application will treat this as valid response, but no data will be actually saved.
 
-![within](https://codecept.io/img/within.png)
+To mock requests enable additional helper [Polly](https://codecept.io/helpers/Polly) (which is based on Polly.js).
+
+```js
+helpers: {
+   Puppeteer: {
+     // regular Puppeteer config here
+   },
+   Polly: {}
+}
+```
+
+And install additional packages:
+
+```
+npm i @pollyjs/core @pollyjs/adapter-puppeteer --save-dev
+```
 
-> [Demo project is available on GitHub](https://github.com/DavertMik/codeceptjs-todomvc-puppeteer)
+After an installation function `mockRequest` will be added to `I` object. You can use it to explicitly define which requests to block and which response they should return instead:
+
+```js
+// block all Google Analytics calls
+I.mockRequest('/google-analytics/*path', 200);
+// return an empty successful response
+I.mockRequest('GET', '/api/users', 200);
+// block post requests to /api/users and return predefined object
+I.mockRequest('POST', '/api/users', { user: 'davert' });
+// return error request with body
+I.mockRequest('GET', '/api/users/1', 404, { error: 'User not found' });
+```
+
+> See [`mockRequest` API](https://codecept.io/helpers/Polly#mockrequest)
+
+To see `mockRequest` method in intellisense auto completion don't forget to run `codeceptjs def` command:
+
+```
+npx codeceptjs def
+```
+
+Mocking rules will be kept while a test is running. To stop mocking use `I.stopMocking()` command
 
 ## Extending
 
@@ -184,7 +228,7 @@ Puppeteer has a very [rich and flexible API](https://github.com/GoogleChrome/pup
 Start with creating an `MyPuppeteer` helper using `generate:helper` or `gh` command:
 
 ```sh
-codeceptjs gh
+npx codeceptjs gh
 ```
 
 Then inside a Helper you can access `Puppeteer` helper of CodeceptJS.
@@ -199,5 +243,7 @@ async renderPageToPdf() {
 }
 ```
 
-The same way you can also access `browser` object to implement more actions or handle events. [Learn more about Helpers](http://codecept.io/helpers/) in the corresponding guide.
+The same way you can also access `browser` object to implement more actions or handle events.
+
+> [▶ Learn more about Helpers](http://codecept.io/helpers/)
 

package/docs/quickstart.md

@@ -4,18 +4,42 @@ title: Quickstart
 ---
 
 **NodeJS v 8.9** and higher required to start.
-CodeceptJS is multi-backend testing framework. It can execute tests using different libraries like webdriverio, Puppeteer, Protractor, etc.
+CodeceptJS is an end 2 end testing framework which supports multiple browser drivers like WebDriver, Puppeteer, Protractor, TestCafe etc.
 
-* In this guide we will use [Google Chrome **Puppeteer**](https://github.com/GoogleChrome/puppeteer) as a driver for browsers. This allows us to start in a minutes with no extra tools installed.
-* If you are familiar with Selenium, you can choose classical [**Selenium WebDriver** setup](#using-selenium-webdriver).
-* Also, look at [complete installation reference](https://codecept.io/installation/).
+> **⬇️ TLDR [Fastest and simplest setup with Puppeteer and CodeceptJS](#using-puppeteer) ⬇️**
 
+How to choose the right driver for your web application?
+Here is a brief comparison of all tools you can use with CodeceptJS.
+
+
+| Driver  | Cross-Browser | Limitations | Headless | Selenuim | Speed |
+|---|---|---|--|--|--|
+| WebDriver  | ✔️ | headers, downloads | ⁉ | ✔️ | normal |
+| Puppeteer  | chrome | cross-browser support | ✔️ | | fast |
+| Protractor | ✔️ | headers, downloads | ⁉ | ✔️ | normal |
+| TestCafe | ✔️  | multiple tabs | ✔️ | | fast |
+| Nightmare | electron (chromium) | multiple tabs, cross-browser  | ✔️ | | fast |
+
+⁉ - headless mode requires additional tools and configuration.
+
+#### How to choose browser driver
+
+* **[Choose Puppeteer](#Using-Puppeteer)** for simplest setup, fast tests, full browser control. Limited to Chrome and Firefox only. Cloud browsers via browserless.io.
+* **[Choose WebDriver](#Using-WebDriver)** or Protractor for classical Selenium. Rich ecosystem and cross browser support with cloud browsers via Sauce Labs, BrowserStack, TestingBot. **Selenium server requried** for local start.
+* **[Choose TestCafe](#Using-TestCafe)** for cheap and fast cross-browser tests. Has stability and feature limitation comparing to WebDriver.
+
+Each driver has its own pros and cons which can't be described in this paragraph. However, in CodeceptJS it is easy to switch between them. In most cases you just need to update a config to run tests differently.
 
 ## Using Puppeteer
 
 
 <video onclick="this.paused ? this.play() : this.pause();" src="/img/codeceptjs-install.mp4" style="width: 100%" controls></video>
 
+0) If you start an empty project, initialize npm first:
+
+```
+npm init -y
+```
 
 1) Install CodeceptJS with Puppeteer
 
@@ -102,17 +126,24 @@ Puppeteer starts a browser without showing its window. To see the browser, edit
 
 Rerun the test to see the browser.
 
-> Next: [CodeceptJS with Puppeteer >>>](https://codecept.io/puppeteer/)
+> [▶ Next: CodeceptJS Basics](https://codecept.io/basics/)
+
+> [▶ Next: CodeceptJS with Puppeteer](https://codecept.io/puppeteer/)
 
-> Next: [CodeceptJS Basics >>>](https://codecept.io/basics/)
 
-> Next: [Demo Project](https://github.com/DavertMik/codeceptjs-todomvc-puppeteer)
 
 
 ---
 
 ## Using Selenium WebDriver
 
+0) If you start an empty project, initialize npm first:
+
+```
+npm init -y
+```
+
+
 1) Install CodeceptJS with webdriverio library
 
 ```
@@ -209,19 +240,23 @@ My First Test --
 ```
 
 
-> Next: [CodeceptJS Basics >>>](https://codecept.io/basics/)
+> [▶ Next: CodeceptJS Basics](https://codecept.io/basics/)
 
-> Next: [Acceptance Testing in CodeceptJS >>>](https://codecept.io/acceptance/)
+> [▶ Next: WebDriver Testing](https://codecept.io/webdriver/)
 
 
 ## Using Protractor
 
-> [**Follow corresponding guide >>**](https://codecept.io/angular/)
+> [▶ Follow corresponding guide](https://codecept.io/angular/)
 
 ## Using Appium
 
-> [**Follow corresponding guide >>**](https://codecept.io/mobile/)
+> [▶ Follow corresponding guide](https://codecept.io/mobile/)
 
 ## Using NightmareJS
 
-> [**Follow corresponding guide >>**](https://codecept.io/nightmare/)
+> [▶ Follow corresponding guide](https://codecept.io/nightmare/)
+
+## Using TestCafe
+
+> [▶ Follow corresponding guide](https://codecept.io/testcafe/)

package/docs/testcafe.md

@@ -0,0 +1,157 @@
+---
+id: testcafe
+title: Testing with TestCafe
+---
+
+[TestCafe](https://devexpress.github.io/testcafe/) is another alternative engine for driving browsers. It is driven by unique technology which provides fast and simple cross browser testing for desktop and mobile browsers. Unlike WebDriver or Puppeteer, TestCafe doesn't control a browser at all. It is not a browser itself, like [Nightmare](https://codecept.io/nightmare) or Cypress. **TestCafe core is a proxy server** that runs behind the scene, and transforms all HTML and JS to include code that is needed for test automation.
+
+![](/img/testcafe.png)
+
+This is very smart idea. But to use TestCafe on daily basis you need to clearly understand its benefits and limitations:
+
+### Pros
+
+* **Fast**. Browser is controlled from inside a web page. This makes test run inside a browser as fast as your browser can render page with no extra network requests.
+* **Simple Cross-Browser Support.** Because TestCafe only launches browsers, it can **automate browser** on desktop or mobile. Unlike WebDriver, you don't need special version of browser and driver to prepare to run tests. Setup simplified. All you need is just a browser installed, and you are ready to go.
+* **Stable to Execution.** Because a test is executed inside a browser, the network latency effects are reduced. Unlike WebDriver you won't hit stale element exceptions, or element not interactable exceptions, as from within a web browser all DOM elements are accessible.
+
+## Cons
+
+* **Magic.** Browsers executed in TestCafe are not aware that they run in test mode. So at some edges automation control can be broken. It's also quite hard to debug possible issues, as you don't know how actually a web page is parsed to inject automation scripts.
+* **No Browser Control.** Because TestCafe do not control browser, you can't actually automate all users actions. For instance, TestCafe can't open new tabs or open a new browser window in incognito mode. There can be also some issues running tests on 3rd party servers or inside iframes.
+* **Simulated Events.** Events like `click` or `doubleClick` are simulated by JavaScript internally. Inside WebDriver or Puppeteer, where those events are dispatched by a browser, called native events. Native events are closer to real user experience. So in some cases simulated events wouldn't represent actual user experience, which can lead to false positive results. For instance, a button which can't be physically clicked by a user, would be clickable inside TestCafe.
+
+Anyway, TestCafe is a good option to start if you need cross browser testing. And here is the **reason to use TestCafe with CodeceptJS: if you hit an edge case or issue, you can easily switch your tests to WebDriver**. As all helpers in CodeceptJS share the same syntax.
+
+CodeceptJS is a rich testing frameworks which also provides features missing in original TestCafe:
+
+* [Cucumber integration](https://codecept.io/bdd)
+* [Real Page Objects](https://codecept.io/pageobjects)
+* [Data Management via API](https://codecept.io/data)
+* and others
+
+## Writing Tests
+
+To start using TestCafe with CodeceptJS install both via NPM
+
+> If you don't have `package.json` in your project, create it with `npm init -y`.
+
+```
+npm i codeceptjs testcafe --save-dev
+```
+
+Then you need to initialize a project, selecting TestCafe when asked:
+
+```
+npx codeceptjs init
+```
+
+A first test should be created with `codeceptjs gt` command
+
+```
+npx codeceptjs gt
+```
+
+In the next example we will [TodoMVC application](http://todomvc.com/examples/angularjs/#/). So let's create a test which will fill in todo list:
+
+```js
+Feature('TodoMVC');
+
+Scenario('create todo item', (I) => {
+  I.amOnPage('http://todomvc.com/examples/angularjs/#/');
+  I.fillField('.new-todo', todo)
+  I.pressKey('Enter');
+  I.seeNumberOfVisibleElements('.todo-list li', 1);
+  I.see('1 item left', '.todo-count');
+});
+```
+
+Same syntax is the same for all helpers in CodeceptJS so to learn more about available commands learn [CodeceptJS Basics](https://codecept.io/basics).
+
+> [▶ Complete list of TestCafe actions](https://codecept.io/helpers/TestCafe)
+
+## Page Objects
+
+Multiple tests can be refactored to share some logic and locators. It is recommended to use PageObjects for this. For instance, in example above, we could create special actions for creating todos and checking them. If we move such methods in a corresponding object a test would look even clearer:
+
+```js
+Scenario('Create a new todo item', async (I, TodosPage) => {
+  I.say('Given I have an empty todo list')
+
+  I.say('When I create a todo "foo"')
+  TodosPage.enterTodo('foo')
+
+  I.say('Then I see the new todo on my list')
+  TodosPage.seeNumberOfTodos(1)
+
+  I.saveScreenshot('create-todo-item.png')
+})
+
+Scenario('Create multiple todo items', async (I, TodosPage) => {
+  I.say('Given I have an empty todo list')
+
+  I.say('When I create todos "foo", "bar" and "baz"')
+  TodosPage.enterTodo('foo')
+  TodosPage.enterTodo('bar')
+  TodosPage.enterTodo('baz')
+
+  I.say('Then I have these 3 todos on my list')
+  TodosPage.seeNumberOfTodos(3)
+
+  I.saveScreenshot('create-multiple-todo-items.png')
+})
+```
+
+> ℹ [Source code of this example](https://github.com/hubidu/codeceptjs-testcafe-todomvc) is available on GitHub.
+
+A PageObject can be injected into a test by its name. Here is how TodosPage looks like:
+
+```js
+// inside todos_page.js
+const { I } = inject();
+
+module.exports = {
+    goto() {
+        I.amOnPage('http://todomvc.com/examples/angularjs/#/')
+    },
+
+    enterTodo(todo) {
+        I.fillField('.new-todo', todo)
+        I.pressKey('Enter')
+    },
+
+    seeNumberOfTodos(numberOfTodos) {
+        I.seeNumberOfVisibleElements('.todo-list li', numberOfTodos)
+    },
+}
+```
+
+> [▶ Read more about PageObjects in CodeceptJS](https://codecept.io/pageobjects)
+
+## Extending
+
+If you want to use TestCafe API inside your tests you can put them into actions of `I` object. To do so you can generate a new helper, access TestCafe helper, and get the test controller.
+
+Create a helper using `codecepjs gh` command.
+
+```
+npx codeceptjs gh
+```
+
+All methods of newly created class will be added to `I` object.
+
+```js
+const Helper = codeceptjs.helper;
+
+class MyTestCafe extends Helper {
+
+  slowlyFillField(field, text) {
+    // import test controller from TestCafe helper
+    const { t } = this.helpers.TestCafe;
+    // use TestCafe API here
+    return t.setTestSpeed(0.1)
+        .typeText(field, text);
+  }
+
+}
+```