codeceptjs 3.4.1 → 3.5.1-2.beta.7

package/docs/advanced.md

@@ -1,351 +0,0 @@
----
-permalink: /advanced
-title: Advanced Usage
----
-
-# Advanced Usage
-
-## Data Driven Tests
-
-Execute the same scenario on a different data set.
-
-Let's say you want to test login for different user accounts.
-In this case, you need to create a datatable and fill it in with credentials.
-Then use `Data().Scenario` to include this data and generate multiple scenarios:
-
-```js
-// Define data table inside a test or load from another module
-let accounts = new DataTable(['login', 'password']); //
-accounts.add(['davert', '123456']); // adding records to a table
-accounts.add(['admin', '123456']);
-
-// You can skip some data. But add them to report as skipped (just like with usual scenarios):
-accounts.xadd(['admin', '23456'])
-
-// Pass dataTable to Data()
-// Use special param `current` to get current data set
-Data(accounts).Scenario('Test Login', ({ I, current }) => {
-  I.fillField('Username', current.login); // current is reserved!
-  I.fillField('Password', current.password);
-  I.click('Sign In');
-  I.see('Welcome '+ current.login);
-});
-
-
-// Also you can set only for Data tests. It will launch executes only the current test but with all data options
-Data(accounts).only.Scenario('Test Login', ({ I, current }) => {
-  I.fillField('Username', current.login); // current is reserved!
-  I.fillField('Password', current.password);
-  I.click('Sign In');
-  I.see('Welcome '+ current.login);
-});
-```
-
-*Important: you can't use name `current` for pageObjects or helpers in data scenarios*
-
-This will produce 2 tests with different data sets.
-Current data set is appended to a test name in output:
-
-```sh
-✓ Test Login | {"login":"davert","password":"123456"}
-✓ Test Login | {"login":"admin","password":"123456"}
-S Test Login | {"login":"admin","password":"23456"}
-```
-
-```js
-// You can filter your data table
-Data(accounts.filter(account => account.login == 'admin')
-.Scenario('Test Login', ({ I, current }) => {
-  I.fillField('Username', current.login);
-  I.fillField('Password', current.password);
-  I.click('Sign In');
-  I.see('Welcome '+ current.login);
-});
-```
-
-This will limit data sets accoring passed function:
-
-```sh
-✓ Test Login | {"login":"admin","password":"123456"}
-S Test Login | {"login":"admin","password":"23456"}
-```
-
-Data sets can also be defined with array, generator, or a function.
-
-```js
-Data(function*() {
-  yield { user: 'davert'};
-  yield { user: 'andrey'};
-}).Scenario() // ...
-```
-
-*HINT: If you don't use DataTable. add `toString()` method to each object added to data set, so the data could be pretty printed in a test name*
-
-## Tags
-
-Append `@tag` to your test name, so
-
-```js
-Scenario('update user profile @slow')
-```
-
-Alternativly, use `tag` method of Scenario to set additional tags:
-
-```js
-Scenario('update user profile', ({  }) => {
-  // test goes here
-}).tag('@slow').tag('important');
-```
-
-All tests with `@tag` could be executed with `--grep '@tag'` option.
-
-```sh
-codeceptjs run --grep '@slow'
-```
-
-Use regex for more flexible filtering:
-
-* `--grep '(?=.*@smoke2)(?=.*@smoke3)'` - run tests with @smoke2 and @smoke3 in name
-* `--grep "\@smoke2|\@smoke3"` - run tests with @smoke2 or @smoke3 in name
-* `--grep '((?=.*@smoke2)(?=.*@smoke3))|@smoke4'` - run tests with (@smoke2 and @smoke3) or @smoke4 in name
-* `--grep '(?=.*@smoke2)^(?!.*@smoke3)'` - run tests with @smoke2 but without @smoke3 in name
-* `--grep '(?=.*)^(?!.*@smoke4)'` - run all tests except @smoke4
-
-
-
-## Debug
-
-CodeceptJS provides a debug mode in which additional information is printed.
-It can be turned on with `--debug` flag.
-
-```sh
-npx codeceptjs run --debug
-```
-
-to receive even more information turn on `--verbose` flag:
-
-```sh
-npx codeceptjs run --verbose
-```
-
-> You can pause execution and enter **interactive console** mode by calling `pause()` inside your test.
-
-To see a complete internal debug of CodeceptJS use `DEBUG` env variable:
-
-```sh
-DEBUG=codeceptjs:* npx codeceptjs run
-```
-
-For an interactive debugging use NodeJS debugger. In **WebStorm**:
-
-```sh
-node $NODE_DEBUG_OPTION ./node_modules/.bin/codeceptjs run
-```
-
-For **Visual Studio Code**, add the following configuration in launch.json:
-
-```json
-{
-  "type": "node",
-  "request": "launch",
-  "name": "codeceptjs",
-  "args": ["run", "--grep", "@your_test_tag"],
-  "program": "${workspaceFolder}/node_modules/.bin/codeceptjs"
-}
-```
-
-
-## Test Options
-
-Features and Scenarios have their options that can be set by passing a hash after their names:
-
-```js
-Feature('My feature', {key: val});
-
-Scenario('My scenario', {key: val},({ I }) => {});
-```
-
-You can use this options for build your own [plugins](https://codecept.io/hooks/#plugins) with [event listners](https://codecept.io/hooks/#api). Example: 
-
-```js
-  // for test
-  event.dispatcher.on(event.test.before, (test) => {
-    ...
-    if (test.opts.key) {
-      ...
-    }
-    ...
-  });
-  // or for suite
-  event.dispatcher.on(event.suite.before, (suite) => {
-    ...
-    if (suite.opts.key) {
-      ...
-    }
-    ...
-  });
-```
-
-## Timeout
-
-Tests can get stuck due to various reasons such as network connection issues, crashed browser, etc.
-This can make tests process hang. To prevent these situations timeouts can be used. Timeouts can be set explicitly for flaky parts of code, or implicitly in a config.
-
-> Previous timeout implementation was disabled as it had no effect when dealing with steps and promises. 
-
-### Steps Timeout
-
-It is possible to limit a step execution to specified time with `I.limitTime` command. 
-It will set timeout in seconds for the next executed step:
-
-```js
-// limit clicking to 5 seconds
-I.limitTime(5).click('Link')
-```
-
-It is possible to set a timeout for all steps implicitly (except waiters) using [stepTimeout plugin](/plugins/#steptimeout).
-
-### Tests Timeout
-
-Test timeout can be set in seconds via Scenario options:
-
-```js
-// limit test to 20 seconds
-Scenario('slow test that should be stopped', { timeout: 20 }, ({ I }) => {
-  // ...
-})
-```
-
-This timeout can be set globally in `codecept.conf.js` in seconds:
-
-```js
-exports.config = {
-
-  // each test must not run longer than 5 mins
-  timeout: 300,
-
-}
-```
-
-### Suites Timeout
-
-A timeout for a group of tests can be set on Feature level via options. 
-
-```js
-// limit all tests in this suite to 30 seconds
-Feature('flaky tests', { timeout: 30 })
-```
-
-### Timeout Confguration 
-
-<Badge text="Updated in 3.4" type="warning"/>
-
-Timeout rules can be set globally via config.
-
-To set a timeout for all running tests provide a **number of seconds** to `timeout` config option:
-
-
-```js
-// inside codecept.conf.js or codecept.conf.ts
-timeout: 30, // limit all tests in all suites to 30 secs
-```
-
-It is possible to tune this configuration for a different groups of tests passing options as array and using `grep` option to filter tests:
-
-```js
-// inside codecept.conf.js or codecept.conf.ts
-
-timeout: [
-  10, // default timeout is 10secs  
-
-  // but increase timeout for slow tests
-  {
-    grep: '@slow',
-    Feature: 50
-  },
-]
-```
-
-> ℹ️ `grep` value can be string or regexp
-
-It is possible to set a timeout for Scenario or Feature:
-
-```js
-// inside codecept.conf.js or codecept.conf.ts
-timeout: [
-
-  // timeout for Feature with @slow in title
-  {
-    grep: '@slow',
-    Feature: 50
-  },
-  
-  // timeout for Scenario with 'flaky0' .. `flaky1` in title
-  {
-    // regexp can be passed to grep
-    grep: /flaky[0-9]/,
-    Scenario: 10
-  },
-
-  // timeout for all suites
-  {    
-    Feature: 20
-  }
-]
-```
-
-Global timeouts will be overridden by explicit timeouts of a test or steps.
-
-### Disable Timeouts
-
-To execute tests ignoring all timeout settings use `--no-timeouts` option:
-
-```
-npx codeceptjs run --no-timeouts
-```
-
-## Dynamic Configuration
-
-Helpers can be reconfigured per scenario or per feature.
-This might be useful when some tests should be executed with different settings than others.
-In order to reconfigure tests use `.config()` method of `Scenario` or `Feature`.
-
-```js
-Scenario('should be executed in firefox', ({ I }) => {
-  // I.amOnPage(..)
-}).config({ browser: 'firefox' })
-```
-
-In this case `config` overrides current config of the first helper.
-To change config of specific helper pass two arguments: helper name and config values:
-
-```js
-Scenario('should create data via v2 version of API', ({ I }) => {
-  // I.amOnPage(..)
-}).config('REST', { endpoint: 'https://api.mysite.com/v2' })
-```
-
-Config can also be set by a function, in this case you can get a test object and specify config values based on it.
-This is very useful when running tests against cloud providers, like BrowserStack. This function can also be asynchronous.
-
-```js
-Scenario('should report to BrowserStack', ({ I }) => {
-  // I.amOnPage(..)
-}).config((test) => {
-  return { desiredCapabilities: {
-    project: test.suite.title,
-    name: test.title,
-  }}
-});
-```
-
-Config changes can be applied to all tests in suite:
-
-```js
-Feature('Admin Panel').config({ url: 'https://mysite.com/admin' });
-```
-
-Please note that some config changes can't be applied on the fly. For instance, if you set `restart: false` in your config and then changing value `browser` won't take an effect as browser is already started and won't be closed untill all tests finish.
-
-Configuration changes will be reverted after a test or a suite.
-

package/docs/api.md

@@ -1,323 +0,0 @@
----
-permalink: /api
-title: API Testing
----
-
-## API Testing
-
-CodeceptJS provides a way to write tests in declarative manner for REST and GraphQL APIs. 
-
-Take a look:
-
-```js
-I.sendGetRequest('/users/1');
-// returns { "user": { "name": "jon" }, "projects": [] }
-I.seeResponseCodeIsSuccessful();
-I.seeResponseContainsKeys(['user', 'projects']);
-I.seeResponseContainsJson({ user: { name: 'jon' } });
-I.seeResponseMatchesJsonSchema($ => {
-  return $.object(
-    user: $.object({
-      name: $.string(),
-    }),
-    projects: $.array()
-  )
-});
-```
-In this code we checked API request for:
-
-* status code
-* data inclusion
-* data structure
-
-These are the things you should generally test your APIs for.
-
-> 🤓 It is recommended to check only invariable parts of responses. Check for required fields and only values you control. For instance, it is not recommended to check id fields, date fields, as they can be frequently changed.
-
-## Installation
-
-Install CodeceptJS if it is not installed yet.
-
-```
-npm i codeceptjs --save-dev
-```
-
-Initialize CodeceptJS and select REST or GraphQL helper when asked for a helper:
-
-```
-npx codeceptjs init
-```
-
-## Configuration
-
-Ensure that inside `codecept.conf.js` in helpers section `REST` or `GraphQL` helpers are enabled.
-
-* If you use `REST` helper add `JSONResponse` helper below with no extra config:
-
-```js
-// inside codecept.conf.js
-// ...
-  helpers: {
-    REST: {
-      endpoint: 'http://localhost:3000/api'
-    },
-    // .. add JSONResponse helper here
-    JSONResponse: {}
-  }
-```
-* If you use `GraphQL` helper add `JSONResponse` helper, configuring it to use GraphQL for requests:
-
-```js
-  helpers: {
-    GraphQL: {
-      endpoint: 'http://localhost:3000/graphql'
-    },
-    // .. add JSONResponse helper here
-    JSONResponse: {
-      requestHelper: 'GraphQL',
-    }
-  }
-```
-
-Originally, REST and GraphQL helpers were not designed for API testing. 
-They were used to perform API requests for browser tests. As so, they lack assertion methods to API responses.
-
-[`JSONResponse`](/helpers/JSONResponse/) helper adds response assertions. 
-
-> 💡 In CodeceptJS assertions start with `see` prefix. Learn more about assertions by [opening reference for JSONResponse](/helpers/JSONResponse/) helper.
-
-Generate TypeScript definitions to get auto-completions for JSONResponse:
-
-```
-npx codeceptjs def
-```
-
-After helpers were configured and typings were generated, you can start writing first API test. By default, CodeceptJS saves tests in `tests` directory and uses `*_test.js` suffix. The `init` command created the first test for you to start.
-
-> Check [API Examples](https://github.com/codeceptjs/api-examples) to see tests implementations.
-
-## Requests
-
-[REST](/helpers/REST/) or [GraphQL](/helpers/GraphQL/) helpers implement methods for making API requests.
-Both helpers send requests via HTTP protocol from CodeceptJS process. 
-For most cases, you will need to have authentication. It can be passed via headers, which can be added to helper's configuration in `codecept.conf.js`. 
-
-```js
-helpers: {
-  REST: {
-    defaultHeaders: {
-      // use Bearer Authorization
-      'Authorization': 'Bearer 11111',
-      'Content-Type': 'application/json',
-      'Accept': 'application/json',
-    },
-  }
-}
-```
-
-Or you can use the browser cookies if you are running browser session.
-In this case use `setSharedCookies()` from `@codeceptjs/configure` package:
-
-```js
-const { setSharedCookies } = require('@codeceptjs/configure');
-
-// add this before exports.config
-setSharedCookies();
-
-exports.config = {
-  // ...
-  helpers: {  
-    // also works with Playwright or Puppeteer
-    WebDriver: {
-      //... 
-    },
-
-    REST: { 
-      // ...
-    }
-  }
-}
-```
-
-### REST
-
-REST helper can send GET/POST/PATCH/etc requests to REST API endpoint:
-
-* [`I.sendGetRequest()`](/helpers/REST#sendGetRequest)
-* [`I.sendPostRequest()`](/helpers/REST#sendPostRequest)
-* [`I.sendPutRequest()`](/helpers/REST#sendPutRequest)
-* [`I.sendPatchRequest()`](/helpers/REST#sendPatchRequest)
-* [`I.sendDeleteRequest()`](/helpers/REST#sendDeleteRequest)
-* ...
-
-Authentication headers can be set in [helper's config](https://codecept.io/helpers/REST/#configuration) or per test with headers or special methods like `I.amBearerAuthenticated`.
-
-Example:
-
-```js
-Feature('Users endpoint')
-
-Scenario('create user', ({ I }) => {
-    // this way we pass Bearer token
-  I.amBearerAuthenticated(secret('token-is-here'));
-  // for custom authorization with headers use
-  // I.haveRequestHeaders method
-
-  // here we send a POST request
-  const response = await I.sendPostRequest('/users', {
-    name: 'joe',
-    email: 'joe@mail.com'
-  });
-  // usually we won't need direct access to response object for API testing 
-  // but you can obtain it from request
-
-  // check the last request was successful
-  // this method introduced by JSONResponse helper
-  I.seeResponseCodeIsSuccessful();
-})
-```
-
-### GraphQL
-
-GraphQL have request format different then in REST API, but the response format is the same.
-It's plain old JSON. This why `JSONResponse` helper works for both API types.
-Configure authorization headers in `codecept.conf.js` and make your first query:  
-
-```js
-Feature('Users endpoint')
-
-Scenario('get user by query', ({ I }) => {
-  // make GraphQL query or mutation
-  const resp = await I.sendQuery('{ user(id: 0) { id name email }}');
-  I.seeResponseCodeIsSuccessful();
-
-  // GraphQL always returns key data as part of response
-  I.seeResponseContainsKeys(['data']);
-
-  // check data for partial inclusion
-  I.seeResponseContainsJson({
-    data: {
-      user: {
-        name: 'john doe',
-        email: 'johnd@mutex.com',
-      },
-    },
-  });
-});
-```
-
-GraphQL helper has two methods available:
-
-* [`I.sendQuery()`](/helpers/GraphQL#sendQuery)
-* [`I.sendMutation()`](/helpers/GraphQL#sendMutation)
-
-## Assertions
-
-`JSONResponse` provides set of assertions for responses in JSON format. These assertions were designed to check only invariable parts of responses. So instead of checking that response equals to the one provided, we will check for data inclusion and structure matching.
-
-For most of cases, you won't need to perform assertions by accessing `response` object directly. All assretions are performed under hood inside `JSONResponse` module. It is recommended to keep it that way, to keep tests readable and make test log to contain all assertions.
-
-```js
-Scenario('I make API call', ({ I }) => {
-  // request was made by REST 
-  // or by GraphQL helper
-
-  // check that response code is 2xx
-  I.seeResponseCodeIsSuccessful();
-
-  // check that response contains keys
-  I.seeResponseContainsKeys(['data', 'pages', 'meta']);
-});
-```
-
-### Response Status Codes
-
-[Response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) can be checked to be equal to some value or to be in a specific range. 
-To check that response code is `200` call `I.seeResponseCodeIs`:
-
-```js
-I.seeResponseCodeIs(200);
-```
-But because other response codes in 2xx range are also valid responses, you can use `seeResponseCodeIsSuccessful()` which will match 200 (OK), 201 (Created), 206 (Partial Content) and others. Methods to check 3xx, 4xx, 5xx response statuses also available.
-
-```js
-// matches 200, 201, 202, ... 206
-I.seeResponseCodeIsSuccessful();
-
-// matches 300...308
-I.seeResponseCodeIsRedirection();
-
-// matches 400..451
-I.seeResponseCodeIsClientError();
-
-// matches 500-511
-I.seeResponseCodeIsServerError();
-```
-
-### Structure
-
-The most basic thing to check in response is existence of keys in JSON object. Use [`I.seeResponseContainsKeys()`](/helpers/JSONResponse#seeResponseContainsKeys) method for it:
-
-```js
-// response is { "name": "joe", "email": "joe@joe.com" }
-I.seeResponseContainsKeys(['name', 'email']);
-```
-
-> ℹ️ If response is an array, it will check that every element in array have provided keys
-
-However, this is a very naive approach. It won't work for arrays or nested objects.
-To check complex JSON structures `JSONResponse` helper uses [`joi`](https://joi.dev) library. 
-It has rich API to validate JSON by the schema defined using JavaScript. 
-
-```js
-// require joi library, 
-// it is installed with CodeceptJS
-const Joi = require('joi');
-
-// create schema definition using Joi API
-const schema = Joi.object().keys({
-  email: Joi.string().email().required(),
-  phone: Joi.string().regex(/^\d{3}-\d{3}-\d{4}$/).required(),
-  birthday: Joi.date().max('1-1-2004').iso()
-});
-
-// check that response matches that schema
-I.seeResponseMatchesJsonSchema(schema);
-```
-
-### Data Inclusion
-
-To check that response contains expected data use `I.seeResponseContainsJson` method. 
-It will check the response data for partial match. 
-
-```js
-I.seeResponseContainsJson({
-  user: {
-    email: 'user@user.com'
-  }
-})
-```
-
-> ℹ️ If response is an array, it will check that at least one element in array matches JSON
-
-To perform arbitrary assertions on a response object use `seeResponseValidByCallback`. 
-It allows you to do any kind of assertions by using `expect` from [`chai`](https://www.chaijs.com) library.
-
-```js
-I.seeResponseValidByCallback(({ data, status, expect }) => {
-  // we receive data and expect to combine them for good assertion
-  expect(data.users.length).to.be.gte(10);
-})
-```
-
-## Extending JSONResponse
-
-To add more assertions it is recommended to create a custom helper.
-Inside it you can get access to latest JSON response:
-
-```js
-// inside a custom helper
-makeSomeCustomAssertion() {
-  const response = this.helpers.JSONResponse.response;
-}
-```