codeceptjs 4.0.0-rc.20 → 4.0.0-rc.22

package/docs/hooks.md

@@ -3,337 +3,136 @@ permalink: /hooks
 title: Extending CodeceptJS
 ---
 
-# Extending 
+# Extending CodeceptJS
 
-CodeceptJS provides API to run custom code before and after the test and inject custom listeners into the event system.
+CodeceptJS has four extension points. Pick the lightest one that does the job:
 
+| Use | To |
+| --- | --- |
+| [`bootstrap` / `teardown`](/bootstrap) | run setup or teardown code once, around the whole suite |
+| [Event listeners](#event-listeners) | react to test, suite, or step events without packaging anything |
+| [Plugins](#plugins) | bundle reusable behavior — listeners, recorder hooks, config — into a module |
+| [Custom helpers](/helpers) | add new `I.*` actions backed by a browser or an HTTP library |
 
-## Plugins
-
-Plugins allow to use CodeceptJS internal API to extend functionality. Use internal event dispatcher, container, output, promise recorder, to create your own reporters, test listeners, etc.
+Listeners and plugins use CodeceptJS internals — the `event` dispatcher, the `recorder` promise chain, the `container`, `output`. See [Architecture](/architecture) for what those are and how a test runs.
 
-CodeceptJS includes [built-in plugins](/plugins/) which extend basic functionality and can be turned on and off on purpose. Taking them as [examples](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/plugin) you can develop your custom plugins.
+## Event Listeners
 
-A plugin is a basic JS module returning a function. Plugins can have individual configs which are passed into this function:
+Attach a listener to `event.dispatcher` to run code at any point in the [test lifecycle](/architecture#events). A listener can live in a [plugin](#plugins) or in your [`bootstrap`](/bootstrap) script.
 
 ```js
-const defaultConfig = {
-  someDefaultOption: true
-}
+import { event } from 'codeceptjs'
 
-export default function(config) {
-  config = Object.assign(defaultConfig, config);
-  // do stuff
-}
+event.dispatcher.on(event.test.before, test => {
+  console.log(`starting ${test.title}`)
+})
 ```
 
-Plugin can register event listeners or hook into promise chain with recorder. See [API reference](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/helper).
-
-To enable your custom plugin in config add it to `plugins` section. Specify path to node module using `require`.
+[Sync events](/architecture#events) run inline. For async work, queue it on the recorder so it runs in order with the test's steps:
 
 ```js
-"plugins": {
-  "myPlugin": {
-    "require": "./path/to/my/module",
-    "enabled": true
-  }
-}
-```
+import { event, recorder } from 'codeceptjs'
 
-* `require` - specifies relative path to a plugin file. Path is relative to config file.
-* `enabled` - to enable this plugin.
-
-If a plugin is disabled (`enabled` is not set or false) this plugin can be enabled from command line:
-
-```
-npx codeceptjs run --plugin myPlugin
+event.dispatcher.on(event.test.before, () => {
+  recorder.add('seed fixture data', async () => {
+    await api.post('/users', { name: 'john', email: 'john@example.com' })
+  })
+})
 ```
 
-Several plugins can be enabled as well:
-
-```
-npx codeceptjs run --plugin myPlugin,allure
-```
+See [Architecture › Events](/architecture#events) for the full event list and the test and step object fields.
 
-### Example: Execute code for a specific group of tests
+## Plugins
 
-If you need to execute some code before a group of tests, you can [mark these tests with a same tag](/advanced/#tags). Then to listen for tests where this tag is included (see [test object api](#test-object)).
+A plugin packages listeners, recorder hooks, container changes, and config into one module. CodeceptJS ships [built-in plugins](/plugins) — [their source](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/plugin) doubles as example code.
 
-Let's say we need to populate database for a group of tests.
+A plugin is a module that exports a function. CodeceptJS calls it once at startup with the plugin's config:
 
 ```js
-// populate database for slow tests
-import { event } from 'codeceptjs';
-
-export default function() {
-
-  event.dispatcher.on(event.test.before, function (test) {
+import { event } from 'codeceptjs'
 
-    if (test.tags.indexOf('@populate') >= 0) {
-      recorder.add('populate database', async () => {
-        // populate database for this test
-      })
-    }
-  });
+const defaultConfig = {
+  someOption: true,
 }
-```
-
-### Example: Check URL before running a test
-
-If you want to share bootstrap script or run multiple bootstraps, it's a good idea to wrap that script into a plugin.
-Plugin can also execute JS before tests but you need to use internal APIs to synchronize promises.
-
-```js
-import { recorder } from 'codeceptjs';
 
-export default function(options) {
+export default function (config) {
+  config = { ...defaultConfig, ...config }
 
-  event.dispatcher.on(event.all.before, function () {
-    recorder.startUnlessRunning(); // start recording promises
-    recorder.add('do some async stuff', async () => {
-      // your code
-    });
-  });
+  event.dispatcher.on(event.test.before, test => {
+    // use config, register listeners, hook into the recorder
+  })
 }
 ```
 
-## API
+### Enabling a plugin
 
-**Use local CodeceptJS installation to get access to `codeceptjs` module**
-
-CodeceptJS provides an API which can be loaded via `import codeceptjs, { recorder, event, output } from 'codeceptjs'` when CodeceptJS is installed locally.
-These internal objects are available:
-
-* [`codecept`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/codecept.js): test runner class
-* [`config`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/config.js): current codecept config
-* [`event`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/event.js): event listener
-* [`recorder`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/recorder.js): global promise chain
-* [`output`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/output.js): internal printer
-* [`container`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/container.js): dependency injection container for tests, includes current helpers and support objects
-* [`helper`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/helper.js): basic helper class
-* [`actor`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/actor.js): basic actor (I) class
-
-[API reference](https://github.com/codeceptjs/CodeceptJS/tree/master/docs/api) is available on GitHub.
-Also please check the source code of corresponding modules.
-
-### Event Listeners
-
-CodeceptJS provides a module with [event dispatcher and set of predefined events](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/event.js).
-
-It can be required from codeceptjs package if it is installed locally.
+Add it to the `plugins` section of the config and point `require` at the module:
 
 ```js
-import { event } from 'codeceptjs';
-
-export default function() {
-
-  event.dispatcher.on(event.test.before, function (test) {
-
-    console.log('--- I am before test --');
-
-  });
+plugins: {
+  myPlugin: {
+    require: './path/to/plugin',   // relative to the config file
+    enabled: true,
+  }
 }
 ```
 
-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. Passes a current test object.
-* `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.bddStep.before(bddStep)` - *async* when the gherkin step is scheduled for execution
-* `event.bddStep.after(bddStep)` - *async* after a gherkin step
-* `event.all.before` - before running tests
-* `event.all.after` - after running tests
-* `event.all.result` - when results are printed
-
-* *sync* - means that event is fired in the moment of action happens.
-* *async* - means that event is fired when an actions is scheduled. Use `recorder` to schedule your actions.
-
-For further reference look for [currently available listeners](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/listener) using event system.
-
-#### Test Object
-
-Test events provide a test object with following fields:
-
-* `title` title of a 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
-* `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 `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
-
-### 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/codeceptjs/CodeceptJS/blob/master/lib/recorder.js) represents a global promises chain.
-
-Provide a function description as a first parameter, function should return a promise:
+- `require` — path to the plugin file, relative to the config file.
+- `enabled` — set `true` to load it.
+- any other key is passed straight to the plugin function as config.
 
-```js
-import { event, recorder } from 'codeceptjs';
-import request from 'request';
-
-export default function() {
-
-  event.dispatcher.on(event.test.before, function (test) {
-
-    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();
-        }
-      });
-    }
-  });
-}
+A disabled or unlisted plugin can be turned on for a single run from the command line:
 
 ```
-
-Whenever you execute tests with `--verbose` option you will see registered events and promises executed by a recorder.
-
-
-### Output
-
-Output module provides 4 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
-import { output } from 'codeceptjs';
-
-output.print('This is basic information');
-output.debug('This is debug information');
-output.log('This is verbose logging information');
+npx codeceptjs run --plugin myPlugin
+npx codeceptjs run --plugin myPlugin,allure
 ```
 
-### Container
-
-CodeceptJS has a dependency injection container with Helpers and Support objects.
-They can be retrieved from the container:
-
-```js
-import { container } from 'codeceptjs';
-
-// get object with all helpers
-let helpers = container.helpers();
-
-// get helper by name
-let WebDriver = container.helpers('WebDriver');
-
-// get support objects
-let support = container.support();
+### Example: run code for a tagged group of tests
 
-// get support object by name
-let UserPage = container.support('UserPage');
-
-// get all registered plugins
-let plugins = container.plugins();
-```
-
-New objects can also be added to container in runtime:
+[Tag](/test-structure#tags) the tests you want to target, then check the tag on `event.test.before`:
 
 ```js
-import { container } from 'codeceptjs';
-import UserPage from './pages/user.js';
-
-container.append({
-  helpers: { // add helper
-    MyHelper: new MyHelper({ config1: 'val1' });
-  },
-  support: { // add page object
-    UserPage,
-  }
-})
-```
+import { event, recorder } from 'codeceptjs'
 
-Container also contains current Mocha instance:
+export default function () {
+  event.dispatcher.on(event.test.before, test => {
+    if (!test.tags.includes('@populate')) return
 
-```js
-let mocha = container.mocha();
+    recorder.add('populate database', async () => {
+      // seed data for this test
+    })
+  })
+}
 ```
 
-### Config
+### Example: run async setup before all tests
 
-CodeceptJS config can be accessed from `import { config } from 'codeceptjs'` then `config.get()`:
+`event.all.before` can fire before the recorder chain is running, so start it first:
 
 ```js
-import { config } from 'codeceptjs';
-
-if (config.get().myKey == 'value') {
-  // run hook
+import { event, recorder } from 'codeceptjs'
+
+export default function () {
+  event.dispatcher.on(event.all.before, () => {
+    recorder.startUnlessRunning()
+    recorder.add('warm up cache', async () => {
+      // your async setup
+    })
+  })
 }
 ```
 
+Wrapping bootstrap logic in a plugin like this lets you share it across projects and combine several setup scripts.
 
-## Custom Runner
+## Custom Helpers
 
-> 📺 [Watch this](https://www.youtube.com/watch?v=3eZtVL0Ad0A) material on YouTube
+To add new `I.*` actions — a higher-level step, a wrapper around a browser SDK, an assertion against your backend — write a helper class. Helpers can also be published as npm packages. See [Custom Helpers](/helpers).
 
-CodeceptJS can be imported and used in custom runners.
-To initialize Codecept you need to create Config and Container objects.
+## Bootstrap & Teardown
 
-```js
-import { codecept as Codecept } from 'codeceptjs';
-
-const config = { helpers: { WebDriver: { browser: 'chrome', url: 'http://localhost' } } };
-const opts = { steps: true };
-
-const codecept = new Codecept(config, options);
-codecept.init(testRoot);
-
-// run tests
-try {
-  await codecept.bootstrap();
-  codecept.loadTests('*_test.js');
-  await codecept.run(test);
-} catch (err) {
-  printError(err);
-  process.exitCode = 1;
-} finally {
-  await codecept.teardown();
-}
+For setup and teardown that needs no packaging — start a server, create a database — use the `bootstrap` and `teardown` config hooks. In [parallel runs](/parallel), `bootstrapAll` / `teardownAll` run once in the parent process. See [Bootstrap & Teardown](/bootstrap).
 
+---
 
-```
-
-In this way Codecept runner class can be extended.
-
+**See also:** [Architecture](/architecture) · [Plugins reference](/plugins) · [Custom Helpers](/helpers) · [Bootstrap & Teardown](/bootstrap)

package/docs/installation.md

@@ -5,79 +5,134 @@ title: Installation
 
 # Installation
 
-## QuickStart Via Installer
+For the quickest start (CodeceptJS + Playwright) follow the [Quickstart](/quickstart). This page covers every browser, mobile, and API helper and what each one needs installed.
 
-Creating a new project via [`create-codeceptjs` installer](https://github.com/codeceptjs/create-codeceptjs) is the simplest way to start
+## Set up a project
 
-Install CodeceptJS + Playwright into current directory
-
-```
-npx create-codeceptjs .
+```sh
+npm init -y                  # if you don't have a package.json yet
+npm i codeceptjs --save-dev
 ```
 
-Install CodeceptJS + Puppeteer into current directory
+Install one of the helpers below, then scaffold the config and a sample test:
 
-```
-npx create-codeceptjs . --puppeteer
+```sh
+npx codeceptjs init
 ```
 
-Install CodeceptJS + webdriverio into current directory
+`init` runs a short wizard, writes `codecept.conf.js` and a sample test, and installs the helper's driver package if it's missing. The [Quickstart](/quickstart) walks through the questions.
 
-```
-npx create-codeceptjs . --webdriverio
-```
+## Playwright
 
-Install CodeceptJS + webdriverio into `e2e-tests` directory:
+Fast, modern browser automation — the recommended helper for web testing.
 
-```
-npx create-codeceptjs e2e-tests --webdriverio
+```sh
+npm i playwright --save-dev
+npx playwright install --with-deps
 ```
 
-If you plan to use CodeceptJS for **API testing** only proceed to standard installation
+`playwright install` downloads the browser binaries; `--with-deps` also installs the Linux system libraries they need (run it with `sudo` if your user can't install packages).
 
-## Standard Installation
+Set `browser` in the helper config to one of:
 
-Open a directory where you want to install CodeceptJS tests.
-If it is an empty directory - create a new NPM package with
+- `chromium` — default
+- `firefox`
+- `webkit` — the open-source Safari engine
+- `electron` — test an Electron app (set `electron.executablePath`)
 
-```
-npm init -y
+To drive branded Chrome or Edge instead of bundled Chromium, install that channel — `npx playwright install chrome` (or `msedge`) — and set `channel` in the config. See the [Playwright helper](/playwright).
+
+## Puppeteer
+
+Chrome/Chromium automation over the DevTools protocol.
+
+```sh
+npm i puppeteer --save-dev
 ```
 
-Install CodeceptJS with NPM:
+Puppeteer downloads a matching Chromium when it installs — nothing else to set up. To drive an existing Chrome instead, set `chrome.executablePath` in the helper config (or install `puppeteer-core` and point it at your browser). See the [Puppeteer helper](/puppeteer).
+
+## WebDriver
+
+W3C WebDriver — runs Chrome, Firefox, Edge, Safari, and remote or cloud grids.
 
 ```sh
-npx codeceptjs init
+npm i webdriverio --save-dev
 ```
 
-After choosing default helper (Playwright, Puppeteer, WebDriver, etc) a corresponding package should be installed automatically.
+WebDriver talks to a Selenium server (or a cloud grid). Pick one:
 
-> If you face issues installing additional packages while running `npx codeceptjs init` command, install required packages manually using npm
+- **[`selenium-standalone`](https://www.npmjs.com/package/selenium-standalone)** — one npm package that installs and runs Selenium with ChromeDriver and GeckoDriver:
 
-Unless you are using WebDriver - CodeceptJS is ready to go!
-For WebDriver installation Selenium Server is required 👇
+  ```sh
+  npm i selenium-standalone --save-dev
+  npx selenium-standalone install
+  npx selenium-standalone start
+  ```
 
-## ESM Support
+- **[Docker](https://github.com/SeleniumHQ/docker-selenium)** — a headless Selenium + browser container:
 
-CodeceptJS v4.x supports ECMAScript Modules (ESM) format. To use ESM:
+  ```sh
+  docker run --net=host --shm-size=2g selenium/standalone-chrome
+  # or selenium/standalone-firefox
+  ```
 
-1. Add `"type": "module"` to your `package.json`
-2. Update import syntax in configuration files to use ESM format
+- **A cloud grid** — Sauce Labs, BrowserStack, LambdaTest, and so on. Set the grid's `host`, `port`, `user`, and `key` (or `protocol` / `path`) in the helper config.
 
-For detailed migration instructions and important behavioral changes, see the **[3.x → 4.x Migration Guide](migration-4.md)**.
+Set `browser` (`chrome`, `firefox`, `MicrosoftEdge`, `safari`) and the server `host` / `port` in `codecept.conf.js` — see the [WebDriver helper](/webdriver). For running this on CI, see [Continuous Integration](/continuous-integration).
 
-## WebDriver
+## Appium (mobile)
+
+Native iOS and Android testing. Appium speaks the WebDriver protocol, so CodeceptJS drives it through `webdriverio`:
+
+```sh
+npm i webdriverio --save-dev
+npm i -g appium
+```
 
-WebDriver based helpers like WebDriver will require [Selenium Server](https://codecept.io/helpers/WebDriver/#selenium-installation) installed. They will also require ChromeDriver or GeckoDriver to run corresponding browsers.
+Install the platform driver(s) and start the server:
 
-We recommend to install them manually or use NPM packages:
+```sh
+appium driver install uiautomator2   # Android
+appium driver install xcuitest       # iOS
+appium
+```
 
-[Selenium Standalone](https://www.npmjs.com/package/selenium-standalone) to install and run Selenium, ChromeDriver, Firefox Driver with one package.
+You'll also need the Android SDK and an emulator or device, or Xcode and a simulator or device (or a device-cloud account). Set `platformName`, `deviceName`, and `app` in the helper config — see [Mobile Testing](/mobile).
 
-Alternatively, you can execute headless Selenium in [Docker](https://github.com/SeleniumHQ/docker-selenium) for headless browser testing.
+## API testing
 
-Launch Selenium with Chrome browser inside a Docker container:
+REST and GraphQL tests need no browser — the helpers are built in (they use `axios`, already a dependency):
 
 ```sh
-docker run --net=host selenium/standalone-chrome
+npm i codeceptjs --save-dev
 ```
+
+Choose `REST` or `GraphQL` when `init` asks, set `endpoint` in the config, and add the `JSONResponse` helper if you want response assertions. See [Testing APIs](/api).
+
+## ESM
+
+CodeceptJS 4.x uses ECMAScript Modules. A project created by `init` is set up for it; an existing project needs `"type": "module"` in `package.json` and `import` syntax in the config and tests. Coming from 3.x — see the [Migration Guide](/migration-4).
+
+## TypeScript
+
+`npx codeceptjs init` scaffolds a TypeScript project when you answer **Yes** to "Do you plan to write tests in TypeScript?" — it writes `codecept.conf.ts` and `*_test.ts` files.
+
+The config file (`codecept.conf.ts`) and helpers are transpiled automatically. Test files need a loader; install [`tsx`](https://tsx.is) and add it to `require`:
+
+```sh
+npm i tsx --save-dev
+```
+
+```ts
+// codecept.conf.ts
+export const config = {
+  tests: './**/*_test.ts',
+  require: ['tsx/cjs'],   // loads the *_test.ts files
+  helpers: {
+    Playwright: { url: 'http://localhost', browser: 'chromium' },
+  },
+}
+```
+
+Run tests as usual with `npx codeceptjs run`. For promise-based typings, types for page objects and custom helpers, and custom locator types, see the [TypeScript guide](/typescript).