codeceptjs 3.2.3 → 3.3.0-beta.1

package/docs/helpers/Puppeteer.md

@@ -15,7 +15,15 @@ Uses [Google Chrome's Puppeteer][1] library to run tests inside headless Chrome.
 Browser control is executed via DevTools Protocol (instead of Selenium).
 This helper works with a browser out of the box with no additional tools required to install.
 
-Requires `puppeteer` package to be installed.
+Requires `puppeteer` or `puppeteer-core` package to be installed.
+
+    npm i puppeteer --save
+
+or
+
+    npm i puppeteer-core --save
+
+Using `puppeteer-core` package, will prevent the download of browser binaries and allow connecting to an existing browser installation or for connecting to a remote one.
 
 > Experimental Firefox support [can be activated][2].
 

package/docs/helpers/REST.md

@@ -71,6 +71,27 @@ Generates url based on format sent (takes endpoint + url if latter lacks 'http')
 
 -   `url` **any** 
 
+### amBearerAuthenticated
+
+Adds a header for Bearer authentication
+
+```js
+// we use secret function to hide token from logs
+I.amBearerAuthenticated(secret('heregoestoken'))
+```
+
+#### Parameters
+
+-   `accessToken` **[string][3]** Bearer access token
+
+### haveRequestHeaders
+
+Sets request headers for all requests of this test
+
+#### Parameters
+
+-   `headers` **[object][4]** headers list
+
 ### sendDeleteRequest
 
 Sends DELETE request to API.
@@ -82,7 +103,7 @@ I.sendDeleteRequest('/api/users/1');
 #### Parameters
 
 -   `url` **any** 
--   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -97,7 +118,7 @@ I.sendGetRequest('/api/users.json');
 #### Parameters
 
 -   `url` **any** 
--   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -114,9 +135,9 @@ I.sendPatchRequest('/api/users.json', secret({ "email": "user@user.com" }));
 
 #### Parameters
 
--   `url` **[string][4]** 
+-   `url` **[string][3]** 
 -   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -135,7 +156,7 @@ I.sendPostRequest('/api/users.json', secret({ "email": "user@user.com" }));
 
 -   `url` **any** 
 -   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -152,9 +173,9 @@ I.sendPutRequest('/api/users.json', secret({ "email": "user@user.com" }));
 
 #### Parameters
 
--   `url` **[string][4]** 
+-   `url` **[string][3]** 
 -   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -174,8 +195,8 @@ I.setRequestTimeout(10000); // In milliseconds
 
 [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
 [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

package/docs/installation.md

@@ -33,6 +33,8 @@ Install CodeceptJS + webdriverio into `e2e-tests` directory:
 npx create-codeceptjs e2e-tests --webdriverio
 ```
 
+If you plan to use CodeceptJS for **API testing** only proceed to standard installation
+
 ## Standard Installation
 
 Open a directory where you want to install CodeceptJS tests.

package/docs/internal-api.md

@@ -0,0 +1,265 @@
+---
+permalink: /internal-api
+title: Internal API
+---
+
+## Concepts
+
+In this guide we will overview the internal API of CodeceptJS.
+This knowledge is required for customization, writing plugins, etc.
+
+CodeceptJS provides an API which can be loaded via `require('codeceptjs')` when CodeceptJS is installed locally. Otherwise, you can load codeceptjs API via global `codeceptjs` object:
+
+```js
+// via module
+const { recorder, event, output } = require('codeceptjs');
+// or using global object
+const { recorder, event, output } = codeceptjs;
+```
+
+These internal objects are available:
+
+* [`codecept`](https://github.com/Codeception/CodeceptJS/blob/master/lib/codecept.js): test runner class
+* [`config`](https://github.com/Codeception/CodeceptJS/blob/master/lib/config.js): current codecept config
+* [`event`](https://github.com/Codeception/CodeceptJS/blob/master/lib/event.js): event listener
+* [`recorder`](https://github.com/Codeception/CodeceptJS/blob/master/lib/recorder.js): global promise chain
+* [`output`](https://github.com/Codeception/CodeceptJS/blob/master/lib/output.js): internal printer
+* [`container`](https://github.com/Codeception/CodeceptJS/blob/master/lib/container.js): dependency injection container for tests, includes current helpers and support objects
+* [`helper`](https://github.com/Codeception/CodeceptJS/blob/master/lib/helper.js): basic helper class
+* [`actor`](https://github.com/Codeception/CodeceptJS/blob/master/lib/actor.js): basic actor (I) class
+
+[API reference](https://github.com/Codeception/CodeceptJS/tree/master/docs/api) is available on GitHub.
+Also please check the source code of corresponding modules.
+
+### Container
+
+CodeceptJS has a dependency injection container with helpers and support objects.
+They can be retrieved from the container:
+
+```js
+const { container } = require('codeceptjs');
+
+// get object with all helpers
+const helpers = container.helpers();
+
+// get helper by name
+const { WebDriver } = container.helpers();
+
+// get support objects
+const supportObjects = container.support();
+
+// get support object by name
+const { UserPage } = container.support();
+
+// get all registered plugins
+const plugins = container.plugins();
+```
+
+New objects can also be added to container in runtime:
+
+```js
+const { container } = require('codeceptjs');
+
+container.append({
+  helpers: { // add helper
+    MyHelper: new MyHelper({ config1: 'val1' });
+  },
+  support: { // add page object
+    UserPage: require('./pages/user');
+  }
+})
+```
+
+> Use this trick to define custom objects inside `boostrap` script
+
+The container also contains the current Mocha instance:
+
+```js
+const mocha = container.mocha();
+```
+
+### Event Listeners
+
+CodeceptJS provides a module with an [event dispatcher and set of predefined events](https://github.com/Codeception/CodeceptJS/blob/master/lib/event.js).
+
+It can be required from codeceptjs package if it is installed locally.
+
+```js
+const { event } = require('codeceptjs');
+
+module.exports = function() {
+
+  event.dispatcher.on(event.test.before, function (test) {
+
+    console.log('--- I am before test --');
+
+  });
+}
+```
+
+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.
+* `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.all.before` - before running tests
+* `event.all.after` - after running tests
+* `event.all.result` - when results are printed
+* `event.workers.before` - before spawning workers in parallel run
+* `event.workers.after` - after workers finished in parallel run
+
+
+> *sync* - means that event is fired in the moment of the action happening.
+ *async* - means that event is fired when an action is scheduled. Use `recorder` to schedule your actions.
+
+For further reference look for [currently available listeners](https://github.com/Codeception/CodeceptJS/tree/master/lib/listener) using the event system.
+
+
+### 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/Codeception/CodeceptJS/blob/master/lib/recorder.js) represents a global promises chain.
+
+Provide a function in the first parameter, a function must be async or must return a promise:
+
+```js
+const { event, recorder } = require('codeceptjs');
+
+module.exports = function() {
+
+  event.dispatcher.on(event.test.before, function (test) {
+
+    const request = require('request');
+
+    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();
+        }
+      });
+    }
+  });
+}
+```
+
+### Config
+
+CodeceptJS config can be accessed from `require('codeceptjs').config.get()`:
+
+```js
+const { config } = require('codeceptjs');
+
+// config object has access to all values of the current config file
+
+if (config.get().myKey == 'value') {
+  // run something
+}
+```
+
+
+### Output
+
+Output module provides four 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
+const output = require('codeceptjs').output;
+
+output.print('This is basic information');
+output.debug('This is debug information');
+output.log('This is verbose logging information');
+```
+
+#### Test Object
+
+The test events are providing a test object with following properties:
+
+* `title` title of the 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
+* `artifacts` list of files attached to this test. Screenshots, videos and other files can be saved here and shared accross different reporters
+* `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 is `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
+
+Whenever you execute tests with `--verbose` option you will see registered events and promises executed by a recorder.
+
+## Custom Runner
+
+You can run CodeceptJS tests from your script.
+
+```js
+const { codecept: Codecept } = require('codeceptjs');
+
+// define main config
+const config = { 
+  helpers: { 
+    WebDriver: { 
+      browser: 'chrome', 
+      url: 'http://localhost' 
+    }
+  }
+};
+
+const opts = { steps: true };
+
+// run CodeceptJS inside async function
+(async () => {
+  const codecept = new Codecept(config, options);
+  codecept.init(__dirname);
+
+  try {
+    await codecept.bootstrap();
+    codecept.loadTests('**_test.js');
+    // run tests
+    await codecept.run(test);
+  } catch (err) {
+    printError(err);
+    process.exitCode = 1;
+  } finally {
+    await codecept.teardown();
+  }    
+})();
+```
+
+> Also, you can run tests inside workers in a custom scripts. Please refer to the [parallel execution](/parallel) guide for more details.

package/docs/playwright.md

@@ -175,8 +175,10 @@ If you need to get element's value inside a test you can use `grab*` methods. Th
 ```js
 const assert = require('assert');
 Scenario('get value of current tasks', async ({ I }) => {
-  I.createTodo('do 1');
-  I.createTodo('do 2');
+  I.fillField('.todo', 'my first item');
+  I.pressKey('Enter')
+  I.fillField('.todo', 'my second item');
+  I.pressKey('Enter')
   let numTodos = await I.grabTextFrom('.todo-count strong');
   assert.equal(2, numTodos);
 });
@@ -188,17 +190,35 @@ In case some actions should be taken inside one element (a container or modal wi
 Please take a note that you can't use within inside another within in Playwright helper:
 
 ```js
-within('.todoapp', () => {
-  I.createTodo('my new item');
+await within('.todoapp', () => {
+  I.fillField('.todo', 'my new item');
+  I.pressKey('Enter')
   I.see('1 item left', '.todo-count');
   I.click('.todo-list input.toggle');
 });
 I.see('0 items left', '.todo-count');
 ```
 
-> [▶ Learn more about basic commands](/basics#writing-tests)
+### Each Element <Badge text="Since 3.3" type="warning"/>
 
-CodeceptJS allows you to implement custom actions like `I.createTodo` or use **PageObjects**. Learn how to improve your tests in [PageObjects](https://codecept.io/pageobjects/) guide.
+Usually, CodeceptJS performs an action on the first matched element. 
+In case you want to do an action on each element found, use the special function `eachElement` which comes from [eachElement](https://codecept.io/plugins/#eachelement) plugin. 
+
+`eachElement` function matches all elements by locator and performs a callback on each of those element. A callback function receives [ElementHandle instance](https://playwright.dev/docs/api/class-elementhandle) from Playwright API. `eachElement` may perform arbitrary actions on a page, so the first argument should by a description of the actions performed. This description will be used for logging purposes.
+
+Usage example
+
+```js
+await eachElement(
+  'tick all checkboxes', 
+  'input.custom-checkbox', 
+  async (el, index) => {
+    await el.check();
+  });
+);
+```
+
+> ℹ Learn more about [eachElement plugin](/plugins/#eachelement)
 
 ## Multi Session Testing
 
@@ -307,19 +327,40 @@ Scenario('website looks nice on iPhone', () => {
 });
 ```
 
-## Configuring CI
+## API Requests
 
-### GitHub Actions
+CodeceptJS has [REST](/helpers/REST) and [GraphQL]((/helpers/GraphQL)) helpers to perform requests to external APIs. This may be helpful to implement [data management](https://codecept.io/data/) strategy. 
 
-Playwright can be added to GitHub Actions using [official action](https://github.com/microsoft/playwright-github-action). Use it before starting CodeceptJS tests to install all dependencies. It is important to run tests in headless mode ([otherwise you will need to enable xvfb to emulate desktop](https://github.com/microsoft/playwright-github-action#run-in-headful-mode)).
+However, Playwright since 1.18 has its own [API for making request](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get). It uses cookies from browser session to authenticate requests. So you can use it via [`makeApiRequest`](/helpers/Playwright#makeApiRequest) method:
 
-```yml
-# from workflows/tests.yml
-- uses: microsoft/playwright-github-action@v1
-- name: run CodeceptJS tests
-  run: npx codeceptjs run
+```js
+I.makeApiRequest('GET', '/users')
 ```
 
+It is also possible to test JSON responses by adding [`JSONResponse`](/helpers/JSONResponse) and connecting it to Playwright:
+
+```js
+// inside codecept.conf.js
+{
+  helpers: {
+    Playwright: {
+      // current config
+    },
+    JSONResponse: {
+      requestHelper: 'Playwright',
+    }
+  }
+}
+```
+This helper provides you methods for [API testing](/api). For instance, you can check for status code, data inclusion and structure:
+
+```js
+I.makeApiRequest('GET', '/users/1');
+I.seeResponseCodeIs(200);
+I.seeResponseContainsKeys(['user']);
+```
+This way you can do full fledged API testing via Playwright.
+
 ## Accessing Playwright API
 
 To get [Playwright API](https://playwright.dev/docs/api/class-playwright) inside a test use `I.usePlaywrightTo` method with a callback.
@@ -350,7 +391,6 @@ I.usePlaywrightTo('emulate offline mode', async (Playwright) => {
   // call a method of helper, await is required here
   await Playwright.click('Reload');
 });
-
 ```
 
 ## Mocking Network Requests <Badge text="Since 3.1" type="warning"/>
@@ -496,6 +536,7 @@ Open `index.html` in your browser to view the full interactive coverage report.
 ![](https://user-images.githubusercontent.com/16587779/131858993-87d1aafc-8ef1-4a82-867d-e64a13e36106.png)
 
 ![](https://user-images.githubusercontent.com/16587779/131859006-c6f17d18-c603-44a5-9d59-0670177276cf.png)
+
 ## Extending Helper
 
 To create custom `I.*` commands using Playwright API you need to create a custom helper.
@@ -538,3 +579,17 @@ async setPermissions() {
 > [▶ Learn more about BrowserContext](https://github.com/microsoft/playwright/blob/master/docs/src/api/class-browsercontext.md)
 
 > [▶ Learn more about Helpers](https://codecept.io/helpers/)
+
+
+## Configuring CI
+
+### GitHub Actions
+
+Playwright can be added to GitHub Actions using [official action](https://github.com/microsoft/playwright-github-action). Use it before starting CodeceptJS tests to install all dependencies. It is important to run tests in headless mode ([otherwise you will need to enable xvfb to emulate desktop](https://github.com/microsoft/playwright-github-action#run-in-headful-mode)).
+
+```yml
+# from workflows/tests.yml
+- uses: microsoft/playwright-github-action@v1
+- name: run CodeceptJS tests
+  run: npx codeceptjs run
+```