codeceptjs 3.5.0 → 3.5.1-2.beta.7

package/docs/internal-api.md

@@ -1,265 +0,0 @@
----
-permalink: /internal-api
-title: Internal API
----
-
-## Concepts
-
-In this guide we will overview the internal API of CodeceptJS.
-This knowledge is required for customization, writing plugins, etc.
-
-CodeceptJS provides an API which can be loaded via `require('codeceptjs')` when CodeceptJS is installed locally. Otherwise, you can load codeceptjs API via global `codeceptjs` object:
-
-```js
-// via module
-const { recorder, event, output } = require('codeceptjs');
-// or using global object
-const { recorder, event, output } = codeceptjs;
-```
-
-These internal objects are available:
-
-* [`codecept`](https://github.com/Codeception/CodeceptJS/blob/master/lib/codecept.js): test runner class
-* [`config`](https://github.com/Codeception/CodeceptJS/blob/master/lib/config.js): current codecept config
-* [`event`](https://github.com/Codeception/CodeceptJS/blob/master/lib/event.js): event listener
-* [`recorder`](https://github.com/Codeception/CodeceptJS/blob/master/lib/recorder.js): global promise chain
-* [`output`](https://github.com/Codeception/CodeceptJS/blob/master/lib/output.js): internal printer
-* [`container`](https://github.com/Codeception/CodeceptJS/blob/master/lib/container.js): dependency injection container for tests, includes current helpers and support objects
-* [`helper`](https://github.com/Codeception/CodeceptJS/blob/master/lib/helper.js): basic helper class
-* [`actor`](https://github.com/Codeception/CodeceptJS/blob/master/lib/actor.js): basic actor (I) class
-
-[API reference](https://github.com/Codeception/CodeceptJS/tree/master/docs/api) is available on GitHub.
-Also please check the source code of corresponding modules.
-
-### Container
-
-CodeceptJS has a dependency injection container with helpers and support objects.
-They can be retrieved from the container:
-
-```js
-const { container } = require('codeceptjs');
-
-// get object with all helpers
-const helpers = container.helpers();
-
-// get helper by name
-const { WebDriver } = container.helpers();
-
-// get support objects
-const supportObjects = container.support();
-
-// get support object by name
-const { UserPage } = container.support();
-
-// get all registered plugins
-const plugins = container.plugins();
-```
-
-New objects can also be added to container in runtime:
-
-```js
-const { container } = require('codeceptjs');
-
-container.append({
-  helpers: { // add helper
-    MyHelper: new MyHelper({ config1: 'val1' });
-  },
-  support: { // add page object
-    UserPage: require('./pages/user');
-  }
-})
-```
-
-> Use this trick to define custom objects inside `boostrap` script
-
-The container also contains the current Mocha instance:
-
-```js
-const mocha = container.mocha();
-```
-
-### Event Listeners
-
-CodeceptJS provides a module with an [event dispatcher and set of predefined events](https://github.com/Codeception/CodeceptJS/blob/master/lib/event.js).
-
-It can be required from codeceptjs package if it is installed locally.
-
-```js
-const { event } = require('codeceptjs');
-
-module.exports = function() {
-
-  event.dispatcher.on(event.test.before, function (test) {
-
-    console.log('--- I am before test --');
-
-  });
-}
-```
-
-Available events:
-
-* `event.test.before(test)` - *async* when `Before` hooks from helpers and from test is executed
-* `event.test.after(test)` - *async* after each test
-* `event.test.started(test)` - *sync* at the very beginning of a test.
-* `event.test.passed(test)` - *sync* when test passed
-* `event.test.failed(test, error)` - *sync* when test failed
-* `event.test.finished(test)` - *sync* when test finished
-* `event.suite.before(suite)` - *async* before a suite
-* `event.suite.after(suite)` - *async* after a suite
-* `event.step.before(step)` - *async* when the step is scheduled for execution
-* `event.step.after(step)`- *async* after a step
-* `event.step.started(step)` - *sync* when step starts.
-* `event.step.passed(step)` - *sync* when step passed.
-* `event.step.failed(step, err)` - *sync* when step failed.
-* `event.step.finished(step)` - *sync* when step finishes.
-* `event.step.comment(step)` - *sync* fired for comments like `I.say`.
-* `event.all.before` - before running tests
-* `event.all.after` - after running tests
-* `event.all.result` - when results are printed
-* `event.workers.before` - before spawning workers in parallel run
-* `event.workers.after` - after workers finished in parallel run
-
-
-> *sync* - means that event is fired in the moment of the action happening.
- *async* - means that event is fired when an action is scheduled. Use `recorder` to schedule your actions.
-
-For further reference look for [currently available listeners](https://github.com/Codeception/CodeceptJS/tree/master/lib/listener) using the event system.
-
-
-### Recorder
-
-To inject asynchronous functions in a test or before/after a test you can subscribe to corresponding event and register a function inside a recorder object. [Recorder](https://github.com/Codeception/CodeceptJS/blob/master/lib/recorder.js) represents a global promises chain.
-
-Provide a function in the first parameter, a function must be async or must return a promise:
-
-```js
-const { event, recorder } = require('codeceptjs');
-
-module.exports = function() {
-
-  event.dispatcher.on(event.test.before, function (test) {
-
-    const request = require('request');
-
-    recorder.add('create fixture data via API', function() {
-      return new Promise((doneFn, errFn) => {
-        request({
-          baseUrl: 'http://api.site.com/',
-          method: 'POST',
-          url: '/users',
-          json: { name: 'john', email: 'john@john.com' }
-        }), (err, httpResponse, body) => {
-          if (err) return errFn(err);
-          doneFn();
-        }
-      });
-    }
-  });
-}
-```
-
-### Config
-
-CodeceptJS config can be accessed from `require('codeceptjs').config.get()`:
-
-```js
-const { config } = require('codeceptjs');
-
-// config object has access to all values of the current config file
-
-if (config.get().myKey == 'value') {
-  // run something
-}
-```
-
-
-### Output
-
-Output module provides four verbosity levels. Depending on the mode you can have different information printed using corresponding functions.
-
-* `default`: prints basic information using `output.print`
-* `steps`: toggled by `--steps` option, prints step execution
-* `debug`: toggled by `--debug` option, prints steps, and debug information with `output.debug`
-* `verbose`: toggled by `--verbose` prints debug information and internal logs with `output.log`
-
-It is recommended to avoid `console.log` and use output.* methods for printing.
-
-```js
-const output = require('codeceptjs').output;
-
-output.print('This is basic information');
-output.debug('This is debug information');
-output.log('This is verbose logging information');
-```
-
-#### Test Object
-
-The test events are providing a test object with following properties:
-
-* `title` title of the test
-* `body` test function as a string
-* `opts` additional test options like retries, and others
-* `pending` true if test is scheduled for execution and false if a test has finished
-* `tags` array of tags for this test
-* `artifacts` list of files attached to this test. Screenshots, videos and other files can be saved here and shared accross different reporters
-* `file` path to a file with a test
-* `steps` array of executed steps (available only in `test.passed`, `test.failed`, `test.finished` event)
-* `skipInfo` additional test options when test skipped 
-* * `message` string with reason for skip
-* * `description` string with test body
-and others
-
-#### Step Object
-
-Step events provide step objects with following fields:
-
-* `name` name of a step, like 'see', 'click', and others
-* `actor` current actor, in most cases it is `I`
-* `helper` current helper instance used to execute this step
-* `helperMethod` corresponding helper method, in most cases is the same as `name`
-* `status` status of a step (passed or failed)
-* `prefix` if a step is executed inside `within` block contain within text, like: 'Within .js-signup-form'.
-* `args` passed arguments
-
-Whenever you execute tests with `--verbose` option you will see registered events and promises executed by a recorder.
-
-## Custom Runner
-
-You can run CodeceptJS tests from your script.
-
-```js
-const { codecept: Codecept } = require('codeceptjs');
-
-// define main config
-const config = { 
-  helpers: { 
-    WebDriver: { 
-      browser: 'chrome', 
-      url: 'http://localhost' 
-    }
-  }
-};
-
-const opts = { steps: true };
-
-// run CodeceptJS inside async function
-(async () => {
-  const codecept = new Codecept(config, options);
-  codecept.init(__dirname);
-
-  try {
-    await codecept.bootstrap();
-    codecept.loadTests('**_test.js');
-    // run tests
-    await codecept.run(test);
-  } catch (err) {
-    printError(err);
-    process.exitCode = 1;
-  } finally {
-    await codecept.teardown();
-  }    
-})();
-```
-
-> Also, you can run tests inside workers in a custom scripts. Please refer to the [parallel execution](/parallel) guide for more details.

package/docs/locators.md

@@ -1,331 +0,0 @@
----
-permalink: /locators
-title: Locators
----
-
-# Locators
-
-CodeceptJS provides flexible strategies for locating elements:
-
-* [CSS and XPath locators](#css-and-xpath)
-* [Semantic locators](#semantic-locators): by link text, by button text, by field names, etc.
-* [Locator Builder](#locator-builder)
-* [ID locators](#id-locators): by CSS id or by accessibility id
-* [Custom Locator Strategies](#custom-locators): by data attributes or whatever you prefer.
-* [Shadow DOM](/shadow): to access shadow dom elements
-* [React](/react): to access React elements by component names and props
-
-Most methods in CodeceptJS use locators which can be either a string or an object.
-
-If the locator is an object, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, `react`, `class` or `shadow`) and the value being the locator itself. This is called a "strict" locator.
-
-Examples:
-
-* {id: 'foo'} matches `<div id="foo">`
-* {name: 'foo'} matches `<div name="foo">`
-* {css: 'input[type=input][value=foo]'} matches `<input type="input" value="foo">`
-* {xpath: "//input[@type='submit'][contains(@value, 'foo')]"} matches `<input type="submit" value="foobar">`
-* {class: 'foo'} matches `<div class="foo">`
-
-Writing good locators can be tricky.
-The Mozilla team has written an excellent guide titled [Writing reliable locators for Selenium and WebDriver tests](https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/).
-
-If you prefer, you may also pass a string for the locator. This is called a "fuzzy" locator.
-In this case, CodeceptJS uses a variety of heuristics (depending on the exact method called) to determine what element you're referring to. If you are locating a clickable element or an input element, CodeceptJS will use [semantic locators](#semantic-locators).
-
-For example, here's the heuristic used for the `fillField` method:
-
-1. Does the locator look like an ID selector (e.g. "#foo")? If so, try to find an input element matching that ID.
-2. If nothing found, check if locator looks like a CSS selector. If so, run it.
-3. If nothing found, check if locator looks like an XPath expression. If so, run it.
-4. If nothing found, check if there is an input element with a corresponding name.
-5. If nothing found, check if there is a label with specified text for input element.
-6. If nothing found, throw an `ElementNotFound` exception.
-
-> ⚠ Be warned that fuzzy locators can be significantly slower than strict locators. If speed is a concern, it's recommended you stick with explicitly specifying the locator type via object syntax.
-
-It is recommended to avoid using implicit CSS locators in methods like `fillField` or `click`, where semantic locators are allowed.
-Use locator type to speed up search by various locator strategies.
-
-```js
-// will search for "input[type=password]" text before trying to search by CSS
-I.fillField('input[type=password]', '123456');
-// replace with strict locator
-I.fillField({ css: 'input[type=password]' }, '123456');
-```
-
-## CSS and XPath
-
-Both CSS and XPath is supported. Usually CodeceptJS can guess locator's type:
-
-```js
-// select by CSS
-I.seeElement('.user .profile');
-I.seeElement('#user-name');
-
-// select by XPath
-I.seeElement('//table/tr/td[position()=3]');
-```
-
-To specify exact locator type use **strict locators**:
-
-```js
-// it's not clear that 'button' is actual CSS locator
-I.seeElement({ css: 'button' });
-
-// it's not clear that 'descendant::table/tr' is actual XPath locator
-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.
-For example, when clicking CodeceptJS will try to find a link or button by their text
-When typing into a field this field can be located by its name, placeholder.
-
-```js
-I.click('Sign In');
-I.fillField('Username', 'davert');
-```
-
-Various strategies are used to locate semantic elements. However, they may run slower than specifying locator by XPath or CSS.
-
-## Locator Builder
-
-CodeceptJS provides a fluent builder to compose custom locators in JavaScript. Use `locate` function to start.
-
-To locate `a` element inside `label` with text: 'Hello' use:
-
-```js
-locate('a')
-  .withAttr({ href: '#' })
-  .inside(locate('label').withText('Hello'));
-```
-
-which will produce following XPath:
-
-```
-.//a[@href = '#'][ancestor::label[contains(., 'Hello')]]
-```
-
-Locator builder accepts both XPath and CSS as parameters but converts them to XPath as more feature-rich format.
-Sometimes provided locators can get very long so it's recommended to simplify the output by providing a brief description for generated XPath:
-
-```js
-locate('//table')
-  .find('a')
-  .withText('Edit')
-  .as('edit button')
-// will be printed as 'edit button'
-```
-
-`locate` has following methods:
-
-#### find
-
-Finds an element inside a located.
-
-```js
-// find td inside a table
-locate('table').find('td');
-```
-Switches current element to found one.
-Can accept another `locate` call or strict locator.
-
-#### withAttr
-
-Find an element with provided attributes
-
-```js
-// find input with placeholder 'Type in name'
-locate('input').withAttr({ placeholder: 'Type in name' });
-```
-
-#### withChild
-
-Finds an element which contains a child element provided:
-
-```js
-// finds form with <select> inside it
-locate('form').withChild('select');
-```
-
-#### withDescendant
-
-Finds an element which contains a descendant element provided:
-
-```js
-// finds form with <select> which is the descendant it
-locate('form').withDescendant('select');
-```
-
-#### withText
-
-Finds element containing a text
-
-```js
-locate('span').withText('Warning');
-```
-
-#### first
-
-Get first element:
-
-```js
-locate('#table td').first();
-```
-
-#### last
-
-Get last element:
-
-```js
-locate('#table td').last();
-```
-
-#### at
-
-Get element at position:
-
-```js
-// first element
-locate('#table td').at(1);
-// second element
-locate('#table td').at(2);
-// second element from end
-locate('#table td').at(-2);
-```
-
-#### inside
-
-Finds an element which contains an provided ancestor:
-
-```js
-// finds `select` element inside #user_profile
-locate('select').inside('form#user_profile');
-```
-
-#### before
-
-Finds element located before the provided one
-
-```js
-// finds `button` before .btn-cancel
-locate('button').before('.btn-cancel');
-```
-
-#### after
-
-Finds element located after the provided one
-
-```js
-// finds `button` after .btn-cancel
-locate('button').after('.btn-cancel');
-```
-
-## ID Locators
-
-ID locators are best to select the exact semantic element in web and mobile testing:
-
-* `#user` or `{ id: 'user' }` finds element with id="user"
-* `~user` finds element with accessibility id "user" (in Mobile testing) or with `aria-label=user`.
-
-## Custom Locators
-
-CodeceptJS allows to create custom locator strategies and use them in tests. This way you can define your own handling of elements using specially prepared attributes of elements.
-
-What if you use special test attributes for locators such as `data-qa`, `data-test`, `test-id`, etc.
-We created [customLocator plugin](/plugins#customlocator) to declare rules for locating element.
-
-Instead of writing a full CSS locator like `[data-qa-id=user_name]` simplify it to `$user_name`.
-
-```js
-// replace this:
-I.click({ css: '[data-test-id=register_button]'});
-// with this:
-I.click('$register_button');
-```
-
-This plugin requires two options: locator prefix and actual attribute to match.
-
-> ℹ See [customLocator Plugin](/plugins#customlocator) reference to learn how to set it up.
-
-If you need more control over custom locators see how declare them manually without using a customLocator plugin.
-
-#### Custom Strict Locators
-
-If use locators of `data-element` attribute you can implement a strategy, which will allow you to use `{ data: 'my-element' }` as a valid locator.
-
-Custom locators should be implemented in a plugin or a bootstrap script using internal CodeceptJS API:
-
-```js
-// inside a plugin or a bootstrap script:
-codeceptjs.locator.addFilter((providedLocator, locatorObj) => {
-  // providedLocator - a locator in a format it was provided
-  // locatorObj - a standrard locator object.
-    if (providedLocator.data) {
-      locatorObj.type = 'css';
-      locatorObj.value = `[data-element=${providedLocator.data}]`
-    }
-});
-```
-
-That's all. New locator type is ready to use:
-
-```js
-I.click({ data: 'user-login' });
-```
-
-#### Custom String Locators
-
-What if we want to locators prefixed with `=` to match elements with exact text value.
-We can do that too:
-
-```js
-// inside a plugin or a bootstrap script:
-codeceptjs.locator.addFilter((providedLocator, locatorObj) => {
-    if (typeof providedLocator === 'string') {
-      // this is a string
-      if (providedLocator[0] === '=') {
-        locatorObj.value = `.//*[text()="${providedLocator.substring(1)}"]`;
-        locatorObj.type = 'xpath';
-      }
-    }
-});
-```
-New locator strategy is ready to use:
-
-
-```js
-I.click('=Login');
-```
-
-#### Custom Strategy Locators
-
-CodeceptJS provides the option to specify custom locators that uses Custom Locator Strategies defined in the WebDriver configuration. It uses the WebDriverIO's [custom$](https://webdriver.io/docs/api/browser/custom$.html) locators internally to locate the elements on page.
-To use the defined Custom Locator Strategy add your custom strategy to your configuration.
-
-```js
-// in codecept.conf.js
-
-const myStrat = (selector) => {
-  return document.querySelectorAll(selector)
-}
-
-// under WebDriver Helpers Configuration
-WebDriver: {
-  ...
-  customLocatorStrategies: {
-    custom: myStrat
-  }
-}
-```
-
-```js
-I.click({custom: 'my-shadow-element-unique-css'})
-```
-
-
-> For more details on locator object see [Locator](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/locator.js) class implementation.

package/docs/mobile-react-native-locators.md

@@ -1,67 +0,0 @@
-## Automating React Native apps
-
-### Problem
-
-> ⚠️ **NOTE**: This problem is not actual starting from `react-native@0.65.x` [CHANGELOG](https://github.com/react-native-community/releases/blob/master/CHANGELOG.md#android-specific-9), [#381fb3](https://github.com/facebook/react-native/commit/381fb395ad9d2d48717a5d082aaedbecdd804554)
-
-Let's say we have a React Native app with component defined like this
-```html
-<Button testID='someButton'>My button</Button>
-```
-
-If you will try to execute a simple test like
-```js
-I.tap('~someButton')
-```
-it will work correctly on iOS (with XUITest driver), but on Android's UIAutomator2 it will give you an error
-```
-Touch actions like "tap" need at least some kind of position information like "element", "x" or "y" options, you've none given.
-```
-
-This happens because of the way React Native implements `testID` for Android, it puts provided value into the [View tag](https://developer.android.com/reference/android/view/View#tags),
-as could be found in the [source code](https://github.com/facebook/react-native/blob/19a88d7f4addcd9f95fd4908d50db37b3604b5b1/ReactAndroid/src/main/java/com/facebook/react/uimanager/BaseViewManager.java#L114).
-But UIAutomator doesn't have any means to work with view tags.
-
-### Solutions
-As many resources suggest (like [here](https://github.com/appium/appium/issues/6025#issuecomment-406141946) or [here](https://github.com/facebook/react-native/issues/7135)),
-you could use `testID` for iOS and `accesibilityLabel` for Android, but `accessibilityLabel` is a user-facing text that's intended for ... accesibility,
-not for UI tests, and you will need to switch it off for production builds.
-
-Another way to solve this issue is to use Espresso driver for Android.
-At first you need to enable Espresso driver for your Android configuration.
-You could do it just by changing `automationName` in the `helpers` section of the config file:
-```js
-{
-  //...
-  helpers: {
-    Appium: {
-      app: '/path/to/apk.apk',
-      platform: 'Android',
-      desiredCapabilities: {
-        automationName: 'Espresso',
-        platformVersion: '9',
-        deviceName: 'Android Emulator'
-      }
-    }
-  }
-  //...
-}
-```
-Then you could locate components using XPath expression:
-```js
-I.tap({android: '//*[@view-tag="someButton"]', ios: '~someButton'})
-```
-This way test would work for both platforms without any changes in code.
-To simplify things further you could write a helper function:
-```js
-function tid(id) {
-  return {
-    android: `//*[@view-tag="${id}"]`,
-    ios: '~' + id
-  }
-}
-```
-Now test will look more concise
-```js
-I.tap(tid('someButton'));
-```