codeceptjs 3.4.1 → 3.5.1-2.beta.7

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.

package/docs/parallel.md

@@ -1,232 +0,0 @@
----
-permalink: /parallel
-title: Parallel Execution
----
-
-# Parallel Execution
-
-CodeceptJS has two engines for running tests in parallel:
-
-* `run-workers` - which spawns [NodeJS Worker](https://nodejs.org/api/worker_threads.html) in a thread. Tests are split by scenarios, scenarios are mixed between groups, each worker runs tests from its own group.
-* `run-multiple` - which spawns a subprocess with CodeceptJS. Tests are split by files and configured in `codecept.conf.js`.
-
-Workers are faster and simpler to start, while `run-multiple` requires additional configuration and can be used to run tests in different browsers at once.
-
-## Parallel Execution by Workers
-
-It is easy to run tests in parallel if you have a lots of tests and free CPU cores. Just execute your tests using `run-workers` command specifying the number of workers to spawn:
-
-```
-npx codeceptjs run-workers 2
-```
-
-> ℹ Workers require NodeJS >= 11.7
-
-This command is similar to `run`, however, steps output can't be shown in workers mode, as it is impossible to synchronize steps output from different processes.
-
-Each worker spins an instance of CodeceptJS, executes a group of tests, and sends back report to the main process.
-
-By default the tests are assigned one by one to the available workers this may lead to multiple execution of `BeforeSuite()`. Use the option `--suites` to assigne the suites one by one to the workers.
-
-```sh
-npx codeceptjs run-workers --suites 2
-```
-
-## Custom Parallel Execution
-
-To get a full control of parallelization create a custom execution script to match your needs.
-This way you can configure which tests are matched, how the groups are formed, and with which configuration each worker is executed.
-
-Start with creating file `bin/parallel.js`.
-
-On MacOS/Linux run following commands:
-
-```
-mkdir bin
-touch bin/parallel.js
-chmod +x bin/parallel.js
-```
-
-> Filename or directory can be customized. You are creating your own custom runner so take this paragraph as an example.
-
-Create a placeholder in file:
-
-```js
-#!/usr/bin/env node
-const { Workers, event } = require('codeceptjs');
-// here will go magic
-```
-
-Now let's see how to update this file for different parallelization modes:
-
-### Example: Running tests in 2 browsers in 4 threads
-
-```js
-const workerConfig = {
-  testConfig: './test/data/sandbox/codecept.customworker.js',
-};
-
-// don't initialize workers in constructor
-const workers = new Workers(null, workerConfig);
-// split tests by suites in 2 groups
-const testGroups = workers.createGroupsOfSuites(2);
-
-const browsers = ['firefox', 'chrome'];
-
-const configs = browsers.map(browser => {
-  return {
-    helpers: {
-      WebDriver: { browser }
-    }
-  };
-});
-
-for (const config of configs) {
-  for (group of testGroups) {
-    const worker = workers.spawn();
-    worker.addTests(group);
-    worker.addConfig(config);
-  }
-}
-
-// Listen events for failed test
-workers.on(event.test.failed, (failedTest) => {
-  console.log('Failed : ', failedTest.title);
-});
-
-// Listen events for passed test
-workers.on(event.test.passed, (successTest) => {
-  console.log('Passed : ', successTest.title);
-});
-
-// test run status will also be available in event
-workers.on(event.all.result, () => {
-  // Use printResults() to display result with standard style
-  workers.printResults();
-});
-
-// run workers as async function
-runWorkers();
-
-async function runWorkers() {
-  try {
-    // run bootstrapAll
-    await workers.bootstrapAll();
-    // run tests
-    await workers.run();
-  } finally {
-    // run teardown All
-    await workers.teardownAll();
-  }
-}
-```
-
-Inside `event.all.result` you can obtain test results from all workers, so you can customize the report:
-
-```js
-workers.on(event.all.result, (status, completedTests, workerStats) => {
-  // print output
-  console.log('Test status : ', status ? 'Passes' : 'Failed ');
-
-  // print stats
-  console.log(`Total tests : ${workerStats.tests}`);
-  console.log(`Passed tests : ${workerStats.passes}`);
-  console.log(`Failed test tests : ${workerStats.failures}`);
-
-  // If you don't want to listen for failed and passed test separately, use completedTests object
-  for (const test of Object.values(completedTests)) {
-    console.log(`Test status: ${test.err===null}, `, `Test : ${test.title}`);
-  }
-}
-```
-
-### Example: Running Tests Split By A Custom Function
-
-If you want your tests to split according to your need this method is suited for you. For example: If you have 4 long running test files and 4 normal test files there chance all 4 tests end up in same worker thread. For these cases custom function will be helpful.
-
-```js
-
-/*
- Define a function to split your tests.
-
- function should return an array with this format [[file1, file2], [file3], ...]
-
- where file1 and file2 will run in a worker thread and file3 will run in a worker thread
-*/
-const splitTests = () => {
-  const files = [
-    ['./test/data/sandbox/guthub_test.js', './test/data/sandbox/devto_test.js'],
-    ['./test/data/sandbox/longrunnig_test.js']
-  ];
-
-  return files;
-}
-
-const workerConfig = {
-  testConfig: './test/data/sandbox/codecept.customworker.js',
-  by: splitTests
-};
-
-// don't initialize workers in constructor
-const customWorkers = new Workers(null,  workerConfig);
-
-customWorkers.run();
-
-// You can use event listeners similar to above example.
-customWorkers.on(event.all.result, () => {
-  workers.printResults();
-});
-```
-
-### Emitting messages to the parent worker
-
-Child workers can send non test events to the main process. This is useful if you want to pass along information not related to the tests event cycles itself such as `event.test.success`.
-
-```js
-// inside main process
-// listen for any non test related events
-workers.on('message', (data) => {
-  console.log(data)
-});
-
-workers.on(event.all.result, (status, completedTests, workerStats) => {
-  // logic
-});
-```
-
-## Sharing Data Between Workers
-
-NodeJS Workers can communicate between each other via messaging system. It may happen that you want to pass some data from one of the workers to other. For instance, you may want to share user credentials accross all tests. Data will be appended to a container.
-
-However, you can't access uninitialized data from a container, so to start, you need to initialize data first. Inside `bootstrap` function of the config we execute the `share` to initialize value:
-
-
-```js
-// inside codecept.conf.js
-exports.config = {
-  bootstrap() {
-    // append empty userData to container
-    share({ userData: false });
-  }
-}
-```
-
-Now each worker has `userData` inside a container. However, it is empty.
-When you obtain real data in one of the tests you can now `share` this data accross tests. Use `inject` function to access data inside a container:
-
-```js
-// get current value of userData
-let { userData } = inject();
-// if userData is still empty - update it
-if (!userData) {
-  userData = { name: 'user', password: '123456' };
-  // now new userData will be shared accross all workers
-  share({userData : userData});
-}
-```
-
-If you want to share data only within same worker, and not across all workers, you need to add option `local: true` every time you run `share` 
-
-```js
-share({ userData: false }, {local: true });
-```