codeceptjs 3.5.15 → 3.6.0-beta.1.ai-healers

package/docs/internal-api.md

@@ -0,0 +1,266 @@
+---
+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
+* `event.workers.result` - test results 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

@@ -0,0 +1,339 @@
+---
+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
+
+Find an element containing a text
+
+```js
+locate('span').withText('Warning');
+```
+
+#### withTextEquals
+
+Find an element with exact text
+
+```js
+locate('button').withTextEquals('Add');
+```
+
+#### 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

@@ -0,0 +1,67 @@
+## 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'));
+```