codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

package/docs/helpers/MockRequest.md

@@ -0,0 +1,377 @@
+---
+permalink: /helpers/MockRequest
+sidebar: auto
+title: MockRequest
+---
+
+# MockRequest
+
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## MockRequest
+
+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.
+
+MockRequest helper works in these [modes][1]:
+
+*   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 @codeceptjs/mock-request --save-dev
+
+Requires Puppeteer helper or WebDriver helper enabled
+
+### Configuration
+
+#### With Puppeteer
+
+Enable helper in config file:
+
+```js
+helpers: {
+   Puppeteer: {
+     // regular Puppeteer config here
+   },
+   MockRequestHelper: {
+     require: '@codeceptjs/mock-request',
+   }
+}
+```
+
+[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: {
+ Puppeteer: {
+   // regular Puppeteer config here
+ },
+ MockRequest: {
+    require: '@codeceptjs/mock-request',
+    mode: process.env.MOCK_MODE || 'replay',
+ },
+}
+```
+
+Interactions between `I.startMocking()` and `I.stopMocking()` will be recorded and saved to `data/requests` directory.
+
+```js
+I.startMocking() // record requests under 'Test' name
+I.startMocking('users') // record requests under 'users' name
+```
+
+Use `I.mockServer()` to customize which requests should be recorded and under which name:
+
+```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');
+});
+```
+
+To stop request recording/replaying use `I.stopMocking()`.
+
+🎥 To record HTTP interactions execute tests with MOCK\_MODE environment variable set as "record":
+
+    MOCK_MODE=record npx codeceptjs run --debug
+
+📼 To replay them launch tests without environment variable:
+
+    npx codeceptjs run --debug
+
+### Parameters
+
+*   `config` &#x20;
+
+### flushMocking
+
+Waits for all requests handled by MockRequests to be resolved:
+
+```js
+I.flushMocking();
+```
+
+### mockRequest
+
+Mock response status
+
+```js
+I.mockRequest('GET', '/api/users', 200);
+I.mockRequest('ANY', '/secretsRoutes/*', 403);
+I.mockRequest('POST', '/secrets', { secrets: 'fakeSecrets' });
+I.mockRequest('GET', '/api/users/1', 404, 'User not found');
+```
+
+Multiple requests
+
+```js
+I.mockRequest('GET', ['/secrets', '/v2/secrets'], 403);
+```
+
+#### Parameters
+
+*   `method` **[string][8]** request method. Can be `GET`, `POST`, `PUT`, etc or `ANY`.
+*   `oneOrMoreUrls` **([string][8] | [Array][9]<[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
+I.mockServer((server) => {
+  // 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` &#x20;
+
+### 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.
+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**  (optional, default `'Test'`)
+*   `config`   (optional, default `{}`)
+
+### stopMocking
+
+Stops mocking requests.
+Must be called to save recorded requests into faile.
+
+```js
+I.stopMocking();
+```
+
+[1]: https://netflix.github.io/pollyjs/#/configuration?id=mode
+
+[2]: https://netflix.github.io/pollyjs/#/configuration?id=configuration
+
+[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
+
+[12]: https://netflix.github.io/pollyjs/#/server/overview
+
+[13]: https://netflix.github.io/pollyjs/#/api?id=recordingname
+
+[14]: https://netflix.github.io/pollyjs/#/configuration

package/docs/helpers/MockServer.md

@@ -0,0 +1,212 @@
+---
+permalink: /helpers/MockServer
+editLink: false
+sidebar: auto
+title: MockServer
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## MockServer
+
+MockServer
+
+The MockServer Helper in CodeceptJS empowers you to mock any server or service via HTTP or HTTPS, making it an excellent tool for simulating REST endpoints and other HTTP-based APIs.
+
+
+
+## Configuration
+
+This helper should be configured in codecept.conf.(js|ts)
+
+Type: [object][1]
+
+### Properties
+
+-   `port` **[number][2]?** Mock server port
+-   `host` **[string][3]?** Mock server host
+-   `httpsOpts` **[object][1]?** key & cert values are the paths to .key and .crt files
+
+
+
+#### Examples
+
+You can seamlessly integrate MockServer with other helpers like REST or Playwright. Here's a configuration example inside the `codecept.conf.js` file:
+
+```javascript
+{
+  helpers: {
+    REST: {...},
+    MockServer: {
+      // default mock server config
+      port: 9393,
+      host: '0.0.0.0',
+      httpsOpts: {
+        key: '',
+        cert: '',
+      },
+    },
+  }
+}
+```
+
+#### Adding Interactions
+
+Interactions add behavior to the mock server. Use the `I.addInteractionToMockServer()` method to include interactions. It takes an interaction object as an argument, containing request and response details.
+
+```javascript
+I.addInteractionToMockServer({
+   request: {
+     method: 'GET',
+     path: '/api/hello'
+   },
+   response: {
+     status: 200,
+     body: {
+       'say': 'hello to mock server'
+     }
+   }
+});
+```
+
+#### Request Matching
+
+When a real request is sent to the mock server, it matches the received request with the interactions. If a match is found, it returns the specified response; otherwise, a 404 status code is returned.
+
+-   Strong match on HTTP Method, Path, Query Params & JSON body.
+-   Loose match on Headers.
+
+##### Strong Match on Query Params
+
+You can send different responses based on query parameters:
+
+```javascript
+I.addInteractionToMockServer({
+  request: {
+    method: 'GET',
+    path: '/api/users',
+    queryParams: {
+      id: 1
+    }
+  },
+  response: {
+    status: 200,
+    body: 'user 1'
+  }
+});
+
+I.addInteractionToMockServer({
+  request: {
+    method: 'GET',
+    path: '/api/users',
+    queryParams: {
+      id: 2
+    }
+  },
+  response: {
+    status: 200,
+    body: 'user 2'
+  }
+});
+```
+
+-   GET to `/api/users?id=1` will return 'user 1'.
+-   GET to `/api/users?id=2` will return 'user 2'.
+-   For all other requests, it returns a 404 status code.
+
+##### Loose Match on Body
+
+When `strict` is set to false, it performs a loose match on query params and response body:
+
+```javascript
+I.addInteractionToMockServer({
+  strict: false,
+  request: {
+    method: 'POST',
+    path: '/api/users',
+    body: {
+      name: 'john'
+    }
+  },
+  response: {
+    status: 200
+  }
+});
+```
+
+-   POST to `/api/users` with the body containing `name` as 'john' will return a 200 status code.
+-   POST to `/api/users` without the `name` property in the body will return a 404 status code.
+
+Happy testing with MockServer in CodeceptJS! 🚀
+
+## Methods
+
+### Parameters
+
+-   `passedConfig`  
+
+### addInteractionToMockServer
+
+An interaction adds behavior to the mock server
+
+```js
+I.addInteractionToMockServer({
+   request: {
+     method: 'GET',
+     path: '/api/hello'
+   },
+   response: {
+     status: 200,
+     body: {
+       'say': 'hello to mock server'
+     }
+   }
+});
+```
+
+```js
+// with query params
+I.addInteractionToMockServer({
+   request: {
+     method: 'GET',
+     path: '/api/hello',
+     queryParams: {
+      id: 2
+    }
+   },
+   response: {
+     status: 200,
+     body: {
+       'say': 'hello to mock server'
+     }
+   }
+});
+```
+
+#### Parameters
+
+-   `interaction` **(CodeceptJS.MockInteraction | [object][1])** add behavior to the mock server
+
+Returns **any** void
+
+### startMockServer
+
+Start the mock server
+
+#### Parameters
+
+-   `port` **[number][2]?** start the mock server with given port
+
+Returns **any** void
+
+### stopMockServer
+
+Stop the mock server
+
+Returns **any** void
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String