codeceptjs 3.5.12-beta.5 → 3.5.12-beta.7

package/typings/promiseBasedTypes.d.ts

@@ -1732,6 +1732,188 @@ declare namespace CodeceptJS {
          */
         seeResponseMatchesJsonSchema(fnOrSchema: any): Promise<any>;
     }
+    /**
+     * ## Configuration
+     *
+     * This helper should be configured in codecept.conf.(js|ts)
+     * @property [port = 9393] - Mock server port
+     * @property [host = "0.0.0.0"] - Mock server host
+     * @property [httpsOpts] - key & cert values are the paths to .key and .crt files
+     */
+    type MockServerConfig = {
+        port?: number;
+        host?: string;
+        httpsOpts?: any;
+    };
+    /**
+     * 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 -->
+     *
+     * #### 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
+     */
+    class MockServer {
+        /**
+         * Start the mock server
+         * @param [port] - start the mock server with given port
+         */
+        startMockServer(port?: number): Promise<any>;
+        /**
+         * Stop the mock server
+         */
+        stopMockServer(): Promise<any>;
+        /**
+         * 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'
+         *      }
+         *    }
+         * });
+         * ```
+         * @param interaction - add behavior to the mock server
+         */
+        addInteractionToMockServer(interaction: CodeceptJS.MockInteraction | any): Promise<any>;
+    }
     /**
      * Nightmare helper wraps [Nightmare](https://github.com/segmentio/nightmare) library to provide
      * fastest headless testing using Electron engine. Unlike Selenium-based drivers this uses

package/typings/types.d.ts

@@ -1759,6 +1759,188 @@ declare namespace CodeceptJS {
          */
         seeResponseMatchesJsonSchema(fnOrSchema: any): void;
     }
+    /**
+     * ## Configuration
+     *
+     * This helper should be configured in codecept.conf.(js|ts)
+     * @property [port = 9393] - Mock server port
+     * @property [host = "0.0.0.0"] - Mock server host
+     * @property [httpsOpts] - key & cert values are the paths to .key and .crt files
+     */
+    type MockServerConfig = {
+        port?: number;
+        host?: string;
+        httpsOpts?: any;
+    };
+    /**
+     * 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 -->
+     *
+     * #### 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
+     */
+    class MockServer {
+        /**
+         * Start the mock server
+         * @param [port] - start the mock server with given port
+         */
+        startMockServer(port?: number): void;
+        /**
+         * Stop the mock server
+         */
+        stopMockServer(): void;
+        /**
+         * 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'
+         *      }
+         *    }
+         * });
+         * ```
+         * @param interaction - add behavior to the mock server
+         */
+        addInteractionToMockServer(interaction: CodeceptJS.MockInteraction | any): void;
+    }
     /**
      * Nightmare helper wraps [Nightmare](https://github.com/segmentio/nightmare) library to provide
      * fastest headless testing using Electron engine. Unlike Selenium-based drivers this uses