codeceptjs 2.4.3 → 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/Nightmare.md

@@ -876,15 +876,23 @@ I.selectOption('Which OS do you use?', ['Android', 'iOS']);
 
 ### setCookie
 
-Sets a cookie.
+Sets cookie(s).
+
+Can be a single cookie object or an array of cookies:
 
 ```js
 I.setCookie({name: 'auth', value: true});
+
+// as array
+I.setCookie([
+  {name: 'auth', value: true},
+  {name: 'agree', value: true}
+]);
 ```
 
 #### Parameters
 
--   `cookie` **[object][4]** a cookie object.Wrapper for `.cookies.set(cookie)`.
+-   `cookie` **([object][4] | [array][11])** a cookie object or array of cookie objects.Wrapper for `.cookies.set(cookie)`.
     [See more][14]
 
 ### triggerMouseEvent