codeceptjs 3.4.0-beta.1 → 3.4.0

package/docs/build/ApiDataFactory.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const REST = require('./REST');
 
 /**
@@ -230,7 +230,7 @@ class ApiDataFactory extends Helper {
   }
 
   _after() {
-    if (!this.config.cleanup) {
+    if (!this.config.cleanup || this.config.cleanup === false) {
       return Promise.resolve();
     }
     const promises = [];
@@ -244,7 +244,6 @@ class ApiDataFactory extends Helper {
         promises.push(this._requestDelete(factoryName, createdItems[id]));
       }
     }
-
     return Promise.all(promises);
   }
 
@@ -379,7 +378,9 @@ Current file error: ${err.message}`);
 
     if (!request) {
       const method = Object.keys(this.factories[factory].delete)[0];
+
       const url = this.factories[factory].delete[method].replace('{id}', id);
+
       request = {
         method,
         url,
@@ -388,6 +389,10 @@ Current file error: ${err.message}`);
 
     request.baseURL = this.config.endpoint;
 
+    if (request.url.match(/^undefined/)) {
+      return this.debugSection('Please configure the delete request in your ApiDataFactory helper', 'delete: () => ({ method: \'DELETE\',  url: \'/api/users\' })');
+    }
+
     return this.restHelper._executeRequest(request).then(() => {
       const idx = this.created[factory].indexOf(id);
       this.debugSection('Deleted Id', `Id: ${id}`);

package/docs/build/FileSystem.js

@@ -2,7 +2,7 @@ const assert = require('assert');
 const path = require('path');
 const fs = require('fs');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const { fileExists } = require('../utils');
 const { fileIncludes } = require('../assert/include');
 const { fileEquals } = require('../assert/equal');

package/docs/build/GraphQL.js

@@ -1,5 +1,5 @@
 const axios = require('axios').default;
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 
 /**
  * GraphQL helper allows to send additional requests to a GraphQl endpoint during acceptance tests.

package/docs/build/GraphQLDataFactory.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const GraphQL = require('./GraphQL');
 
 /**

package/docs/build/JSONResponse.js

@@ -2,7 +2,7 @@ const assert = require('assert');
 const chai = require('chai');
 const joi = require('joi');
 const chaiDeepMatch = require('chai-deep-match');
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 
 chai.use(chaiDeepMatch);
 

package/docs/build/Mochawesome.js

@@ -2,7 +2,7 @@ let addMochawesomeContext;
 let currentTest;
 let currentSuite;
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const { clearString } = require('../utils');
 
 class Mochawesome extends Helper {

package/docs/build/Nightmare.js

@@ -2,7 +2,7 @@ const path = require('path');
 
 const urlResolve = require('url').resolve;
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const { includes: stringIncludes } = require('../assert/include');
 const { urlEquals } = require('../assert/equal');
 const { equals } = require('../assert/equal');

package/docs/build/Playwright.js

@@ -1,7 +1,7 @@
 const path = require('path');
 const fs = require('fs');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const Locator = require('../locator');
 const recorder = require('../recorder');
 const stringIncludes = require('../assert/include').includes;

package/docs/build/Protractor.js

@@ -6,7 +6,7 @@ let ProtractorExpectedConditions;
 
 const path = require('path');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const stringIncludes = require('../assert/include').includes;
 const { urlEquals, equals } = require('../assert/equal');
 const { empty } = require('../assert/empty');

package/docs/build/Puppeteer.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const fsExtra = require('fs-extra');
 const path = require('path');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const Locator = require('../locator');
 const recorder = require('../recorder');
 const stringIncludes = require('../assert/include').includes;

package/docs/build/REST.js

@@ -1,7 +1,7 @@
 const axios = require('axios').default;
+const Helper = require('@codeceptjs/helper');
 const Secret = require('../secret');
 
-const Helper = require('../helper');
 const { beautify } = require('../utils');
 
 /**

package/docs/build/TestCafe.js

@@ -6,6 +6,7 @@ const qrcode = require('qrcode-terminal');
 const createTestCafe = require('testcafe');
 const { Selector, ClientFunction } = require('testcafe');
 
+const Helper = require('@codeceptjs/helper');
 const ElementNotFound = require('./errors/ElementNotFound');
 const testControllerHolder = require('./testcafe/testControllerHolder');
 const {
@@ -22,7 +23,6 @@ const {
   xpathLocator,
 } = require('../utils');
 const Locator = require('../locator');
-const Helper = require('../helper');
 
 /**
  * Client Functions

package/docs/build/WebDriver.js

@@ -4,7 +4,7 @@ const assert = require('assert');
 const path = require('path');
 const fs = require('fs');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const stringIncludes = require('../assert/include').includes;
 const { urlEquals, equals } = require('../assert/equal');
 const { debug } = require('../output');

package/docs/changelog.md

@@ -7,6 +7,53 @@ layout: Section
 
 # Releases
 
+## 3.4.0
+
+* **Updated to latest mocha and modern Cucumber**
+* **Allure plugin moved to [@codeceptjs/allure-legacy](https://github.com/codeceptjs/allure-legacy) package**. This happened because allure-commons package v1 was not updated and caused vulnarabilities. Fixes [#3422](https://github.com/codeceptjs/CodeceptJS/issues/3422). We don't plan to maintain allure v2 plugin so it's up to community to take this initiative. Current allure plugin will print a warning message without interfering the run, so it won't accidentally fail your builds.
+* Added ability to **[retry Before](https://codecept.io/basics/#retry-before), BeforeSuite, After, AfterSuite** hooks by **[davertmik](https://github.com/davertmik)**:
+```js
+Feature('flaky Before & BeforeSuite', { retryBefore: 2, retryBeforeSuite: 3 })
+```
+
+* **Flexible [retries configuration](https://codecept.io/basics/#retry-configuration) introduced** by **[davertmik](https://github.com/davertmik)**:
+
+```js
+retry: [
+  {
+    // enable this config only for flaky tests
+    grep: '@flaky', 
+    Before: 3 // retry Before 3 times
+    Scenario: 3 // retry Scenario 3 times
+  }, 
+  {
+    // retry less when running slow tests
+    grep: '@slow' 
+    Scenario: 1
+    Before: 1
+  }, {
+    // retry all BeforeSuite 3 times
+    BeforeSuite: 3
+  }
+]
+```
+* **Flexible [timeout configuration](https://codecept.io/advanced/#timeout-configuration)** introduced by **[davertmik](https://github.com/davertmik)**:
+
+```js
+timeout: [
+  10, // default timeout is 10secs  
+  {   // but increase timeout for slow tests
+    grep: '@slow',
+    Feature: 50
+  },
+]
+```
+
+* JsDoc: Removed promise from `I.say`. See [#3535](https://github.com/codeceptjs/CodeceptJS/issues/3535) by **[danielrentz](https://github.com/danielrentz)**
+* **[Playwright]** `handleDownloads` requires now a filename param. See [#3511](https://github.com/codeceptjs/CodeceptJS/issues/3511) by **[PeterNgTr](https://github.com/PeterNgTr)** 
+* **[WebDriver]** Added support for v8, removed support for webdriverio v5 and lower. See [#3578](https://github.com/codeceptjs/CodeceptJS/issues/3578) by **[PeterNgTr](https://github.com/PeterNgTr)**
+
+
 ## 3.3.7
 
 🛩️ Features
@@ -37,8 +84,8 @@ layout: Section
 
 📖 Documentation
 
-* Updated [Auickstart](https://codecept.io/quickstart/) with detailed explanation of questions in init
-* Added [Translation](/translations/) guide
+* Updated [Quickstart](https://codecept.io/quickstart/) with detailed explanation of questions in init
+* Added [Translation](/translation/) guide
 * Updated [TypeScript](https://bit.ly/3XIMq6n) guide for promise-based typings
 * Reordered guides list on a website
 

package/docs/plugins.md

@@ -7,98 +7,6 @@ title: Plugins
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-## allure
-
-Allure reporter
-
-> ⚠️ This plugin was moved to its [own package][1]
-
-![][2]
-
-Enables Allure reporter.
-
-#### Usage
-
-To start please install `allure-commandline` package (which requires Java 8)
-
-    npm install -g allure-commandline --save-dev
-
-Add this plugin to config file:
-
-```js
-"plugins": {
-    "allure": {}
-}
-```
-
-Run tests with allure plugin enabled:
-
-    npx codeceptjs run --plugins allure
-
-By default, allure reports are saved to `output` directory.
-Launch Allure server and see the report like on a screenshot above:
-
-    allure serve output
-
-#### Configuration
-
--   `outputDir` - a directory where allure reports should be stored. Standard output directory is set by default.
--   `enableScreenshotDiffPlugin` - a boolean flag for add screenshot diff to report.
-     To attach, tou need to attach three files to the report - "diff.png", "actual.png", "expected.png".
-     See [Allure Screenshot Plugin][3]
-
-#### Public API
-
-There are few public API methods which can be accessed from other plugins.
-
-```js
-const allure = codeceptjs.container.plugins('allure');
-```
-
-`allure` object has following methods:
-
--   `addAttachment(name, buffer, type)` - add an attachment to current test / suite
--   `addLabel(name, value)` - adds a label to current test
--   `addParameter(kind, name, value)` - adds a parameter to current test
--   `createStep(name, stepFunc)` - create a step, stepFunc could consist an attachment
-    Example of usage:
-
-```js
-    allure.createStep('New created step', () => {
-      allure.addAttachment(
-        'Request params',
-        '{"clientId":123, "name":"Tom", "age":29}',
-        'application/json'
-      );
-    });
-```
-
-![Created Step Image][4]
-
--   `addScreenDiff(name, expectedImg, actualImg, diffImg)` - add a special screen diff block to the current test case
-    image must be a string representing the contents of the expected image file encoded in base64
-    Example of usage:
-
-```js
-const expectedImg = fs.readFileSync('expectedImg.png', { encoding: 'base64' });
-...
-allure.addScreenDiff('Screen Diff', expectedImg, actualImg, diffImg);
-```
-
-![Overlay][5]
-![Diff][6]
-
--   `severity(value)` - adds severity label
--   `epic(value)` - adds epic label
--   `feature(value)` - adds feature label
--   `story(value)` - adds story label
--   `issue(value)` - adds issue label
--   `setDescription(description, type)` - sets a description
-
-### Parameters
-
--   `config`  
-
 ## autoDelay
 
 Sometimes it takes some time for a page to respond to user's actions.
@@ -464,7 +372,7 @@ Possible config options:
 
 ## customLocator
 
-Creates a [custom locator][7] by using special attributes in HTML.
+Creates a [custom locator][1] by using special attributes in HTML.
 
 If you have a convention to use `data-test-id` or `data-qa` attributes to mark active elements for e2e tests,
 you can enable this plugin to simplify matching elements with these attributes:
@@ -614,9 +522,9 @@ This method works with WebDriver, Playwright, Puppeteer, Appium helpers.
 Function parameter `el` represents a matched element.
 Depending on a helper API of `el` can be different. Refer to API of corresponding browser testing engine for a complete API list:
 
--   [Playwright ElementHandle][8]
--   [Puppeteer][9]
--   [webdriverio element][10]
+-   [Playwright ElementHandle][2]
+-   [Puppeteer][3]
+-   [webdriverio element][4]
 
 #### Configuration
 
@@ -630,17 +538,17 @@ const eachElement = codeceptjs.container.plugins('eachElement');
 
 ### Parameters
 
--   `purpose` **[string][11]** 
+-   `purpose` **[string][5]** 
 -   `locator` **CodeceptJS.LocatorOrString** 
--   `fn` **[Function][12]** 
+-   `fn` **[Function][6]** 
 
-Returns **([Promise][13]&lt;any> | [undefined][14])** 
+Returns **([Promise][7]&lt;any> | [undefined][8])** 
 
 ## fakerTransform
 
-Use the [faker.js][15] package to generate fake data inside examples on your gherkin tests
+Use the [faker.js][9] package to generate fake data inside examples on your gherkin tests
 
-![Faker.js][16]
+![Faker.js][10]
 
 #### Usage
 
@@ -678,7 +586,7 @@ Scenario Outline: ...
 
 ## pauseOnFail
 
-Automatically launches [interactive pause][17] when a test fails.
+Automatically launches [interactive pause][11] when a test fails.
 
 Useful for debugging flaky tests on local environment.
 Add this plugin to config file:
@@ -694,10 +602,6 @@ Enable it manually on each run via `-p` option:
 
     npx codeceptjs run -p pauseOnFail
 
-## reporter
-
-Type: Allure
-
 ## retryFailedStep
 
 Retries each failed step in a test.
@@ -865,14 +769,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][18] plugin automatically starts browsers and video recording.
+[Selenoid][12] plugin automatically starts browsers and video recording.
 Works with WebDriver helper.
 
 ### Prerequisite
 
 This plugin **requires Docker** to be installed.
 
-> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][19] tool from Selenoid
+> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][13] tool from Selenoid
 
 ### Usage
 
@@ -901,7 +805,7 @@ plugins: {
   }
 ```
 
-When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][20] and start Selenoid automatically.
+When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][14] and start Selenoid automatically.
 It will also create `browsers.json` file required by Selenoid.
 
 In automatic mode the latest version of browser will be used for tests. It is recommended to specify exact version of each browser inside `browsers.json` file.
@@ -913,10 +817,10 @@ In automatic mode the latest version of browser will be used for tests. It is re
 While this plugin can create containers for you for better control it is recommended to create and launch containers manually.
 This is especially useful for Continous Integration server as you can configure scaling for Selenoid containers.
 
-> Use [Selenoid Configuration Manager][19] to create and start containers semi-automatically.
+> Use [Selenoid Configuration Manager][13] to create and start containers semi-automatically.
 
 1.  Create `browsers.json` file in the same directory `codecept.conf.js` is located
-    [Refer to Selenoid documentation][21] to know more about browsers.json.
+    [Refer to Selenoid documentation][15] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -941,7 +845,7 @@ _Sample browsers.json_
 
 2.  Create Selenoid container
 
-Run the following command to create a container. To know more [refer here][22]
+Run the following command to create a container. To know more [refer here][16]
 
 ```bash
 docker create                                    \
@@ -974,7 +878,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 | enableVideo      | Enable video recording and use `video` folder of output (default: false)       |
 | enableLog        | Enable log recording and use `logs` folder of output (default: false)          |
 | deletePassed     | Delete video and logs of passed tests (default : true)                         |
-| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][23] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][17] to know more   |
 
 ### Parameters
 
@@ -982,7 +886,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 
 ## stepByStepReport
 
-![step-by-step-report][24]
+![step-by-step-report][18]
 
 Generates step by step report for a test.
 After each step in a test a screenshot is created. After test executed screenshots are combined into slideshow.
@@ -1163,7 +1067,7 @@ This plugin allows to run webdriverio services like:
 -   browserstack
 -   appium
 
-A complete list of all available services can be found on [webdriverio website][25].
+A complete list of all available services can be found on [webdriverio website][19].
 
 #### Setup
 
@@ -1175,7 +1079,7 @@ See examples below:
 
 #### Selenium Standalone Service
 
-Install `@wdio/selenium-standalone-service` package, as [described here][26].
+Install `@wdio/selenium-standalone-service` package, as [described here][20].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -1194,7 +1098,7 @@ Please note, this service can be used with Protractor helper as well!
 
 #### Sauce Service
 
-Install `@wdio/sauce-service` package, as [described here][27].
+Install `@wdio/sauce-service` package, as [described here][21].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -1224,56 +1128,44 @@ In the same manner additional services from webdriverio can be installed, enable
 
 -   `config`  
 
-[1]: https://github.com/codeceptjs/allure-plugin
-
-[2]: https://user-images.githubusercontent.com/220264/45676511-8e052800-bb3a-11e8-8cbb-db5f73de2add.png
-
-[3]: https://github.com/allure-framework/allure2/blob/master/plugins/screen-diff-plugin/README.md
-
-[4]: https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png
-
-[5]: https://user-images.githubusercontent.com/63167966/215404458-9a325668-819e-4289-9b42-5807c49ebddb.png
-
-[6]: https://user-images.githubusercontent.com/63167966/215404645-73b09da0-9e6d-4352-a123-80c22f7014cd.png
-
-[7]: https://codecept.io/locators#custom-locators
+[1]: https://codecept.io/locators#custom-locators
 
-[8]: https://playwright.dev/docs/api/class-elementhandle
+[2]: https://playwright.dev/docs/api/class-elementhandle
 
-[9]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
+[3]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
 
-[10]: https://webdriver.io/docs/api
+[4]: https://webdriver.io/docs/api
 
-[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
 
-[15]: https://www.npmjs.com/package/faker
+[9]: https://www.npmjs.com/package/faker
 
-[16]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
+[10]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
 
-[17]: /basics/#pause
+[11]: /basics/#pause
 
-[18]: https://aerokube.com/selenoid/
+[12]: https://aerokube.com/selenoid/
 
-[19]: https://aerokube.com/cm/latest/
+[13]: https://aerokube.com/cm/latest/
 
-[20]: https://hub.docker.com/u/selenoid
+[14]: https://hub.docker.com/u/selenoid
 
-[21]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[15]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[22]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[16]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[23]: https://docs.docker.com/engine/reference/commandline/create/
+[17]: https://docs.docker.com/engine/reference/commandline/create/
 
-[24]: https://codecept.io/img/codeceptjs-slideshow.gif
+[18]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[25]: https://webdriver.io
+[19]: https://webdriver.io
 
-[26]: https://webdriver.io/docs/selenium-standalone-service.html
+[20]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[27]: https://webdriver.io/docs/sauce-service.html
+[21]: https://webdriver.io/docs/sauce-service.html

package/docs/tutorial.md

@@ -0,0 +1,271 @@
+---
+permalink: /tutorial
+title: CoeceptJS Complete Tutorial
+---
+
+**[CodeceptJS](https://codecept.io) is a popular open-source testing framework** for JavaScript. It is designed to simplify writing and maintain end-to-end tests for web applications, using a readable and intuitive syntax. To run tests in browser it uses **[Playwright](https://playwright.dev)** library from Microsoft.
+
+CodeceptJS was started in 2015 and is widely used by organizations of all sizes, from startups to large enterprises.
+
+## Let's get CodeceptJS installed!
+
+To install CodeceptJS, you will need to have Node.js and npm (the Node.js package manager) installed on your system. You can check if you already have these tools installed by running the following commands in a terminal:
+
+```bash
+node --version
+npm --version
+```
+
+If either of these commands return an error, you will need to install Node.js and npm before you can install CodeceptJS. You can download and install the latest version of Node.js from the official website, which includes npm.
+
+To install CodeceptJS create a new folder and run command form terminal:
+
+```
+npx create-codeceptjs .
+```
+
+If you run the npx create-codeceptjs . command, it will install CodeceptJS with Playwright in the current directory. 
+
+> The `npx` command is a tool that comes with npm (the Node.js package manager) and it allows you to run npm packages without having to install them globally on your system.
+
+It may take some time as it downloads browsers: Chrome, Firefox and Safari and creates a demo project.
+
+But we are here to write a checkout test, right?
+
+Let's initialize a new project for that!
+
+Run 
+
+```
+npx codeceptjs init
+```
+Agree on defaults (press Enter for every question asked). When asked for base site URL, provide a URL of a ecommerce website you are testing. For instance, it could be: `https://myshop.com` if you test already published website or `http://localhost` if you run the website locally. 
+
+When asked for a test name and suite name write "Checkout". It will create the following dirctory structure:
+
+```
+.
+├── codecept.conf.js
+├── package.json
+└── Checkout_test.js
+```
+
+The `codecept.conf.js` file in the root of the project directory contains the global configuration settings for CodeceptJS.
+
+Now open a test:
+
+```js
+Feature('Checkout');
+
+Scenario('test something', ({ I }) => {
+});
+```
+Inside the Scenario block you write a test. 
+
+Add `I.amOnPage('/')` into it. It will open the browser on a URL you specified as a base.
+
+```js
+Feature('Checkout');
+
+Scenario('test something', ({ I }) => {
+  I.amOnPage('/')
+});
+```
+But you may want to ask...
+
+## What is I?
+
+Glad you asked! 
+
+In CodeceptJS, the `I` object is used to represent the user performing actions in a test scenario. It provides a number of methods (also known as actions) that can be used to simulate user interactions with the application under test.
+
+Some of the most popular actions of the I object are:
+
+* `I.amOnPage(url)`: This action navigates the user to the specified URL.
+* `I.click(locator)`: This action simulates a click on the element identified by the given locator.
+* `I.fillField(field, value)`: This action fills the specified field with the given value.
+* `I.see(text, context)`: This action checks that the given text is visible on the page (or in the specified context).
+* `I.selectOption(select, option)`: This action selects the specified option from the given select dropdown.
+* `I.waitForElement(locator, timeout)`: This action waits for the specified element to appear on the page, up to the given timeout.
+* `I.waitForText(text, timeout, context)`: This action waits for the given text to appear on the page (or in the specified context), up to the given timeout.
+
+We will need to use them to navigate into Checkout process. How do we navigate web? Sure by clicking on links!
+
+Let's use `I.click()` for that.
+
+But how we can access elements on a webpage? 
+
+CodeceptJS is smart enough to locate clickable elements by their visible text. For instance, if on your ecommerce website you have a product 'Coffee Cup' with that exact name you can use 
+
+```js
+I.click('Coffee Cup');
+```
+
+But sometimes elements are not as easy to locate, so you can use CSS or XPath locators to locate them.
+
+For instance, locating Coffee Cup via CSS can take into accont HTML structure of a page and element attributes. For instance, it can be like this:
+
+```js
+I.click('div.products a.product-name[title="Coffee Cup"]');
+```
+
+In this example, the `div.products` part of the selector specifies a div element with the `products` class, and the `a.product-name[title="Coffee Cup"]` part specifies an a element with `the product-name` class and the `title` attribute set to Coffee Cup. 
+
+You can read more about HTML and CSS locators, and basically that's all what you need to know to start writing a checkout test!
+
+## Get back to Checkout
+
+Let's see how a regular checkout script may look in CodeceptJS:
+
+```js
+Scenario('test the checkout form', async ({ I }) => {
+  // we select one product and switched to checkout project
+  I.amOnPage('/');
+  I.click('Coffee Cup');
+  I.click('Purchase');
+  I.click('Checkout');
+
+  // fill in the shipping address
+  I.fillField('First Name', 'John');
+  I.fillField('Last Name', 'Doe');
+  I.fillField('Address', '123 Main St.');
+  I.fillField('City', 'New York');
+  I.selectOption('State', 'New York');
+  I.fillField('Zip Code', '10001');
+
+  // select a payment method
+  I.click('#credit-card-option');
+  I.fillField('Card Number', '1234-5678-9012-3456');
+  I.fillField('Expiration Date', '12/22');
+  I.fillField('Security Code', '123');
+
+  // click the checkout button
+  I.click('Checkout');
+
+  // verify that the checkout was successful
+  I.see('Your order has been placed successfully!');
+});
+``` 
+Sure, in relaity your script might be more complicated. As you have noticed, we used CSS locator `'#credit-card-option'`  to get select a payment option. However, the test is simple and you can follow user steps through it.
+
+Please note, that you shouldn't use a real credit card number here. Good news, you don't need to. Payment providers like Strip provide dummy card numbers for testing purposes. 
+
+Run the test with next command:
+
+```
+npx codeceptjs run --debug -p pauseOnFail
+```
+
+What are special options here?
+
+* `--debug` flag is used to output additional information to the console, such as the details of each step in the test, the values of variables, and the results of test assertions. This can help you to identify and fix any issues in your tests.
+* `-p pauseOnFail` option is also used to keep the browser opened even if a test fails. It will help us to identify to which point test was executed and what can be improved.
+
+Add more test steps if needed, update locators, and notify business owners that all that purchases are made by you so your collegues won't call you in the night asking when you want to get a coffee cup 😀 Also the good idea is to run tests on staging website, to not interfere with business process.
+
+What a test is complete you can run it with:
+
+```
+npx codeceptjs run
+```
+
+If you are annoyed to see a browser window you can use `HEADLESS` environment variable:
+
+```
+HEADLESS=true codeceptjs run
+```
+for Windows users HEADLESS should be set in a different manner:
+
+```
+set HEADLESS=true&& codeceptjs run
+```
+The tests will pass but no browser is shown, so you can watch YouTube videos while it goes!
+
+## Refactoring
+
+What if you need to check more purchases? Should you copy paste your code for that?
+
+No! You can use Page Object pattern to put repeating interactions into the reusable functions.
+
+You can create a page object via next command:
+
+```
+npx codeceptjs gpo
+```
+
+Sure, we will call it `Checkout`. It will be created in `./pages/Checkout.js` file. You should enable it in `codecept.conf.js` inside `include` section:
+
+```js
+    include: {
+    ...
+      checkoutPage: './pages/Checkout.js',
+    },
+
+```
+Now open this file:
+
+```js
+const { I } = inject();
+
+module.exports = {
+
+  // insert your locators and methods here
+}
+```
+
+Feels really empty. What should we do about it? Should we write more code? No, we already have it. Let's copy code blocks from a test we have it and place them under a corredponnding function names:
+
+```js
+connst { I } = inject();
+
+module.exports = {
+
+  fillShippingAddress(name, address, city, state, zip) {
+    I.fillField('Name', name);
+    I.fillField('Address', address);
+    I.fillField('City', city);
+    I.fillField('State', state);
+    I.fillField('Zip', zip);
+  },
+
+  fillValidCreditCard() {
+    I.click('#credit-card-option');
+    I.fillField('Card Number', '1234-5678-9012-3456');
+    I.fillField('Expiration Date', '12/22');
+    I.fillField('Security Code', '123');
+  },
+
+  checkout() {
+    I.click('Checkout');
+  },
+}
+```
+
+After that we can update our test to use the created page object. Note, that we import Checkout PageObject by its name `checkoutPage` we previously defined in a config.
+
+```js
+Scenario('test the checkout form', async ({I, checkoutPage}) => {
+  I.amOnPage('/');
+  I.click('Coffee Cup');
+  I.click('Purchase');
+  I.click('Checkout');
+
+  // fill in the shipping address using the page object
+  checkoutPage.fillShippingAddress('John', 'Doe', '123 Main St.', 'New York', 'New York', '10001');
+  checkoutPage.fillValidCreditCard();
+  checkoutPage.checkout();
+
+  // verify that the checkout was successful
+  I.see('Your order has been placed successfully!');
+});
+```
+
+As you see the code of a test was reduced. And we can write the similar tests on the same manner.
+
+By applying more and more cases you can test a website to all behaviors.
+
+## Summary
+
+This was a deep dive! If you think on just starting test automation, CodeceptJS is the best choice for you as it uses native language to pass commands to browser. 
+
+If you already skilled in JavaScript, with CodeceptJS you can focus on business level of your test, instead of writing code for browser. This way you can keep your tests stable and maintainable.

package/lib/helper/ApiDataFactory.js

@@ -230,7 +230,7 @@ class ApiDataFactory extends Helper {
   }
 
   _after() {
-    if (!this.config.cleanup) {
+    if (!this.config.cleanup || this.config.cleanup === false) {
       return Promise.resolve();
     }
     const promises = [];
@@ -244,7 +244,6 @@ class ApiDataFactory extends Helper {
         promises.push(this._requestDelete(factoryName, createdItems[id]));
       }
     }
-
     return Promise.all(promises);
   }
 
@@ -379,7 +378,9 @@ Current file error: ${err.message}`);
 
     if (!request) {
       const method = Object.keys(this.factories[factory].delete)[0];
+
       const url = this.factories[factory].delete[method].replace('{id}', id);
+
       request = {
         method,
         url,
@@ -388,6 +389,10 @@ Current file error: ${err.message}`);
 
     request.baseURL = this.config.endpoint;
 
+    if (request.url.match(/^undefined/)) {
+      return this.debugSection('Please configure the delete request in your ApiDataFactory helper', 'delete: () => ({ method: \'DELETE\',  url: \'/api/users\' })');
+    }
+
     return this.restHelper._executeRequest(request).then(() => {
       const idx = this.created[factory].indexOf(id);
       this.debugSection('Deleted Id', `Id: ${id}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.4.0-beta.1",
+  "version": "3.4.0",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -131,7 +131,7 @@
     "testcafe": "^2.1.0",
     "ts-morph": "^3.1.3",
     "ts-node": "^10.9.1",
-    "tsd-jsdoc": "https://github.com/englercj/tsd-jsdoc.git",
+    "tsd-jsdoc": "^2.5.0",
     "typedoc": "^0.23.10",
     "typedoc-plugin-markdown": "^3.13.4",
     "typescript": "^4.8.4",

package/typings/index.d.ts

@@ -18,18 +18,28 @@ declare namespace CodeceptJS {
   };
 
   type RetryConfig = {
-    grep: string;
+    /** Filter tests by string or regexp pattern */
+    grep: string | RegExp;
+    /** Number of times to repeat scenarios of a Feature */
     Feature: number;
+    /** Number of times to repeat scenarios */
     Scenario: number;
+    /** Number of times to repeat Before hook */
     Before: number;
+    /** Number of times to repeat After hook */
     After: number;
+    /** Number of times to repeat BeforeSuite hook */
     BeforeSuite: number;
+    /** Number of times to repeat AfterSuite hook */
     AfterSuite: number;
   };
 
   type TimeoutConfig = {
-    grep: string;
+    /** Filter tests by string or regexp pattern */
+    grep: string | RegExp;
+    /** Set timeout for a scenarios of a Feature */
     Feature: number;
+    /** Set timeout for scenarios */
     Scenario: number;
   };