codeceptjs 3.4.1 → 3.5.1-2.beta.7

package/docs/mobile.md

@@ -1,297 +0,0 @@
----
-permalink: /mobile
-title: Mobile Testing with Appium
----
-
-# Mobile Testing with Appium
-
-CodeceptJS allows to test mobile and hybrid apps in a similar manner web applications are tested.
-Such tests are executed using [Appium](https://appium.io) on emulated or physical devices. Also, Appium allows to test web application on mobile devices.
-
-What makes CodeceptJS better for mobile testing?
-Take a look. Here is the sample test for a native mobile application written in CodeceptJS:
-
-```js
-I.seeAppIsInstalled("io.super.app");
-I.click('~startUserRegistrationCD');
-I.fillField('~email of the customer', 'Nothing special');
-I.see('davert@codecept.io', '~email of the customer');
-I.clearField('~email of the customer');
-I.dontSee('Nothing special', '~email of the customer');
-I.seeElement({
-  android: 'android.widget.Button',
-  ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'
-});
-```
-
-This test is easy to read and write. Also it will work both on iOS and Android devices.
-Doesn't it sound cool?
-
-## Setting Up
-
-Ensure that you have [CodeceptJS installed](https://codecept.io/installation/).
-You will also need to install [Appium](https://appium.io/).
-We suggest to use [appium-doctor](https://www.npmjs.com/package/appium-doctor) to check if your system is ready for mobile testing.
-
-```sh
-npm i -g appium-doctor
-```
-
-If everything is OK, continue with installing Appium. If not, consider using cloud based alternatives like [SauceLabs](https://saucelabs.com) or [BrowserStack](https://browserstack.com). Cloud services provide hosted appium with real and emulated mobile devices.
-
-To install Appium use npm:
-
-```sh
-npm i -g appium
-```
-
-Then you need to prepare application for execution.
-It should be packed into apk (for Android) or .ipa (for iOS) or zip.
-
-Next, is to launch the emulator or connect physical device.
-Once they are prepared, launch Appium:
-
-```sh
-appium
-```
-
-To run mobile test you need either an device emulator (available with Android SDK or iOS), real device connected for mobile testing. Alternatively, you may execute Appium with device emulator inside Docker container.
-
-CodeceptJS should be installed with webdriverio support:
-
-```bash
-npm install codeceptjs webdriverio --save
-```
-
-## Configuring
-
-Initialize CodeceptJS with `init` command:
-
-```sh
-npx codeceptjs init
-```
-
-Select [Appium helper](https://codecept.io/helpers/Appium/) when asked.
-
-```sh
-? What helpers do you want to use?
- ◯ WebDriver
- ◯ Protractor
- ◯ Puppeteer
- ◯ Nightmare
-❯◉ Appium
- ◯ REST
-```
-
-You will also be asked for the platform and the application package.
-
-```sh
-? [Appium] Application package. Path to file or url
-```
-
-Check the newly created `codecept.conf.js` configuration file.
-You may want to set some additional Appium settings via [desiredCapabilities](https://appium.io/docs/en/writing-running-appium/caps/)
-
-```js
-helpers: {
-  Appium: {
-    app: "my_app.apk",
-    platform: "Android",
-    desiredCapabilities: {}
-  }
-}
-```
-
-Once you configured Appium, create the first test by running
-
-```sh
-npx codeceptjs gt
-```
-
-## BrowserStack Configuration
-
-If you wish to use BrowserStack's [Automated Mobile App Testing](https://www.browserstack.com/app-automate) platform. Configure the Appium helper like this:
-
-```js
-helpers: {
-  Appium: {
-    app: "bs://<hashed app-id>",
-    host: "hub-cloud.browserstack.com",
-    port: 4444,
-    platform: "ios",
-    user: "BROWSERSTACK_USER",
-    key: "BROWSERSTACK_KEY",
-    device: "iPhone 7"
-  }
-}
-```
-Here is the full list of [capabilities](https://www.browserstack.com/app-automate/capabilities).
-
-You need to upload your Android app (.apk) or iOS app (.ipa) to the BrowserStack servers using the REST API before running your tests. The App URL (`bs://hashed appid`) is returned in the response of this call.
-
-```sh
-curl -u "USERNAME:ACCESS_KEY" \
--X POST "https://api-cloud.browserstack.com/app-automate/upload" \
--F "file=@/path/to/app/file/Application-debug.apk"
-```
-
-## Writing a Test
-
-A test is written in a scenario-driven manner, listing an actions taken by a user.
-This is the sample test for a native mobile application:
-
-```js
-Scenario('test registration', ({ I }) => {
-  I.click('~startUserRegistrationCD');
-  I.fillField('~inputUsername', 'davert');
-  I.fillField('~inputEmail', 'davert@codecept.io');
-  I.fillField('~inputPassword', '123456');
-  I.hideDeviceKeyboard();
-  I.click('~input_preferredProgrammingLanguage');
-  I.click('Javascript');
-  I.checkOption('#io.demo.testapp:id/input_adds');
-  I.click('Register User (verify)');
-  I.swipeUp("#io.selendroid.testapp:id/LinearLayout1");
-  I.see('Javascript'); // see on the screen
-  I.see('davert', '~label_username_data'); // see in element
-});
-```
-
-Mobile test is pretty similar to a web test. And it is much the same, if you test hybrid app with a web view context inside.
-However, mobile apps do not have URLs, Cookies, they have other features which may vary on a running platform.
-
-There are mobile-only methods like:
-
-* `swipeUp`, `swipeLeft`, ...
-* `hideDeviceKeyboard`,
-* `seeAppIsInstalled`, `installApp`, `removeApp`, `seeAppIsNotInstalled` - Android only
-
-and [others](https://codecept.io/helpers/Appium/).
-
-## Locating Elements
-
-To start writing a test it is important to understand how to locate elements for native mobile applications.
-In both Android and iPhone elements are defined in XML format and can be searched by XPath locators.
-
-```js
-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.
-Accessibility id is recommended to use for locating element, as it rarely changed.
-
-* 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
-* 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:
-
-```js
-I.seeElement('~startUserRegistrationButton');
-```
-
-Elements can also have ids, which can be located with `#` prefix.
-On Android it it is important to keep full package name in id locator:
-
-```js
-I.seeElement('#io.selendroid.testapp:id/inputUsername');
-```
-
-Buttons can be matched by their visible text:
-
-```js
-I.tap('Click me!');
-I.click('Click me!');
-```
-
-Native iOS/Android locators can be used with `android=` and `ios=` prefixes. [Learn more](https://webdriver.io/guide/usage/selectors.html#Mobile-Selectors).
-
-But how to get all those locators? We recommend to use [Appium Inspector](https://github.com/appium/appium-desktop).
-
-For Android you can use **UI Automator Viewer** bundled with Android SDK:
-
-![](https://user-images.githubusercontent.com/220264/27566310-1f631604-5aed-11e7-8b92-1ffe9e9f14f9.png)
-
-## Hybrid Apps and Contexts
-
-Mobile applications may have different contexts. For instance, there can be native view and web view with a browser instance in it.
-
-To execute commands in context of a webview use `within('webview')` function:
-
-```js
-I.click('~startWebView');
-within('webview', () => {
-  I.see('Preferred car');
-  I.click('Send me your name!');
-});
-```
-
-It will locate first available webview, switch to it, and switch back to native application after.
-Inside WebView all browser features are enabled: CSS locators, JavaScript, etc.
-
-To set a specific context use `{ web: 'webview.context' }` instead:
-
-```js
-within({webview: 'MyWEBVIEW_com.my.app'}, () => );
-```
-
-Alternatively use `switchToWeb` or `switchToNative` methods to switch between contexts.
-
-```js
-I.click('~startWebView');
-I.switchToWeb();
-I.see('Preferred car');
-I.click('Send me your name!');
-I.switchToNative();
-```
-
-To get a list of all contexts use `grabAllContexts` method:
-
-```js
-let contexts = await I.grabAllContexts();
-```
-
-## Cross-Platform Testing
-
-It is often happen that mobile applications behave similarly on different platforms. Can we build one test for them? Yes!
-CodeceptJS provides a way to specify different locators for Android and iOS platforms:
-
-```js
-I.click({android: '//android.widget.Button', ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'});
-```
-
-In case some code should be executed on one platform and ignored on others use `runOnAndroid` and `runOnIOS` methods:
-
-```js
-I.runOnAndroid(() => {
-  I.click('Hello Android');
-});
-I.runOnIOS(() => {
-  I.click('Hello iOS');
-});
-```
-
-The same code can be shared for web applications as well. To execute some code in web browser only, use `I.runInWeb`:
-
-```js
-I.runInWeb(() => {
-  I.amOnPage('/login'); // not available for mobile
-  I.fillField('name', 'jon');
-  I.fillField('password', '123456');
-  I.click('Login');
-  I.waitForElement('#success'); // no available for mobile
-});
-```
-
-Just as you can specify android, and ios-specific locators, you can do so for web:
-
-```js
-I.click({web: '#login', ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'});
-```

package/docs/nightmare.md

@@ -1,223 +0,0 @@
----
-permalink: /nightmare
-title: Testing with Nightmare
----
-
-# Testing with Nightmare
-
-Selenium WebDriver is considered to be standard for end to end testing of web applications.
-Despite its popularity it have its drawbacks, it requires a real browser and Selenium server to control it.
-This hardens setting it up testing environment for CI server and slows down test execution.
-
-Is there a sane alternative to Selenium?
-
-Yes, how about [NightmareJS](https://www.nightmarejs.org)?
-
-It is modern Electron based testing framework which allows to execute tests in headless mode as well as in window mode for debug purposes.
-This makes Nightmare very useful, much more handy than PhantomJS. Nightmare is in active development and has nice API for writing acceptance tests.
-Unfortunately, as all other JavaScript testing frameworks it has its own very custom API.
-What if you choose it for a project and suddenly you realize that you need something more powerful, like Selenium?
-Yes, that might be a problem if you are not using CodeceptJS.
-The one idea behind CodeceptJS is to unify different testing backends under one API, so you could easily write tests the same way no matter what engines you use: webdriverio, Protractor, or Nightmare.
-
-Compare a test written using Nightmare API:
-
-```js
-nightmare
-  .goto('http://yahoo.com')
-  .type('form[action*="/search"] [name=p]', 'github nightmare')
-  .click('form[action*="/search"] [type=submit]')
-  .wait('#main')
-  .evaluate(function () {
-    return document.querySelector('#main .searchCenterMiddle li a').href
-  })
-```
-
-with a similar CodeceptJS test:
-
-```js
-  I.amOnPage('http://yahoo.com');
-  I.fillField('p', 'github nightmare');
-  I.click('Search Web');
-  I.waitForElement('#main');
-  I.seeElement('#main .searchCenterMiddle li a');
-  I.seeElement("//a[contains(@href,'github.com/segmentio/nightmare')]");
-  I.see('segmentio/nightmare','#main li a');
-```
-
-NightmareJS support only CSS locators for web elements, while CodeceptJS improves it to use XPath as well.
-This is how form can be located by labels, and buttons by text in examples above. It is done by injecting
-client-side scrips (for element location) to every loaded page. Also all events like click, doubleClick, keyPress are **simulated** by JavaScript,
-this makes testing less relevant, as they are not native to operating systems.
-
-## How Fast Is Nightmare JS?
-
-Let's execute the test above within WebDriver using headless Firefox + Selenium Server packed in Docker container.
-
-```sh
-docker run -d -p 4444:4444 selenium/standalone-firefox:2.53.0
-codeceptjs run yahoo_test.js --steps
-```
-
-This provides use with output:
-
-```sh
- Yahoo basic test
- > WebDriver._before
- • I am on page "http://yahoo.com"
- • I fill field "p", "github nightmare"
- • I click "Search Web"
- • I wait for element "#main", 2
- • I see element "#main .searchCenterMiddle li a"
- • I see "segmentio/nightmare", "li a"
- ✓ OK in 17591ms
-```
-
-When we switch helper to Nightmare:
-
-```sh
- Yahoo basic test
- > Nightmare._before
- • I am on page "http://yahoo.com"
- • I fill field "p", "github nightmare"
- • I click "Search Web"
- • I wait for element "#main", 2
- • I see element "#main .searchCenterMiddle li a"
- • I see "segmentio/nightmare", "li a"
- ✓ OK in 5490ms
-```
-
-As you see the Nightmare test was almost **3 times faster** than Selenium test.
-Sure, this can't be taken as a valuable benchmark but more like a proof of concept.
-
-## Setup
-
-To start you need CodeceptJS with nightmare package installed.
-
-```bash
-npm install -g nightmare
-```
-
-And a basic project initialized
-
-```sh
-codeceptjs init
-```
-
-You will be asked for a Helper to use, you should select Nightmare and provide url of a website you are testing.
-Setup process is explained on [QuickStart page](https://codecept.io/quickstart/).
-
-(If you already have CodeceptJS project, just install nightmare globally or locally and enable it in config)
-
-## Configuring Nightmare
-
-Enable `Nightmare` helper in `codecept.json` config:
-
-```js
-{ // ..
-  "helpers": {
-    "Nightmare": {
-      "url": "http://localhost",
-      "show": false,
-      "restart": false
-    }
-  }
-  // ..
-}
-```
-
-Turn on the `show` option if you want to follow test progress in a window. This is very useful for debugging.
-All other options can be taken from [NightmareJS API](https://github.com/segmentio/nightmare#api).
-
-Turn off the `restart` option if you want to run your suite in a single browser instance.
-
-Option `waitForAction` defines how long to wait after a click, doubleClick or pressKey action is performed.
-Test execution may happen much faster than the response is rendered, so make sure you set a proper delay value.
-By default CodeceptJS waits for 500ms.
-
-## Opening a Web Page
-
-Nightmare provides you with more control to browser engine than Selenium does.
-This allows you to use headers in your tests. For instance, CodeceptJS provides `haveHeader` method
-to set default headers for all your HTTP requests:
-
-```js
-I.haveHeader('x-tested-with', 'codeceptjs');
-```
-
-When opening a web page you can set headers as well. `amOnPage` methods can take headers as second parameter:
-
-```js
-// use basic http auth
-I.amOnPage('/admin', { 'Authorization': 'Basic '+token });
-```
-
-As a small bonus: all `console.log` calls on a page will be also shown in `--debug` mode.
-
-## Manipulating Web Page
-
-Nightmare helper is supposed to work in the same manner as WebDriver or Protractor.
-This means that all CodeceptJS actions like `click`, `fillField`, `selectOption` and others are supposed to work in the very same manner.
-They are expressive and flexible to accept CSS, XPath, names, values, or strict locators. Follow the helper reference for detailed description.
-
-Assertions start with `see` prefix. You can check text on a page, elements on page and others.
-
-## Extending Nightmare Helper
-
-CodeceptJS allows you to define and connect own helpers. If some functionality of
-Nightmare helper is missing you can easily create `ExtendedNightmare` helper by running:
-
-```sh
-codeceptjs gh
-```
-
-Learn more about [Helpers](https://codecept.io/helpers/).
-
-Nightmare instance can be accessed by custom helper:
-
-```js
-// returns current nightmare instance
-this.helpers['Nightmare'].browser;
-```
-
-This way you can call [native Nightmare commands](https://github.com/segmentio/nightmare#interact-with-the-page).
-
-It is important to understand that Nightmare executes JavaScript on client and on server side.
-If you need to find an element you should search for it using client side script, but if you want
-to do an assertion you should return a data to server side.
-
-Nightmare provides `evaluate` method to execute client-side JavaScript. CodeceptJS registers `codeceptjs`
-object globally on client side with `findElement` and `findElements` methods in it. They return IDs of matched elements
-so you can access them in next calls to `evaluate`:
-
-```js
-// inside a custom helper class
-async seeAttributeContains(locator, attribute, expectedValue) {
-  // let's use chai assertion library
-  const assert = require('chai').assert;
-  // get nightmare instance
-  const browser = this.helpers['Nightmare'].browser;
-  // find an element by CSS or XPath:
-  const els = await this.helpers['Nightmare']._locate(locator);
-    // we received an array with IDs of matched elements
-    // now let's execute client-side script to get attribute for the first element
-  const attributeValue = await browser.evaluate(function(el, attribute) {
-      // this is executed inside a web page!
-      return codeceptjs.fetchElement(el).getAttribute(attribute);
-  }, els[0], attribute); // function + its params
-
-    // get attribute value and back to server side
-    // execute an assertion
-  assert.include(attributeValue, expectedValue);
-}
-```
-
-It can be used in tests like:
-
-```js
-I.seeAttributeContains('#main img', 'src', '/cat.jpg');
-```
-
-This sample assertion used `_locate` helper method which searched for elements
-by CSS/XPath or a strict locator. Then `browser.evaluate` method was called to
-use locate found elements on a page and return attribute from the first of them.