codeceptjs 3.5.0 → 3.5.1-2.beta.7

package/docs/custom-helpers.md

@@ -1,306 +0,0 @@
----
-permalink: /helpers
-title: Custom Helpers
----
-
-# Extending CodeceptJS With Custom Helpers
-
-Helper is the core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them. When `I` object is used in tests it delegates execution of its functions to currently enabled helper classes. 
-
-Use Helpers to introduce low-level API to your tests without polluting test scenarios. Helpers can also be used to share functionality across different project and installed as npm packages.
-
-## Development
-
-Helpers can be created by running a generator command:
-
-```bash
-npx codeceptjs gh
-```
-
-> or `npx codeceptjs generate:helper`
-
-This command generates a basic helper, append it to `helpers` section of config file:
-
-```js
-helpers: {
-  WebDriver: {  },
-  MyHelper: {
-    require: './path/to/module'
-  }
-}
-```
-
-Helpers are classes inherited from [corresponding abstract class](https://github.com/codeceptjs/helper).
-Created helper file should look like this:
-
-```js
-const Helper = require('@codeceptjs/helper');
-
-class MyHelper extends Helper {
-
-  // before/after hooks
-  _before() {
-    // remove if not used
-  }
-
-  _after() {
-    // remove if not used
-  }
-
-  // add custom methods here
-  // If you need to access other helpers
-  // use: this.helpers['helperName']
-
-}
-
-module.exports = MyHelper;
-```
-
-When the helper is enabled in config all methods of a helper class are available in `I` object.
-For instance, if we add a new method to helper class:
-
-```js
-const Helper = require('@codeceptjs/helper');
-
-class MyHelper extends Helper {
-
-  doAwesomeThings() {
-    console.log('Hello from MyHelpr');
-  }
-
-}
-```
-
-We can call a new method from within `I`:
-
-```js
-I.doAwesomeThings();
-```
-
-> Methods starting with `_` are considered special and won't available in `I` object.
-
-
-Please note, `I` object can't be used helper class. As `I` object delegates its calls to helper classes, you can't make a circular dependency on it. Instead of calling `I` inside a helper, you can get access to other helpers by using `helpers` property of a helper. This allows you to access any other enabled helper by its name. 
-
-For instance, to perform a click with Playwright helper, do it like this:
-
-```js
-doAwesomeThingsWithPlaywright() {
-  const { Playwright } = this.helpers;
-  Playwright.click('Awesome');    
-}
-```
-
-
-After a custom helper is finished you can update CodeceptJS Type Definitions by running:
-
-```sh
-npx codeceptjs def .
-```
-
-This way, if your tests are written with TypeScript, your IDE will be able to leverage features like autocomplete and so on.
-
-## Accessing Elements
-
-WebDriver, Puppeteer, Playwright, and Protractor drivers provide API for web elements.
-However, CodeceptJS do not expose them to tests by design, keeping test to be action focused.
-If you need to get access to web elements, it is recommended to implement operations for web elements in a custom helper.
-
-To get access for elements, connect to a corresponding helper and use `_locate` function to match web elements by CSS or XPath, like you usually do:
-
-### Accessing Elements in WebDriver
-
-```js
-// inside a custom helper
-async clickOnEveryElement(locator) {
-  const { WebDriver } = this.helpers;
-  const els = await WebDriver._locate(locator);
-
-  for (let el of els) {
-    await el.click();
-  }
-}
-```
-
-In this case an an instance of webdriverio element is used.
-To get a [complete API of an element](https://webdriver.io/docs/api/) refer to webdriverio docs.
-
-### Accessing Elements in Playwright & Puppeteer
-
-Similar method can be implemented for Playwright & Puppeteer:
-
-```js
-// inside a custom helper
-async clickOnEveryElement(locator) {
-  const { Playwright } = this.helpers;
-  const els = await Playwright._locate(locator);
-
-  for (let el of els) {
-    await el.click();
-  }
-}
-```
-
-In this case `el` will be an instance of [ElementHandle](https://playwright.dev/#version=master&path=docs%2Fapi.md&q=class-elementhandle) which is similar for Playwright & [Puppeteer](https://pptr.dev/#?product=Puppeteer&version=master&show=api-class-elementhandle).
-
-> ℹ There are more `_locate*` methods in each helper. Take a look on documentation of a helper you use to see which exact method it exposes.
-
-## Configuration
-
-Helpers should be enabled inside `codecept.json` or `codecept.conf.js` files. Command `generate helper`
-does that for you, however you can enable them manually by placing helper to `helpers` section inside config file.
-You can also pass additional config options to your helper from a config - **(please note, this example contains comments, while JSON format doesn't support them)**:
-
-```js
-helpers: {
-  // here goes standard helpers:
-  // WebDriver, Protractor, Nightmare, etc...
-  // and their configuration
-  MyHelper: {
-    require: "./my_helper.js", // path to module
-    defaultHost: "http://mysite.com" // custom config param
-  }
-
-}
-```
-
-Config values will be stored inside helper in `this.config`. To get `defaultHost` value you can use
-
-```js
-this.config.defaultHost
-```
-
-in any place of your helper. You can also redefine config options inside a constructor:
-
-```js
-constructor(config) {
-  config.defaultHost += '/api';
-  console.log(config.defaultHost); // http://mysite.com/api
-  super(config);
-}
-```
-
-## Hooks
-
-Helpers may contain several hooks you can use to handle events of a test.
-Implement corresponding methods to them.
-
-* `_init` - before all tests
-* `_finishTest` - after all tests
-* `_before` - before a test
-* `_after` - after a test
-* `_beforeStep` - before each step
-* `_afterStep` - after each step
-* `_beforeSuite` - before each suite
-* `_afterSuite` - after each suite
-* `_passed` - after a test passed
-* `_failed` - after a test failed
-
-Each implemented method should return a value as they will be added to global promise chain as well.
-
-## Conditional Retries
-
-It is possible to execute global conditional retries to handle unforseen errors.
-Lost connections and network issues are good candidates to be retried whenever they appear.
-
-This can be done inside a helper using the global [promise recorder](/hooks/#api):
-
-Example: Retrying rendering errors in Puppeteer.
-
-```js
-_before() {
-  const recorder = require('codeceptjs').recorder;
-  recorder.retry({
-    retries: 2,
-    when: err => err.message.indexOf('Cannot find context with specified id') > -1,
-  });
-}
-```
-
-`recorder.retry` acts similarly to `I.retry()` and accepts the same parameters. It expects the `when` parameter to be set so it would handle only specific errors and not to retry for every failed step.
-
-Retry rules are available in array `recorder.retries`. The last retry rule can be disabled by running `recorder.retries.pop()`;
-
-## Using Typescript
-
-With Typescript, just simply replacing `module.exports` with `export` for autocompletion.
-
-
-## Helper Examples
-
-### Playwright Example
-
-In this example we take the power of Playwright to change geolocation in our tests:
-
-```js
-const Helper = require('@codeceptjs/helper');
-
-class MyHelper extends Helper {
-
-  async setGeoLocation(longitude, latitude) {
-    const { browserContext } = this.helpers.Playwright;
-    await browserContext.setGeolocation({ longitude, latitude });
-    await Playwright.refreshPage();
-  }
-}
-```
-
-### WebDriver Example
-
-Next example demonstrates how to use WebDriver library to create your own test action. Method `seeAuthentication` will use `browser` instance of WebDriver to get access to cookies. Standard NodeJS assertion library will be used (you can use any).
-
-```js
-const Helper = require('@codeceptjs/helper');
-
-// use any assertion library you like
-const assert = require('assert');
-
-class MyHelper extends Helper {
-  /**
-   * checks that authentication cookie is set
-   */
-  async seeAuthentication() {
-    // access current browser of WebDriver helper
-    const { WebDriver } = this.helpers
-    const { browser } = WebDriver;
-
-    // get all cookies according to https://webdriver.io/api/protocol/cookie.html
-    // any helper method should return a value in order to be added to promise chain
-    const res = await browser.cookie();
-    // get values
-    let cookies = res.value;
-    for (let k in cookies) {
-      // check for a cookie
-      if (cookies[k].name != 'logged_in') continue;
-      assert.equal(cookies[k].value, 'yes');
-      return;
-    }
-    assert.fail(cookies, 'logged_in', "Auth cookie not set");
-  }
-}
-
-module.exports = MyHelper;
-```
-
-### Puppeteer Example
-
-Puppeteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Accessing `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
-
-Let's see how we can use [emulate](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulateoptions) function to emulate iPhone browser in a test.
-
-```js
-const Helper = require('@codeceptjs/helper');
-const puppeteer = require('puppeteer');
-const iPhone = puppeteer.devices['iPhone 6'];
-
-class MyHelper extends Helper {
-
-  async emulateIPhone() {
-    const { page } = this.helpers.Puppeteer;
-    await page.emulate(iPhone);
-  }
-
-}
-
-module.exports = MyHelper;
-```

package/docs/data.md

@@ -1,375 +0,0 @@
----
-permalink: /data
-title: Data Management
----
-
-# Data Management
-
-> This chapter describes data management for external sources. If you are looking for using Data Sets in tests, see [Data Driven Tests](https://codecept.io/advanced/#data-drivern-tests) section*
-
-Managing data for tests is always a tricky issue. How isolate data between tests, how to prepare data for different tests, etc.
-There are different approaches to solve it:
-
-1.  reset database completely between tests
-2.  create unique non-intersecting data sets per each test
-3.  create and delete data for a test
-
-The most efficient way would be to allow test to control its data, i.e. the 3rd option.
-However, accessing database directly is not a good idea as database vendor, schema and data are used by application internally and are out of scope of acceptance test.
-
-Today all modern web applications have REST or GraphQL API . So it is a good idea to use it to create data for a test and delete it after.
-API is supposed to be a stable interface and it can be used by acceptance tests. CodeceptJS provides 4 helpers for Data Management via REST and GraphQL API.
-
-## REST
-
-[REST helper](https://codecept.io/helpers/REST/) allows sending raw HTTP requests to application.
-This is a tool to make shortcuts and create your data pragmatically via API. However, it doesn't provide tools for testing APIs, so it should be paired with WebDriver, Nightmare or Protractor helpers for browser testing.
-
-Enable REST helper in the config. It is recommended to set `endpoint`, a base URL for all API requests. If you need some authorization you can optionally set default headers too.
-
-See the sample config:
-
-```js
-helpers: {
-  REST: {
-    endpoint: "http://localhost/api/v1/",
-    defaultHeaders: {
-      'Auth': '11111',
-      'Content-Type': 'application/json',
-      'Accept': 'application/json',
-    },
-  },
-  WebDriver : {
-    url: 'http://localhost',
-    browser: 'chrome'
-  }
-}
-```
-
-REST helper provides basic methods to send requests to application:
-
-```js
-I.sendGetRequest()
-I.sendPostRequest()
-I.sendPutRequest()
-I.sendPatchRequest()
-I.sendDeleteRequest()
-```
-
-As well as a method for setting headers: `haveRequestHeaders`.
-
-Here is a usage example:
-
-```js
-let postId = null;
-
-Scenario('check post page', async ({ I })  => {
-  // valid access token
-  I.haveRequestHeaders({auth: '1111111'});
-  // get the first user
-  let user = await I.sendGetRequest('/api/users/1');
-  // create a post and save its Id
-  postId = await I.sendPostRequest('/api/posts', { author: user.id, body: 'some text' });
-  // open browser page of new post
-  I.amOnPage('/posts/2.html');
-  I.see('some text', 'p.body');
-});
-
-// cleanup created data
-After(({ I }) => {
-  I.sendDeleteRequest('/api/posts/'+postId);
-});
-```
-
-This can also be used to emulate Ajax requests:
-
-```js
-I.sendPostRequest('/update-status', {}, { http_x_requested_with: 'xmlhttprequest' });
-```
-
-> See complete reference on [REST](https://codecept.io/helpers/REST) helper
-
-## GraphQL
-
-[GraphQL helper](https://codecept.io/helpers/GraphQL/) allows sending GraphQL queries and mutations to application, over Http.
-This is a tool to make shortcuts and create your data pragmatically via GraphQL endpoint. However, it doesn't provide tools for testing the endpoint, so it should be paired with WebDriver, Nightmare or Protractor helpers for browser testing.
-
-Enable GraphQL helper in the config. It is recommended to set `endpoint`, the URL to which the requests go to. If you need some authorization you can optionally set default headers too.
-
-See the sample config:
-
-```js
-helpers: {
-  GraphQL: {
-    endpoint: "http://localhost/graphql/",
-    defaultHeaders: {
-      'Auth': '11111',
-      'Content-Type': 'application/json',
-      'Accept': 'application/json',
-    },
-  },
-  WebDriver : {
-    url: 'http://localhost',
-    browser: 'chrome'
-  }
-}
-```
-
-GraphQL helper provides two basic methods to queries and mutations to application:
-
-```js
-I.sendQuery()
-I.sendMutation()
-```
-
-As well as a method for setting headers: `haveRequestHeaders`.
-
-Here is a usage example:
-
-```js
-let postData = null;
-
-Scenario('check post page', async ({ I })  => {
-  // valid access token
-  I.haveRequestHeaders({auth: '1111111'});
-  // get the first user
-  let response = await I.sendQuery('{ user(id:1) { id }}');
-  let user = response.data;
-  // create a post and save its Id
-  response = await I.sendMutation(
-    'mutation createPost($input: PostInput!) { createPost(input: $input) { id }}',
-    {
-      input : {
-        author: user.data.id,
-        body: 'some text',
-      }
-    },
-  );
-  postData = response.data.data['createPost'];
-  // open browser page of new post
-  I.amOnPage(`/posts/${postData.slug}.html`);
-  I.see(postData.body, 'p.body');
-});
-
-// cleanup created data
-After(({ I }) => {
-  I.sendMutation(
-    'mutation deletePost($id: ID!) { deletePost(id: $id) }',
-    { id: postData.id},
-  );
-});
-```
-
-> See complete reference on [GraphQL](https://codecept.io/helpers/GraphQL) helper
-
-## Data Generation with Factories
-
-This concept is extended by:
-- [ApiDataFactory](https://codecept.io/helpers/ApiDataFactory/) helper, and,
-- [GraphQLDataFactory](https://codecept.io/helpers/GraphQLDataFactory/) helper.
-
-These helpers build data according to defined rules and use REST API or GraphQL mutations to store them and automatically clean them up after a test.
-
-Just define how many items of any kind you need and the data factory helper will create them for you.
-
-To make this work some preparations are required.
-
-At first, you need data generation libraries which are [Rosie](https://github.com/rosiejs/rosie) and [Faker](https://www.npmjs.com/package/faker). Faker can generate random names, emails, texts, and Rosie uses them
-to generate objects using factories.
-
-Install rosie and faker to create a first factory:
-
-```js
-npm i rosie faker --save-dev
-```
-
-Then create a module which will export a factory for an entity.
-And add that module as a part of the configuration for the helper.
-
-Please look at the respective Factory sections for examples for factory modules and configuration.
-
-### API Data Factory
-
-This helper uses REST API to store the built data and automatically clean them up after a test,
-The way for setting data for a test is as simple as writing:
-
-```js
-// inside async function
-let post = await I.have('post');
-I.haveMultiple('comment', 5, { postId: post.id});
-```
-
-After completing the preparations under 'Data Generation with Factories', create a factory module which will export a factory.
-
-See the example providing a factory for User generation:
-
-```js
-// factories/post.js
-var Factory = require('rosie').Factory;
-var faker = require('@faker-js/faker');
-
-module.exports = new Factory()
-  .attr('name', () => faker.name.findName())
-  .attr('email', () => faker.internet.email());
-```
-
-Next is to configure helper to match factories with API:
-
-```js
- ApiDataFactory: {
-   endpoint: "http://user.com/api",
-   headers: {
-     'Content-Type': 'application/json',
-     'Accept': 'application/json',
-   },
-   factories: {
-     user: {
-        uri: "/users",
-        factory: "./factories/user"
-     }
-   }
- }
-```
-
-Then, calling `I.have('user')` inside a test will create a new user for you.
-This is done by sending POST request to `/api/users` URL. Response is returned and can be used in tests.
-
-At the end of a test ApiDataFactory will clean up created record for you. This is done by collecting
-ids from crated records and running `DELETE /api/users/{id}` requests at the end of a test.
-This rules can be customized in helper configuration.
-
-> See complete reference on [ApiDataFactory](https://codecept.io/helpers/ApiDataFactory) helper
-
-### GraphQL Data Factory
-
-The helper uses GraphQL mutations to store the built data and automatically clean them up after a test.
-This way for setting data for a test is as simple as writing:
-
-```js
-// inside async function
-let post = await I.mutateData('createPost');
-I.mutateMultiple('createComment', 5, { postId: post.id});
-```
-
-
-
-After completing the preparations under 'Data Generation with Factories', create a factory module which will export a factory.
-
-The object built by the factory is sent as the variables object along with the mutation. So make sure it matches the argument type as detailed in the GraphQL schema. You may want to pass a constructor to the factory to achieve that.
-
-See the example providing a factory for User generation:
-
-```js
-// factories/post.js
-var Factory = require('rosie').Factory;
-var faker = require('@faker-js/faker');
-
-module.exports = new Factory((buildObj) => {
-  return {
-    input: { ...buildObj },
-  }
-})
-  .attr('name', () => faker.name.findName())
-  .attr('email', () => faker.internet.email());
-```
-
-Next is to configure helper to match factories with API:
-
-```js
-GraphQLDataFactory: {
-  endpoint: "http://user.com/graphql",
-  cleanup: true,
-  headers: {
-    'Content-Type': 'application/json',
-    'Accept': 'application/json',
-  },
-  factories: {
-    createUser: {
-      query: 'mutation createUser($input: UserInput!) { createUser(input: $input) { id name }}',
-      factory: './factories/users',
-      revert: (data) => ({
-        query: 'mutation deleteUser($id: ID!) { deleteUser(id: $id) }',
-        variables: { id : data.id},
-      }),
-    },
-  }
-```
-
-Then, calling `I.mutateData('createUser')` inside a test will create a new user for you.
-This is done by sending a GraphQL mutation request over Http to `/graphql` endpoint. Response is returned and can be used in tests.
-
-At the end of a test GraphQLDataFactory will clean up created record for you. This is done by collecting
-data from crated records, creating deletion mutation objects by passing the data to the `revert` function provided, and sending deletion mutation objects as requests at the end of a test.
-This behavior is according the `revert` function be customized in helper configuration.
-The revert function returns an object, that contains the query for deletion, and the variables object to go along with it.
-
-> See complete reference on [GraphQLDataFactory](https://codecept.io/helpers/GraphQLDataFactory) helper
-
-## Requests Using Browser Session
-
-All the REST, GraphQL, GraphQLDataFactory, and ApiDataFactory helpers allow override requests before sending.
-This feature can be used to fetch current browser cookies and set them to REST API or GraphQL client.
-By doing this we can make requests within the current browser session without a need of additional authentication.
-
-> Sharing browser session with ApiDataFactory or GraphQLDataFactory can be especially useful when you test Single Page Applications
-
-Since CodeceptJS 2.3.3 there is a simple way to enable shared session for browser and data helpers.
-Install [`@codeceptjs/configure`](https://github.com/codeceptjs/configure) package:
-
-```
-npm i @codeceptjs/configure --save
-```
-
-Import `setSharedCookies` function and call it inside a config:
-
-```js
-// in codecept.conf.js
-const { setSharedCookies } = require('@codeceptjs/configure');
-
-// share cookies between browser helpers and REST/GraphQL
-setSharedCookies();
-
-exports.config = {}
-```
-
-Without `setSharedCookies` you will need to update the config manually, so a data helper could receive cookies from a browser to make a request. If you would like to configure this process manually, here is an example of doing so:
-
-```js
-
-let cookies; // share cookies
-
-exports.config = {
-helpers: {
-  ApiDataFactory: {
-    endpoint: 'http://local.app/api',
-    cleanup: true,
-    headers: {
-      'Content-Type': 'application/json',
-      'Accept': 'application/json',
-    },
-    factories: {
-      user: {
-          uri: "/users",
-          factory: "./factories/user",
-      }
-    },
-    onRequest: async (request) => {
-      // get a cookie if it's not obtained yet
-      if (cookies) cookies = await codeceptjs.container.helpers('WebDriver').grabCookie();
-      // add cookies to request for a current request
-      request.headers = { Cookie: cookies.map(c => `${c.name}=${c.value}`).join('; ') };
-    },
-  }
-  WebDriver: {
-    url: 'https://local.app/',
-    browser: 'chrome',
-  }
-}
-```
-
-In this case we are accessing WebDriver helper. However, you can replace WebDriver with any helper you use.
-
-The same can be done with GraphQLDataFactory.
-
-The order of helpers is important! ApiDataFactory will clean up created users after a test,
-so it needs browser to be still opened to obtain its cookies.