codeceptjs 3.5.12-beta.2 → 3.5.12-beta.3

package/docs/mobile.md

@@ -1,338 +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/docs/en/2.1/).
-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
-```
-
-Appium 2x reenvisions Appium as a platform where “drivers” and “plugins” can be easily created and shared independently.
-
-** Note: ** Appium v1 is no longer maintained, so it's advised to migrate to Appium v2.
-
-Install an Appium driver and its dependencies
-To install the Appium driver and its dependencies, we'll be using the `uiautomator2` (Android), `XCUITest` (iOS) drivers.
-
-```
-appium driver install xcuitest
-appium driver install uiautomator2
-```
-To make sure that all the drivers are installed successfully, run the following command:
-
-```
-appium driver list
-
-tth~$appium driver list            
-✔ Listing available drivers
-- espresso@2.17.0 [installed (NPM)]
-- uiautomator2@2.12.6 [installed (NPM)]
-- xcuitest@4.19.1 [installed (NPM)]
-- mac2 [not installed]
-- safari [not installed]
-- gecko [not installed]
-- chromium [not installed]
-```
-
-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 a physical device.
-Once they are prepared, launch Appium:
-
-```sh
-tth~$npx appium --base-path=/wd/hub
-[Appium] Welcome to Appium v2.0.0-beta.57 (REV 3e675c32ae71dc0b00749d5d29213e2ea5b53c5b)
-[Appium] Non-default server args:
-[Appium] {
-[Appium]   basePath: '/wd/hub'
-[Appium] }
-[Appium] Attempting to load driver espresso...
-[debug] [Appium] Requiring driver at /Users/trung-thanh/Desktop/thanh-nguyen/task2/node_modules/appium-espresso-driver
-[Appium] Attempting to load driver uiautomator2...
-[debug] [Appium] Requiring driver at /Users/trung-thanh/Desktop/thanh-nguyen/task2/node_modules/appium-uiautomator2-driver
-[Appium] Appium REST http interface listener started on 0.0.0.0:4723
-[Appium] Available drivers:
-[Appium]   - espresso@2.17.0 (automationName 'Espresso')
-[Appium]   - uiautomator2@2.12.6 (automationName 'UiAutomator2')
-[Appium] No plugins have been installed. Use the "appium plugin" command to install the one(s) you want to use.
-```
-
-** Note: ** Appium v2 doesn't use the same base path as Appium v1, hence if you want to use the same base path you should pass `--base-path=/wd/hub` when launching the Appium server.
-
-To run mobile test you need either a device emulator (available with Android SDK or iOS) or 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@8.6.3 --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
- ◯ Puppeteer
-❯◉ 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/2.1/guides/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 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-inspector).
-
-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/pageobjects.md

@@ -1,291 +0,0 @@
----
-permalink: /pageobjects
-title: Page Objects
----
-
-# Page Objects
-
-The UI of your web application has interaction areas which can be shared across different tests.
-To avoid code duplication you can put common locators and methods in one place.
-
-## Dependency Injection
-
-All objects described here are injected via Dependency Injection, in a similar way AngularJS does. If you want an object to be injected in a scenario by its name, you can add it to the configuration:
-
-```js
-  include: {
-    I: "./custom_steps.js",
-    Smth: "./pages/Smth.js",
-    loginPage: "./pages/Login.js",
-    signinFragment: "./fragments/Signin.js"
-  }
-```
-
-These objects can now be retrieved by the name specified in the configuration.
-
-Required objects can be obtained via parameters in tests or via a global `inject()` call.
-
-```js
-// globally inject objects by name
-const { I, myPage, mySteps } = inject();
-
-// inject objects for a test by name
-Scenario('sample test', ({ I, myPage, mySteps }) => {
-  // ...
-});
-```
-
-## Actor
-
-During initialization you were asked to create a custom steps file. If you accepted this option, you are now able to use the `custom_steps.js` file to extend `I`. See how the `login` method can be added to `I`:
-
-```js
-module.exports = function() {
-  return actor({
-
-    login: function(email, password) {
-      this.fillField('Email', email);
-      this.fillField('Password', password);
-      this.click('Submit');
-    }
-  });
-}
-```
-
-> ℹ Instead of `I` you should use `this` in the current context.
-
-## PageObject
-
-If an application has different pages (login, admin, etc) you should use a page object.
-CodeceptJS can generate a template for it with the following command:
-
-```sh
-npx codeceptjs gpo
-```
-
-This will create a sample template for a page object and include it in the `codecept.json` config file.
-
-```js
-const { I, otherPage } = inject();
-
-module.exports = {
-
-  // insert your locators and methods here
-}
-```
-
-As you see, the `I` object is available in scope, so you can use it just like you would do in tests.
-A general page object for a login page could look like this:
-
-```js
-// enable I and another page object
-const { I, registerPage } = inject();
-
-module.exports = {
-
-  // setting locators
-  fields: {
-    email: '#user_basic_email',
-    password: '#user_basic_password'
-  },
-  submitButton: {css: '#new_user_basic input[type=submit]'},
-
-  // introducing methods
-  sendForm(email, password) {
-    I.fillField(this.fields.email, email);
-    I.fillField(this.fields.password, password);
-    I.click(this.submitButton);
-  },
-
-  register(email, password) {
-    // use another page object inside current one
-    registerPage.registerUser({ email, password });
-  }
-}
-```
-
-You can include this pageobject in a test by its name (defined in `codecept.json`). If you created a `loginPage` object,
-it should be added to the list of arguments to be included in the test:
-
-```js
-Scenario('login', ({ I, loginPage }) => {
-  loginPage.sendForm('john@doe.com','123456');
-  I.see('Hello, John');
-});
-```
-
-Also, you can use `async/await` inside a Page Object:
-
-```js
-const { I } = inject();
-
-module.exports = {
-
-  // setting locators
-  container: "//div[@class = 'numbers']",
-  mainItem: {
-    number: ".//div[contains(@class, 'numbers__main-number')]",
-    title: ".//div[contains(@class, 'numbers__main-title-block')]"
-  },
-
-  // introducing methods
-  async openMainArticle() {
-    I.waitForVisible(this.container)
-    let _this = this
-    let title;
-    await within(this.container, async () => {
-      title = await I.grabTextFrom(_this.mainItem.number);
-      let subtitle = await I.grabTextFrom(_this.mainItem.title);
-      title = title + " " + subtitle.charAt(0).toLowerCase() + subtitle.slice(1);
-      await I.click(_this.mainItem.title)
-    })
-    return title;
-  }
-}
-```
-
-and use them in your tests:
-
-```js
-Scenario('login2', async ({ I, loginPage, basePage }) => {
-  let title = await mainPage.openMainArticle()
-  basePage.pageShouldBeOpened(title)
-});
-```
-
-Page Objects can be be functions, arrays or classes. When declared as classes you can easily extend them in other page objects.
-
-Here is an example of declaring page object as a class:
-
-```js
-const { expect } = require('chai');
-const { I } = inject();
-
-class AttachFile {
-  constructor() {
-    this.inputFileField = 'input[name=fileUpload]';
-    this.fileSize = '.file-size';
-    this.fileName = '.file-name'
-  }
-
-  async attachFileFrom(path) {
-    await I.waitForVisible(this.inputFileField)
-    await I.attachFile(this.inputFileField, path)
-  }
-
-  async hasFileSize(fileSizeText) {
-    await I.waitForElement(this.fileSize)
-    const size = await I.grabTextFrom(this.fileSize)
-    expect(size).toEqual(fileSizeText)
-  }
-
-  async hasFileSizeInPosition(fileNameText, position) {
-    await I.waitNumberOfVisibleElements(this.fileName, position)
-    const text = await I.grabTextFrom(this.fileName)
-    expect(text[position - 1]).toEqual(fileNameText)
-  }
-}
-
-// For inheritance
-module.exports = new AttachFile();
-module.exports.AttachFile = AttachFile;
-```
-
-> ⚠ While building complex page objects it is important to keep all `async` functions to be called with `await`. While CodeceptJS allows to run commands synchronously if async function has `I.grab*` or any custom function that returns a promise it must be called with `await`. If you see `UnhandledPromiseRejectionWarning` it might be caused by async page object function that was called without `await`.
-
-## Page Fragments
-
-Similarly, CodeceptJS allows you to generate **PageFragments** and any other abstractions
-by running the `go` command with `--type` (or `-t`) option:
-
-```sh
-npx codeceptjs go --type fragment
-```
-
-Page Fragments represent autonomous parts of a page, like modal boxes, components, widgets.
-Technically, they are the same as PageObject but conceptually they are a bit different.
-For instance, it is recommended that Page Fragment includes a root locator of a component.
-Methods of page fragments can use `within` block to narrow scope to a root locator:
-
-```js
-const { I } = inject();
-// fragments/modal.js
-module.exports = {
-
-  root: '#modal',
-
-  // we are clicking "Accept: inside a popup window
-  accept() {
-    within(this.root, function() {
-      I.click('Accept');
-    });
-  }
-}
-```
-
-To use a Page Fragment within a Test Scenario, just inject it into your Scenario:
-
-```js
-Scenario('failed_login', async ({ I, loginPage, modal }) => {
-  loginPage.sendForm('john@doe.com','wrong password');
-  I.waitForVisible(modal.root);
-  within(modal.root, function () {
-    I.see('Login failed');
-  })
-});
-```
-
-To use a Page Fragment within a Page Object, you can use `inject` method to get it by its name.
-
-```js
-const { I, modal } = inject();
-
-module.exports = {
-  doStuff() {
-    ...
-    modal.accept();
-    ...
-  }
-}
-```
-
-> PageObject and PageFragment names are declared inside `include` section of `codecept.conf.js`. See [Dependency Injection](#dependency-injection)
-
-## StepObjects
-
-StepObjects represent complex actions which involve the usage of multiple web pages. For instance, creating users in the backend, changing permissions, etc.
-StepObject can be created similarly to PageObjects or PageFragments:
-
-```sh
-npx codeceptjs go --type step
-```
-
-Technically, they are the same as PageObjects. StepObjects can inject PageObjects and use multiple POs to make a complex scenarios:
-
-```js
-const { I, userPage, permissionPage } = inject();
-
-module.exports = {
-
-  createUser(name) {
-    // action composed from actions of page objects
-    userPage.open();
-    userPage.create(name);
-    permissionPage.activate(name);
-  }
-
-};
-```
-
-## Dynamic Injection
-
-You can inject objects per test by calling `injectDependencies` function in a Scenario:
-
-```js
-Scenario('search @grop', ({ I, Data }) => {
-  I.fillField('Username', Data.username);
-  I.pressKey('Enter');
-}).injectDependencies({ Data: require('./data.js') });
-```
-
-This requires the `./data.js` module and assigns it to a `Data` argument in a test.