codeceptjs 2.6.1 → 2.6.2

package/docs/helpers/MockRequest.md

@@ -1,45 +1,166 @@
 ---
 permalink: /helpers/MockRequest
-editLink: false
 sidebar: auto
 title: MockRequest
 ---
 
+# MockRequest
+
+
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
 ## MockRequest
 
-**Extends Helper**
-
 This helper allows to **mock requests while running tests in Puppeteer or WebDriver**.
 For instance, you can block calls to 3rd-party services like Google Analytics, CDNs.
 Another way of using is to emulate requests from server by passing prepared data.
 
-### Installations
+MockRequest helper works in these [modes][1]:
 
-Requires [Polly.js][1] library by Netflix installed
+-   passthrough (default) - mock prefefined HTTP requests
+-   record - record all requests into a file
+-   replay - replay all recorded requests from a file
+
+Combining record/replay modes allows testing websites with large datasets. 
+
+To use in passthrough mode set rules to mock requests and they will be automatically intercepted and replaced:
+
+```js
+// default mode
+I.mockRequest('GET', '/api/users', '[]');
+```
+
+In record-replay mode start mocking to make HTTP requests recorded/replayed, and stop when you don't need to block requests anymore:
+
+```js
+// record or replay all XHR for /users page
+I.startMocking();
+I.amOnPage('/users');
+I.stopMocking();
+```
+
+### Installations
 
-    npm i @pollyjs/core @pollyjs/adapter-puppeteer --save-dev
+    npm i @codeceptjs/mock-request --save-dev
 
 Requires Puppeteer helper or WebDriver helper enabled
 
 ### Configuration
 
-Just enable helper in config file:
+#### With Puppeteer
+
+Enable helper in config file:
 
 ```js
 helpers: {
    Puppeteer: {
      // regular Puppeteer config here
    },
-   MockRequest: {}
+   MockRequestHelper: {
+     require: '@codeceptjs/mock-request',
+   }
 }
 ```
 
-> Partially works with WebDriver helper
-
 [Polly config options][2] can be passed as well:
 
+```js
+// sample options
+helpers: {
+  MockRequestHelper: {
+     require: '@codeceptjs/mock-request',
+     mode: record,
+     recordIfMissing: true,
+     recordFailedRequests: false,
+     expiresIn: null,
+     persisterOptions: {
+       keepUnusedRequests: false
+       fs: {
+         recordingsDir: './data/requests',
+       },
+    },
+  }
+}
+```
+
+* * *
+
+**TROUBLESHOOTING**: Puppeteer does not mock requests in headless mode: 
+
+Problem: request mocking does not work and in debug mode you see this in output:
+
+    Access to fetch at {url} from origin {url} has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
+
+Solution: update Puppeteer config to include `--disable-web-security` arguments:
+
+```js
+ Puppeteer: {
+   show: false,
+   chrome: {
+     args: [
+       '--disable-web-security',
+     ],
+   },
+ },
+```
+
+* * *
+
+#### With WebDriver
+
+This helper partially works with WebDriver. It can intercept and mock requests **only on already loaded page**.
+
+```js
+helpers: {
+   WebDriver: {
+     // regular WebDriver config here
+   },
+   MockRequestHelper: {
+     require: '@codeceptjs/mock-request',
+   }
+}
+```
+
+> Record/Replay mode is not tested in WebDriver but technically can work with [REST Persister][3]
+
+## Usage
+
+### 👻 Mock Requests
+
+To intercept API requests and mock them use following API
+
+-   [startMocking()][4] - to enable request interception
+-   [mockRequest()][5] - to define mock in a simple way
+-   [mockServer()][6] - to use PollyJS server API to define complex mocks
+-   [stopMocking()][7] - to stop intercepting requests and disable mocks.
+
+Calling `mockRequest` or `mockServer` will start mocking, if it was not enabled yet.
+
+```js
+I.startMocking(); // optionally
+I.mockRequest('/google-analytics/*path', 200);
+// return an empty successful response 
+I.mockRequest('GET', '/api/users', 200);
+// mock users api
+I.mockServer(server => {
+  server.get('https://server.com/api/users*').
+    intercept((req, res) => { res.status(200).json(users);
+  });
+});
+I.click('Get users);
+I.stopMocking();
+```
+
+### 📼 Record & Replay
+
+> At this moment works only with Puppeteer
+
+Record & Replay mode allows you to record all xhr & fetch requests and save them to file.
+On next runs those requests can be replayed. 
+By default, it stores all passed requests, but this behavior can be customized with `I.mockServer`
+
+Set mode via enironment variable, `replay` mode by default:
+
 ```js
 // enable replay mode
 helpers: {
@@ -47,39 +168,52 @@ helpers: {
    // regular Puppeteer config here
  },
  MockRequest: {
-    mode: 'replay',
+    require: '@codeceptjs/mock-request',
+    mode: process.env.MOCK_MODE || 'replay',
  },
 }
 ```
 
-### Usage
+Interactions between `I.startMocking()` and `I.stopMocking()` will be recorded and saved to `data/requests` directory.
 
-Use `I.mockRequest` to intercept and mock requests.
+```js
+I.startMocking() // record requests under 'Test' name
+I.startMocking('users') // record requests under 'users' name
+```
 
-### Parameters
+Use `I.mockServer()` to customize which requests should be recorded and under which name:
 
--   `config`  
+```js
+I.startMocking();
+I.mockServer((server) => {
+  // mock request only from ap1.com and api2.com and
+  // store recording into two different files
+  server.any('https://api1.com/*').passthrough(false).recordingName('api1');
+  server.any('https://api2.com/*').passthrough(false).recordingName('api2');
+});
+```
 
-### _checkAndStartMocking
+To stop request recording/replaying use `I.stopMocking()`.
 
-Starts mocking if it's not started yet.
+🎥 To record HTTP interactions execute tests with MOCK_MODE environment variable set as "record":
 
-### _connectPuppeteer
+    MOCK_MODE=record npx codeceptjs run --debug
 
-Creates a polly instance by registering puppeteer adapter with the instance
+📼 To replay them launch tests without environment variable:
 
-#### Parameters
+    npx codeceptjs run --debug
 
--   `title` **any** 
+### Parameters
 
-### _connectWebDriver
+-   `config`  
 
-Creates polly object in the browser window context using xhr and fetch adapters,
-after loading PollyJs and adapter scripts.
+### flushMocking
 
-#### Parameters
+Waits for all requests handled by MockRequests to be resolved:
 
--   `title` **any** 
+```js
+I.flushMocking();
+```
 
 ### mockRequest
 
@@ -100,33 +234,142 @@ I.mockRequest('GET', ['/secrets', '/v2/secrets'], 403);
 
 #### Parameters
 
--   `method` **[string][3]** request method. Can be `GET`, `POST`, `PUT`, etc or `ANY`.
--   `oneOrMoreUrls` **([string][3] | [Array][4]&lt;[string][3]>)** url(s) to mock. Can be exact URL, a pattern, or an array of URLs.
--   `dataOrStatusCode` **([number][5] | [string][3] | [object][6])** status code when number provided. A response body otherwise
--   `additionalData` **([string][3] | [object][6])** response body when a status code is set by previous parameter. 
+-   `method` **[string][8]** request method. Can be `GET`, `POST`, `PUT`, etc or `ANY`.
+-   `oneOrMoreUrls` **([string][8] \| [Array][9]&lt;[string][8]>)** url(s) to mock. Can be exact URL, a pattern, or an array of URLs.
+-   `dataOrStatusCode` **([number][10] \| [string][8] \| [object][11])** status code when number provided. A response body otherwise
+-   `additionalData` **([string][8] \| [object][11])** response body when a status code is set by previous parameter. (optional, default `null`)
+
+### mockServer
+
+Use PollyJS [Server Routes API][12] to declare mocks via callback function:
+
+```js
+// basic usage
+server.get('/api/v2/users').intercept((req, res) => {
+  res.sendStatus(200).json({ users });
+});
+
+// passthrough requests to "/api/v2"
+server.get('/api/v1').passthrough();
+```
+
+In record replay mode you can define which routes should be recorded and where to store them:
+
+```js
+I.startMocking('mock');
+I.mockServer((server) => {
+
+  // record requests from cdn1.com and save them to data/recording/xml
+  server.any('https://cdn1.com/*').passthrough(false).recordingName('xml');
+  
+  // record requests from cdn2.com and save them to data/recording/svg
+  server.any('https://cdn2.com/*').passthrough(false).recordingName('svg');
+
+  // record requests from /api and save them to data/recording/mock (default)
+  server.any('/api/*').passthrough(false);
+});
+```
+
+#### Parameters
+
+-   `configFn`  
+
+### passthroughMocking
+
+Forces passthrough mode for mocking.
+Requires mocking to be started.
+
+```js
+I.passthroughMocking();
+```
+
+### recordMocking
+
+Forces record mode for mocking.
+Requires mocking to be started.
+
+```js
+I.recordMocking();
+```
+
+### replayMocking
+
+Forces replay mode for mocking.
+Requires mocking to be started.
+
+```js
+I.replayMocking();
+```
 
 ### startMocking
 
 Starts mocking of http requests.
-Used by mockRequest method to automatically start
-mocking requests.
+In record mode starts recording of all requests.
+In replay mode blocks all requests and replaces them with saved.
+
+If inside one test you plan to record/replay requests in several places, provide [recording name][13] as the parameter.
+
+```js
+// start mocking requests for a test
+I.startMocking(); 
+
+// start mocking requests for main page
+I.startMocking('main-page');
+// do actions
+I.stopMocking();
+I.startMocking('login-page');
+```
+
+To update [PollyJS configuration][14] use secon argument:
+
+```js
+// change mode
+I.startMocking('comments', { mode: 'replay' });
+
+// override config
+I.startMocking('users-loaded', {
+   recordFailedRequests: true
+})
+```
 
 #### Parameters
 
--   `title` **any**  
+-   `title` **any**  (optional, default `'Test'`)
+-   `config`   (optional, default `{}`)
 
 ### stopMocking
 
 Stops mocking requests.
+Must be called to save recorded requests into faile.
 
-[1]: https://netflix.github.io/pollyjs/#/
+```js
+I.stopMocking();
+```
+
+[1]: https://netflix.github.io/pollyjs/#/configuration?id=mode
 
 [2]: https://netflix.github.io/pollyjs/#/configuration?id=configuration
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[3]: https://netflix.github.io/pollyjs/#/examples?id=rest-persister
+
+[4]: #startMocking
+
+[5]: #mockRequest
+
+[6]: #mockServer
+
+[7]: #stopMocking
+
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[12]: https://netflix.github.io/pollyjs/#/server/overview
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[13]: https://netflix.github.io/pollyjs/#/api?id=recordingname
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[14]: https://netflix.github.io/pollyjs/#/configuration

package/docs/helpers/Playwright.md

@@ -38,7 +38,7 @@ This helper should be configured in codecept.json or codecept.conf.js
 -   `keepBrowserState`:  - keep browser state between tests when `restart` is set to false.
 -   `keepCookies`:  - keep cookies between tests when `restart` is set to false.
 -   `waitForAction`: (optional) how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
--   `waitForNavigation`: . When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Playwright API][2]. Array values are accepted as well.
+-   `waitForNavigation`: . When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. Choose one of those options is possible. See [Playwright API][2].
 -   `pressKeyDelay`: . Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
 -   `getPageTimeout`  config option to set maximum navigation time in milliseconds.
 -   `waitForTimeout`: (optional) default wait* timeout in ms. Default: 1000.
@@ -63,7 +63,7 @@ This helper should be configured in codecept.json or codecept.conf.js
 }
 ```
 
-#### Example #2: Wait for DOMContentLoaded event and 0 network connections
+#### Example #2: Wait for DOMContentLoaded event
 
 ```js
 {
@@ -71,7 +71,7 @@ This helper should be configured in codecept.json or codecept.conf.js
      Playwright : {
        url: "http://localhost",
        restart: false,
-       waitForNavigation: [ "domcontentloaded", "networkidle0" ],
+       waitForNavigation: "domcontentloaded",
        waitForAction: 500
      }
    }
@@ -890,6 +890,24 @@ let email = await I.grabValueFrom('input[name=email]');
 
 Returns **[Promise][9]<[string][7]>** attribute value
 
+### handleDownloads
+
+Handles a file download.Aa file name is required to save the file on disk.
+Files are saved to "output" directory.
+
+Should be used with [FileSystem helper][11] to check that file were downloaded correctly.
+
+```js
+I.handleDownloads('downloads/avatar.jpg');
+I.click('Download Avatar');
+I.amInPath('output/downloads');
+I.waitForFile('downloads/avatar.jpg', 5);
+```
+
+#### Parameters
+
+-   `fileName` **[string][7]?** set filename for downloaded file 
+
 ### haveRequestHeaders
 
 Set headers for all next requests
@@ -928,7 +946,7 @@ Open new tab and switch to it
 I.openNewTab();
 ```
 
-You can pass in [page options][11] to emulate device on this page
+You can pass in [page options][12] to emulate device on this page
 
 ```js
 // enable mobile
@@ -943,7 +961,7 @@ I.openNewTab({ isMobile: true });
 
 Presses a key in the browser (on a focused element).
 
-_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][12].
+_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][13].
 
 ```js
 I.pressKey('Backspace');
@@ -1002,13 +1020,13 @@ Some of the supported key names are:
 
 #### Parameters
 
--   `key` **([string][7] | [Array][10]<[string][7]>)** key or array of keys to press._Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Playwright#1313][13]).
+-   `key` **([string][7] | [Array][10]<[string][7]>)** key or array of keys to press._Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Playwright#1313][14]).
 
 ### pressKeyDown
 
 Presses a key in the browser and leaves it in a down state.
 
-To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][14]).
+To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][15]).
 
 ```js
 I.pressKeyDown('Control');
@@ -1024,7 +1042,7 @@ I.pressKeyUp('Control');
 
 Releases a key in the browser which was previously set to a down state.
 
-To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][14]).
+To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][15]).
 
 ```js
 I.pressKeyDown('Control');
@@ -1092,7 +1110,7 @@ I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scro
 #### Parameters
 
 -   `fileName` **[string][7]** file name to save.
--   `fullPage` **[boolean][15]** (optional, `false` by default) flag to enable fullscreen screenshot mode. 
+-   `fullPage` **[boolean][16]** (optional, `false` by default) flag to enable fullscreen screenshot mode. 
 
 ### scrollPageToBottom
 
@@ -1541,7 +1559,7 @@ I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and
 
 #### Parameters
 
--   `fn` **([string][7] | [function][16])** to be executed in browser context.
+-   `fn` **([string][7] | [function][17])** to be executed in browser context.
 -   `argsOrSec` **([Array][10]<any> | [number][8])?** (optional, `1` by default) arguments for function or seconds. 
 -   `sec` **[number][8]?** (optional, `1` by default) time in seconds to wait 
 
@@ -1563,7 +1581,7 @@ I.waitForInvisible('#popup');
 
 Waits for navigation to finish. By default takes configured `waitForNavigation` option.
 
-See [Pupeteer's reference][2]
+See [Pupeteer's reference][18]
 
 #### Parameters
 
@@ -1580,7 +1598,7 @@ I.waitForRequest(request => request.url() === 'http://example.com' && request.me
 
 #### Parameters
 
--   `urlOrPredicate` **([string][7] | [function][16])** 
+-   `urlOrPredicate` **([string][7] | [function][17])** 
 -   `sec` **[number][8]?** seconds to wait 
 
 ### waitForResponse
@@ -1594,7 +1612,7 @@ I.waitForResponse(request => request.url() === 'http://example.com' && request.m
 
 #### Parameters
 
--   `urlOrPredicate` **([string][7] | [function][16])** 
+-   `urlOrPredicate` **([string][7] | [function][17])** 
 -   `sec` **[number][8]?** number of seconds to wait 
 
 ### waitForText
@@ -1640,7 +1658,7 @@ I.waitForVisible('#popup');
 #### Parameters
 
 -   `locator` **([string][7] | [object][5])** element located by CSS|XPath|strict locator.
--   `sec` **[number][8]** (optional, `1` by default) time in seconds to waitThis method accepts [React selectors][17]. 
+-   `sec` **[number][8]** (optional, `1` by default) time in seconds to waitThis method accepts [React selectors][19]. 
 
 ### waitInUrl
 
@@ -1694,7 +1712,7 @@ I.waitUntil(() => window.requests == 0, 5);
 
 #### Parameters
 
--   `fn` **([function][16] | [string][7])** function which is executed in browser context.
+-   `fn` **([function][17] | [string][7])** function which is executed in browser context.
 -   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
 -   `timeoutMsg` **[string][7]** message to show in case of timeout fail. 
 -   `interval` **[number][8]?**  
@@ -1715,7 +1733,7 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 
 [1]: https://github.com/microsoft/playwright
 
-[2]: https://github.com/GoogleChrome/Playwright/blob/master/docs/api.md#pagewaitfornavigationoptions
+[2]: https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitfornavigationoptions
 
 [3]: https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
 
@@ -1733,16 +1751,20 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 
 [10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[11]: https://github.com/microsoft/playwright/blob/v0.12.1/docs/api.md#browsernewpageoptions
+[11]: https://codecept.io/helpers/FileSystem
+
+[12]: https://github.com/microsoft/playwright/blob/v0.12.1/docs/api.md#browsernewpageoptions
+
+[13]: #fillfield
 
-[12]: #fillfield
+[14]: https://github.com/GoogleChrome/Playwright/issues/1313
 
-[13]: https://github.com/GoogleChrome/Playwright/issues/1313
+[15]: #click
 
-[14]: #click
+[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[18]: https://github.com/GoogleChrome/Playwright/blob/master/docs/api.md#pagewaitfornavigationoptions
 
-[17]: https://codecept.io/react
+[19]: https://codecept.io/react

package/docs/helpers/Puppeteer.md

@@ -696,6 +696,42 @@ I.fillField({css: 'form#login input[name=username]'}, 'John');
 This action supports [React locators](https://codecept.io/react#locators)
 
 
+### forceClick
+
+Perform an emulated click on a link or a button, given by a locator.
+Unlike normal click instead of sending native event, emulates a click with JavaScript.
+This works on hidden, animated or inactive elements as well.
+
+If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+For images, the "alt" attribute and inner text of any parent links are searched.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+// simple link
+I.forceClick('Logout');
+// button of form
+I.forceClick('Submit');
+// CSS button
+I.forceClick('#form input[type=submit]');
+// XPath
+I.forceClick('//form/*[@type=submit]');
+// link in context
+I.forceClick('Logout', '#nav');
+// using strict locator
+I.forceClick({css: 'nav a.login'});
+```
+
+#### Parameters
+
+-   `locator` **([string][8] | [object][6])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+-   `context` **([string][8]? | [object][6])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
+
 ### grabAttributeFrom
 
 Retrieves an attribute from an element located by CSS or XPath and returns it to test.

package/docs/helpers/WebDriver.md

@@ -391,12 +391,14 @@ this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').
 Find a clickable element by providing human readable text:
 
 ```js
-this.helpers['WebDriver']._locateClickable('Next page').then // ...
+const els = await this.helpers.WebDriver._locateClickable('Next page');
+const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages');
 ```
 
 #### Parameters
 
 -   `locator` **([string][19] | [object][18])** element located by CSS|XPath|strict locator.
+-   `context`  
 
 ### _locateFields
 
@@ -873,6 +875,42 @@ I.fillField({css: 'form#login input[name=username]'}, 'John');
 This action supports [React locators](https://codecept.io/react#locators)
 
 
+### forceClick
+
+Perform an emulated click on a link or a button, given by a locator.
+Unlike normal click instead of sending native event, emulates a click with JavaScript.
+This works on hidden, animated or inactive elements as well.
+
+If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+For images, the "alt" attribute and inner text of any parent links are searched.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+// simple link
+I.forceClick('Logout');
+// button of form
+I.forceClick('Submit');
+// CSS button
+I.forceClick('#form input[type=submit]');
+// XPath
+I.forceClick('//form/*[@type=submit]');
+// link in context
+I.forceClick('Logout', '#nav');
+// using strict locator
+I.forceClick({css: 'nav a.login'});
+```
+
+#### Parameters
+
+-   `locator` **([string][19] | [object][18])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+-   `context` **([string][19]? | [object][18])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+
+
+This action supports [React locators](https://codecept.io/react#locators)
+ 
+
 ### grabAllWindowHandles
 
 Get all Window Handles.