codeceptjs 3.5.2 → 3.5.3

package/typings/promiseBasedTypes.d.ts

@@ -4519,6 +4519,133 @@ declare namespace CodeceptJS {
          * @param [handler] - a function to process reques
          */
         stopMockingRoute(url?: string | RegExp, handler?: (...params: any[]) => any): Promise<any>;
+        /**
+         * Starts recording of network traffic.
+         * This also resets recorded network requests.
+         *
+         * ```js
+         * I.startRecordingTraffic();
+         * ```
+         */
+        startRecordingTraffic(): Promise<void>;
+        /**
+         * Grab the recording network traffics
+         */
+        grabRecordedNetworkTraffics(): Promise<any>;
+        /**
+         * Blocks traffic for URL.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.blockTraffic('http://example.com/css/style.css');
+         * I.blockTraffic('http://example.com/css/*.css');
+         * I.blockTraffic('http://example.com/**');
+         * I.blockTraffic(/\.css$/);
+         * ```
+         * @param url - URL to block . URL can contain * for wildcards. Example: https://www.example.com** to block all traffic for that domain. Regexp are also supported.
+         */
+        blockTraffic(url: any): Promise<any>;
+        /**
+         * Mocks traffic for URL(s).
+         * This is a powerful feature to manipulate network traffic. Can be used e.g. to stabilize your tests, speed up your tests or as a last resort to make some test scenarios even possible.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.mockTraffic('/api/users/1', '{ id: 1, name: 'John Doe' }');
+         * I.mockTraffic('/api/users/*', JSON.stringify({ id: 1, name: 'John Doe' }));
+         * I.mockTraffic([/^https://api.example.com/v1/, 'https://api.example.com/v2/**'], 'Internal Server Error', 'text/html');
+         * ```
+         * @param urls - string|Array These are the URL(s) to mock, e.g. "/fooapi/*" or "['/fooapi_1/*', '/barapi_2/*']". Regular expressions are also supported.
+         * @param responseString - string The string to return in fake response's body.
+         * @param contentType - Content type of fake response. If not specified default value 'application/json' is used.
+         */
+        mockTraffic(urls: any, responseString: any, contentType?: any): Promise<any>;
+        /**
+         * Resets all recorded network requests.
+         */
+        flushNetworkTraffics(): Promise<any>;
+        /**
+         * Stops recording of network traffic. Recorded traffic is not flashed.
+         *
+         * ```js
+         * I.stopRecordingTraffic();
+         * ```
+         */
+        stopRecordingTraffic(): Promise<any>;
+        /**
+         * Verifies that a certain request is part of network traffic.
+         *
+         * ```js
+         * // checking the request url contains certain query strings
+         * I.amOnPage('https://openai.com/blog/chatgpt');
+         * I.startRecordingTraffic();
+         * await I.seeTraffic({
+         *    name: 'sentry event',
+         *    url: 'https://images.openai.com/blob/cf717bdb-0c8c-428a-b82b-3c3add87a600',
+         *    parameters: {
+         *       width: '1919',
+         *       height: '1138',
+         *     },
+         * });
+         * ```
+         *
+         * ```js
+         * // checking the request url contains certain post data
+         * I.amOnPage('https://openai.com/blog/chatgpt');
+         * I.startRecordingTraffic();
+         * await I.seeTraffic({
+         *    name: 'event',
+         *    url: 'https://cloudflareinsights.com/cdn-cgi/rum',
+         *    requestPostData: {
+         *       st: 2,
+         *     },
+         * });
+         * ```
+         * @param opts - options when checking the traffic network.
+         * @param opts.name - A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+         * @param opts.url - Expected URL of request in network traffic
+         * @param [opts.parameters] - Expected parameters of that request in network traffic
+         * @param [opts.requestPostData] - Expected that request contains post data in network traffic
+         * @param [opts.timeout] - Timeout to wait for request in seconds. Default is 10 seconds.
+         */
+        seeTraffic(opts: {
+            name: string;
+            url: string;
+            parameters?: any;
+            requestPostData?: any;
+            timeout?: number;
+        }): Promise<any>;
+        /**
+         * Returns full URL of request matching parameter "urlMatch".
+         * @param urlMatch - Expected URL of request in network traffic. Can be a string or a regular expression.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.grabTrafficUrl('https://api.example.com/session');
+         * I.grabTrafficUrl(/session.*start/);
+         * ```
+         */
+        grabTrafficUrl(urlMatch: string | RegExp): Promise<any>;
+        /**
+         * Verifies that a certain request is not part of network traffic.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSeeTraffic({ name: 'Unexpected API Call', url: 'https://api.example.com' });
+         * I.dontSeeTraffic({ name: 'Unexpected API Call of "user" endpoint', url: /api.example.com.*user/ });
+         * ```
+         * @param opts - options when checking the traffic network.
+         * @param opts.name - A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+         * @param opts.url - Expected URL of request in network traffic. Can be a string or a regular expression.
+         */
+        dontSeeTraffic(opts: {
+            name: string;
+            url: string | RegExp;
+        }): Promise<any>;
     }
     /**
      * This helper works the same as MockRequest helper. It has been included for backwards compatibility

package/typings/types.d.ts

@@ -4602,6 +4602,133 @@ declare namespace CodeceptJS {
          * @param [handler] - a function to process reques
          */
         stopMockingRoute(url?: string | RegExp, handler?: (...params: any[]) => any): void;
+        /**
+         * Starts recording of network traffic.
+         * This also resets recorded network requests.
+         *
+         * ```js
+         * I.startRecordingTraffic();
+         * ```
+         */
+        startRecordingTraffic(): Promise<void>;
+        /**
+         * Grab the recording network traffics
+         */
+        grabRecordedNetworkTraffics(): any[];
+        /**
+         * Blocks traffic for URL.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.blockTraffic('http://example.com/css/style.css');
+         * I.blockTraffic('http://example.com/css/*.css');
+         * I.blockTraffic('http://example.com/**');
+         * I.blockTraffic(/\.css$/);
+         * ```
+         * @param url - URL to block . URL can contain * for wildcards. Example: https://www.example.com** to block all traffic for that domain. Regexp are also supported.
+         */
+        blockTraffic(url: any): void;
+        /**
+         * Mocks traffic for URL(s).
+         * This is a powerful feature to manipulate network traffic. Can be used e.g. to stabilize your tests, speed up your tests or as a last resort to make some test scenarios even possible.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.mockTraffic('/api/users/1', '{ id: 1, name: 'John Doe' }');
+         * I.mockTraffic('/api/users/*', JSON.stringify({ id: 1, name: 'John Doe' }));
+         * I.mockTraffic([/^https://api.example.com/v1/, 'https://api.example.com/v2/**'], 'Internal Server Error', 'text/html');
+         * ```
+         * @param urls - string|Array These are the URL(s) to mock, e.g. "/fooapi/*" or "['/fooapi_1/*', '/barapi_2/*']". Regular expressions are also supported.
+         * @param responseString - string The string to return in fake response's body.
+         * @param contentType - Content type of fake response. If not specified default value 'application/json' is used.
+         */
+        mockTraffic(urls: any, responseString: any, contentType?: any): void;
+        /**
+         * Resets all recorded network requests.
+         */
+        flushNetworkTraffics(): void;
+        /**
+         * Stops recording of network traffic. Recorded traffic is not flashed.
+         *
+         * ```js
+         * I.stopRecordingTraffic();
+         * ```
+         */
+        stopRecordingTraffic(): void;
+        /**
+         * Verifies that a certain request is part of network traffic.
+         *
+         * ```js
+         * // checking the request url contains certain query strings
+         * I.amOnPage('https://openai.com/blog/chatgpt');
+         * I.startRecordingTraffic();
+         * await I.seeTraffic({
+         *    name: 'sentry event',
+         *    url: 'https://images.openai.com/blob/cf717bdb-0c8c-428a-b82b-3c3add87a600',
+         *    parameters: {
+         *       width: '1919',
+         *       height: '1138',
+         *     },
+         * });
+         * ```
+         *
+         * ```js
+         * // checking the request url contains certain post data
+         * I.amOnPage('https://openai.com/blog/chatgpt');
+         * I.startRecordingTraffic();
+         * await I.seeTraffic({
+         *    name: 'event',
+         *    url: 'https://cloudflareinsights.com/cdn-cgi/rum',
+         *    requestPostData: {
+         *       st: 2,
+         *     },
+         * });
+         * ```
+         * @param opts - options when checking the traffic network.
+         * @param opts.name - A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+         * @param opts.url - Expected URL of request in network traffic
+         * @param [opts.parameters] - Expected parameters of that request in network traffic
+         * @param [opts.requestPostData] - Expected that request contains post data in network traffic
+         * @param [opts.timeout] - Timeout to wait for request in seconds. Default is 10 seconds.
+         */
+        seeTraffic(opts: {
+            name: string;
+            url: string;
+            parameters?: any;
+            requestPostData?: any;
+            timeout?: number;
+        }): Promise<any>;
+        /**
+         * Returns full URL of request matching parameter "urlMatch".
+         * @param urlMatch - Expected URL of request in network traffic. Can be a string or a regular expression.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.grabTrafficUrl('https://api.example.com/session');
+         * I.grabTrafficUrl(/session.*start/);
+         * ```
+         */
+        grabTrafficUrl(urlMatch: string | RegExp): Promise<any>;
+        /**
+         * Verifies that a certain request is not part of network traffic.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSeeTraffic({ name: 'Unexpected API Call', url: 'https://api.example.com' });
+         * I.dontSeeTraffic({ name: 'Unexpected API Call of "user" endpoint', url: /api.example.com.*user/ });
+         * ```
+         * @param opts - options when checking the traffic network.
+         * @param opts.name - A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+         * @param opts.url - Expected URL of request in network traffic. Can be a string or a regular expression.
+         */
+        dontSeeTraffic(opts: {
+            name: string;
+            url: string | RegExp;
+        }): void;
     }
     /**
      * This helper works the same as MockRequest helper. It has been included for backwards compatibility
@@ -11114,31 +11241,6 @@ declare namespace CodeceptJS {
          */
         function cleanDispatcher(): void;
     }
-    namespace browserCodecept {
-        /**
-         * all found elements are stored here for reuse
-         */
-        var elements: Node[];
-        /**
-         * global context changer
-         */
-        var within: Node;
-        /**
-         * finders
-         */
-        function fetchElement(id: number): Node;
-        function findAndStoreElements(by: string, locator: CodeceptJS.ILocator, contextEl?: any): number[];
-        function findAndStoreElement(by: string, locator: CodeceptJS.ILocator, contextEl?: any): number | undefined;
-        function setWithin(by: string, locator: CodeceptJS.ILocator): void;
-        function findElements(by: string, locator: CodeceptJS.ILocator, contextEl?: any): Node[];
-        function findElement(by: string, locator: CodeceptJS.ILocator, context?: any): Node;
-        function clickEl(el: number): boolean;
-        function doubleClickEl(el: number): void;
-        function hoverEl(el: number, x: number | undefined, y: number | undefined): void;
-        function rightClickEl(el: number): void;
-        function checkEl(el: number): boolean | undefined;
-        function unCheckEl(el: number): boolean;
-    }
     /**
      * Index file for loading CodeceptJS programmatically.
      *

package/docs/nightmare.md

@@ -1,223 +0,0 @@
----
-permalink: /nightmare
-title: Testing with Nightmare
----
-
-# Testing with Nightmare
-
-Selenium WebDriver is considered to be standard for end to end testing of web applications.
-Despite its popularity it have its drawbacks, it requires a real browser and Selenium server to control it.
-This hardens setting it up testing environment for CI server and slows down test execution.
-
-Is there a sane alternative to Selenium?
-
-Yes, how about [NightmareJS](https://www.nightmarejs.org)?
-
-It is modern Electron based testing framework which allows to execute tests in headless mode as well as in window mode for debug purposes.
-This makes Nightmare very useful, much more handy than PhantomJS. Nightmare is in active development and has nice API for writing acceptance tests.
-Unfortunately, as all other JavaScript testing frameworks it has its own very custom API.
-What if you choose it for a project and suddenly you realize that you need something more powerful, like Selenium?
-Yes, that might be a problem if you are not using CodeceptJS.
-The one idea behind CodeceptJS is to unify different testing backends under one API, so you could easily write tests the same way no matter what engines you use: webdriverio, Protractor, or Nightmare.
-
-Compare a test written using Nightmare API:
-
-```js
-nightmare
-  .goto('http://yahoo.com')
-  .type('form[action*="/search"] [name=p]', 'github nightmare')
-  .click('form[action*="/search"] [type=submit]')
-  .wait('#main')
-  .evaluate(function () {
-    return document.querySelector('#main .searchCenterMiddle li a').href
-  })
-```
-
-with a similar CodeceptJS test:
-
-```js
-  I.amOnPage('http://yahoo.com');
-  I.fillField('p', 'github nightmare');
-  I.click('Search Web');
-  I.waitForElement('#main');
-  I.seeElement('#main .searchCenterMiddle li a');
-  I.seeElement("//a[contains(@href,'github.com/segmentio/nightmare')]");
-  I.see('segmentio/nightmare','#main li a');
-```
-
-NightmareJS support only CSS locators for web elements, while CodeceptJS improves it to use XPath as well.
-This is how form can be located by labels, and buttons by text in examples above. It is done by injecting
-client-side scrips (for element location) to every loaded page. Also all events like click, doubleClick, keyPress are **simulated** by JavaScript,
-this makes testing less relevant, as they are not native to operating systems.
-
-## How Fast Is Nightmare JS?
-
-Let's execute the test above within WebDriver using headless Firefox + Selenium Server packed in Docker container.
-
-```sh
-docker run -d -p 4444:4444 selenium/standalone-firefox:2.53.0
-codeceptjs run yahoo_test.js --steps
-```
-
-This provides use with output:
-
-```sh
- Yahoo basic test
- > WebDriver._before
- • I am on page "http://yahoo.com"
- • I fill field "p", "github nightmare"
- • I click "Search Web"
- • I wait for element "#main", 2
- • I see element "#main .searchCenterMiddle li a"
- • I see "segmentio/nightmare", "li a"
- ✓ OK in 17591ms
-```
-
-When we switch helper to Nightmare:
-
-```sh
- Yahoo basic test
- > Nightmare._before
- • I am on page "http://yahoo.com"
- • I fill field "p", "github nightmare"
- • I click "Search Web"
- • I wait for element "#main", 2
- • I see element "#main .searchCenterMiddle li a"
- • I see "segmentio/nightmare", "li a"
- ✓ OK in 5490ms
-```
-
-As you see the Nightmare test was almost **3 times faster** than Selenium test.
-Sure, this can't be taken as a valuable benchmark but more like a proof of concept.
-
-## Setup
-
-To start you need CodeceptJS with nightmare package installed.
-
-```bash
-npm install -g nightmare
-```
-
-And a basic project initialized
-
-```sh
-codeceptjs init
-```
-
-You will be asked for a Helper to use, you should select Nightmare and provide url of a website you are testing.
-Setup process is explained on [QuickStart page](https://codecept.io/quickstart/).
-
-(If you already have CodeceptJS project, just install nightmare globally or locally and enable it in config)
-
-## Configuring Nightmare
-
-Enable `Nightmare` helper in `codecept.json` config:
-
-```js
-{ // ..
-  "helpers": {
-    "Nightmare": {
-      "url": "http://localhost",
-      "show": false,
-      "restart": false
-    }
-  }
-  // ..
-}
-```
-
-Turn on the `show` option if you want to follow test progress in a window. This is very useful for debugging.
-All other options can be taken from [NightmareJS API](https://github.com/segmentio/nightmare#api).
-
-Turn off the `restart` option if you want to run your suite in a single browser instance.
-
-Option `waitForAction` defines how long to wait after a click, doubleClick or pressKey action is performed.
-Test execution may happen much faster than the response is rendered, so make sure you set a proper delay value.
-By default CodeceptJS waits for 500ms.
-
-## Opening a Web Page
-
-Nightmare provides you with more control to browser engine than Selenium does.
-This allows you to use headers in your tests. For instance, CodeceptJS provides `haveHeader` method
-to set default headers for all your HTTP requests:
-
-```js
-I.haveHeader('x-tested-with', 'codeceptjs');
-```
-
-When opening a web page you can set headers as well. `amOnPage` methods can take headers as second parameter:
-
-```js
-// use basic http auth
-I.amOnPage('/admin', { 'Authorization': 'Basic '+token });
-```
-
-As a small bonus: all `console.log` calls on a page will be also shown in `--debug` mode.
-
-## Manipulating Web Page
-
-Nightmare helper is supposed to work in the same manner as WebDriver or Protractor.
-This means that all CodeceptJS actions like `click`, `fillField`, `selectOption` and others are supposed to work in the very same manner.
-They are expressive and flexible to accept CSS, XPath, names, values, or strict locators. Follow the helper reference for detailed description.
-
-Assertions start with `see` prefix. You can check text on a page, elements on page and others.
-
-## Extending Nightmare Helper
-
-CodeceptJS allows you to define and connect own helpers. If some functionality of
-Nightmare helper is missing you can easily create `ExtendedNightmare` helper by running:
-
-```sh
-codeceptjs gh
-```
-
-Learn more about [Helpers](https://codecept.io/helpers/).
-
-Nightmare instance can be accessed by custom helper:
-
-```js
-// returns current nightmare instance
-this.helpers['Nightmare'].browser;
-```
-
-This way you can call [native Nightmare commands](https://github.com/segmentio/nightmare#interact-with-the-page).
-
-It is important to understand that Nightmare executes JavaScript on client and on server side.
-If you need to find an element you should search for it using client side script, but if you want
-to do an assertion you should return a data to server side.
-
-Nightmare provides `evaluate` method to execute client-side JavaScript. CodeceptJS registers `codeceptjs`
-object globally on client side with `findElement` and `findElements` methods in it. They return IDs of matched elements
-so you can access them in next calls to `evaluate`:
-
-```js
-// inside a custom helper class
-async seeAttributeContains(locator, attribute, expectedValue) {
-  // let's use chai assertion library
-  const assert = require('chai').assert;
-  // get nightmare instance
-  const browser = this.helpers['Nightmare'].browser;
-  // find an element by CSS or XPath:
-  const els = await this.helpers['Nightmare']._locate(locator);
-    // we received an array with IDs of matched elements
-    // now let's execute client-side script to get attribute for the first element
-  const attributeValue = await browser.evaluate(function(el, attribute) {
-      // this is executed inside a web page!
-      return codeceptjs.fetchElement(el).getAttribute(attribute);
-  }, els[0], attribute); // function + its params
-
-    // get attribute value and back to server side
-    // execute an assertion
-  assert.include(attributeValue, expectedValue);
-}
-```
-
-It can be used in tests like:
-
-```js
-I.seeAttributeContains('#main img', 'src', '/cat.jpg');
-```
-
-This sample assertion used `_locate` helper method which searched for elements
-by CSS/XPath or a strict locator. Then `browser.evaluate` method was called to
-use locate found elements on a page and return attribute from the first of them.