cypress 5.1.0 → 5.2.0

package/lib/errors.js

@@ -121,7 +121,7 @@ function _templateObject6() {
 }
 
 function _templateObject5() {
-  var data = _taggedTemplateLiteral(["\n\n    Reasons this may happen:\n\n    - node was installed as 'root' or with 'sudo'\n    - the cypress npm package as 'root' or with 'sudo'\n\n    Please check that you have the appropriate user permissions.\n  "], ["\\n\n    Reasons this may happen:\n\n    - node was installed as 'root' or with 'sudo'\n    - the cypress npm package as 'root' or with 'sudo'\n\n    Please check that you have the appropriate user permissions.\n  "]);
+  var data = _taggedTemplateLiteral(["\n\n    Reasons this may happen:\n\n    - node was installed as 'root' or with 'sudo'\n    - the cypress npm package as 'root' or with 'sudo'\n\n    Please check that you have the appropriate user permissions.\n\n    You can also try clearing the cache with 'cypress cache clear' and reinstalling. \n  "], ["\\n\n    Reasons this may happen:\n\n    - node was installed as 'root' or with 'sudo'\n    - the cypress npm package as 'root' or with 'sudo'\n\n    Please check that you have the appropriate user permissions.\n\n    You can also try clearing the cache with 'cypress cache clear' and reinstalling. \n  "]);
 
   _templateObject5 = function _templateObject5() {
     return data;

package/lib/tasks/install.js

@@ -1,5 +1,7 @@
 "use strict";
 
+function _typeof(obj) { "@babel/helpers - typeof"; if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }; } return _typeof(obj); }
+
 function _templateObject7() {
   var data = _taggedTemplateLiteral(["\n          ", " Warning: Forcing a binary version different than the default.\n\n            The CLI expected to install version: ", "\n\n            Instead we will install version: ", "\n\n            These versions may not work properly together.\n        "]);
 
@@ -20,6 +22,18 @@ function _templateObject6() {
   return data;
 }
 
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function _iterableToArrayLimit(arr, i) { if (typeof Symbol === "undefined" || !(Symbol.iterator in Object(arr))) return; var _arr = []; var _n = true; var _d = false; var _e = undefined; try { for (var _i = arr[Symbol.iterator](), _s; !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"] != null) _i["return"](); } finally { if (_d) throw _e; } } return _arr; }
+
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+
 function _templateObject5() {
   var data = _taggedTemplateLiteral(["\n    Failed to access ", ":\n\n    ", "\n    "]);
 
@@ -72,10 +86,32 @@ function _templateObject() {
 
 function _taggedTemplateLiteral(strings, raw) { if (!raw) { raw = strings.slice(0); } return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } })); }
 
+function _wrapRegExp(re, groups) { _wrapRegExp = function _wrapRegExp(re, groups) { return new BabelRegExp(re, undefined, groups); }; var _RegExp = _wrapNativeSuper(RegExp); var _super = RegExp.prototype; var _groups = new WeakMap(); function BabelRegExp(re, flags, groups) { var _this = _RegExp.call(this, re, flags); _groups.set(_this, groups || _groups.get(re)); return _this; } _inherits(BabelRegExp, _RegExp); BabelRegExp.prototype.exec = function (str) { var result = _super.exec.call(this, str); if (result) result.groups = buildGroups(result, this); return result; }; BabelRegExp.prototype[Symbol.replace] = function (str, substitution) { if (typeof substitution === "string") { var groups = _groups.get(this); return _super[Symbol.replace].call(this, str, substitution.replace(/\$<([^>]+)>/g, function (_, name) { return "$" + groups[name]; })); } else if (typeof substitution === "function") { var _this = this; return _super[Symbol.replace].call(this, str, function () { var args = []; args.push.apply(args, arguments); if (_typeof(args[args.length - 1]) !== "object") { args.push(buildGroups(args, _this)); } return substitution.apply(this, args); }); } else { return _super[Symbol.replace].call(this, str, substitution); } }; function buildGroups(result, re) { var g = _groups.get(re); return Object.keys(g).reduce(function (groups, name) { groups[name] = result[g[name]]; return groups; }, Object.create(null)); } return _wrapRegExp.apply(this, arguments); }
+
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); if (superClass) _setPrototypeOf(subClass, superClass); }
+
+function _possibleConstructorReturn(self, call) { if (call && (_typeof(call) === "object" || typeof call === "function")) { return call; } return _assertThisInitialized(self); }
+
+function _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return self; }
+
+function _wrapNativeSuper(Class) { var _cache = typeof Map === "function" ? new Map() : undefined; _wrapNativeSuper = function _wrapNativeSuper(Class) { if (Class === null || !_isNativeFunction(Class)) return Class; if (typeof Class !== "function") { throw new TypeError("Super expression must either be null or a function"); } if (typeof _cache !== "undefined") { if (_cache.has(Class)) return _cache.get(Class); _cache.set(Class, Wrapper); } function Wrapper() { return _construct(Class, arguments, _getPrototypeOf(this).constructor); } Wrapper.prototype = Object.create(Class.prototype, { constructor: { value: Wrapper, enumerable: false, writable: true, configurable: true } }); return _setPrototypeOf(Wrapper, Class); }; return _wrapNativeSuper(Class); }
+
+function _construct(Parent, args, Class) { if (_isNativeReflectConstruct()) { _construct = Reflect.construct; } else { _construct = function _construct(Parent, args, Class) { var a = [null]; a.push.apply(a, args); var Constructor = Function.bind.apply(Parent, a); var instance = new Constructor(); if (Class) _setPrototypeOf(instance, Class.prototype); return instance; }; } return _construct.apply(null, arguments); }
+
+function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }
+
+function _isNativeFunction(fn) { return Function.toString.call(fn).indexOf("[native code]") !== -1; }
+
+function _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }
+
+function _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }
+
 var _ = require('lodash');
 
 var os = require('os');
 
+var url = require('url');
+
 var path = require('path');
 
 var chalk = require('chalk');
@@ -109,6 +145,102 @@ var _require2 = require('../errors'),
     throwFormErrorText = _require2.throwFormErrorText,
     errors = _require2.errors;
 
+var getNpmArgv = function getNpmArgv() {
+  var json = process.env.npm_config_argv;
+
+  if (!json) {
+    return;
+  }
+
+  debug('found npm argv json %o', json);
+
+  try {
+    return JSON.parse(json).original || [];
+  } catch (e) {
+    return [];
+  }
+}; // attempt to discover the version specifier used to install Cypress
+// for example: "^5.0.0", "https://cdn.cypress.io/...", ...
+
+
+var getVersionSpecifier = function getVersionSpecifier() {
+  var startDir = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : path.resolve(__dirname, '../..');
+  var argv = getNpmArgv();
+
+  if (argv) {
+    var tgz = _.find(argv, function (t) {
+      return t.endsWith('cypress.tgz');
+    });
+
+    if (tgz) {
+      return tgz;
+    }
+  }
+
+  var getVersionSpecifierFromPkg = function getVersionSpecifierFromPkg(dir) {
+    debug('looking for versionSpecifier %o', {
+      dir: dir
+    });
+
+    var tryParent = function tryParent() {
+      var parentPath = path.resolve(dir, '..');
+
+      if (parentPath === dir) {
+        debug('reached FS root with no versionSpecifier found');
+        return;
+      }
+
+      return getVersionSpecifierFromPkg(parentPath);
+    };
+
+    return fs.readJSON(path.join(dir, 'package.json'))["catch"](function () {
+      return {};
+    }).then(function (pkg) {
+      var specifier = _.chain(['dependencies', 'devDependencies', 'optionalDependencies']).map(function (prop) {
+        return _.get(pkg, "".concat(prop, ".cypress"));
+      }).compact().first().value();
+
+      return specifier || tryParent();
+    });
+  }; // recurse through parent directories until package.json with `cypress` is found
+
+
+  return getVersionSpecifierFromPkg(startDir).then(function (versionSpecifier) {
+    debug('finished looking for versionSpecifier', {
+      versionSpecifier: versionSpecifier
+    });
+    return versionSpecifier;
+  });
+};
+
+var betaNpmUrlRe = /*#__PURE__*/_wrapRegExp(/^\/beta\/npm\/([\.0-9]+)\/([\0-\.0-\uFFFF]+)\/cypress\.tgz$/, {
+  version: 1,
+  artifactSlug: 2
+}); // convert a prerelease NPM package .tgz URL to the corresponding binary .zip URL
+
+
+var getBinaryUrlFromPrereleaseNpmUrl = function getBinaryUrlFromPrereleaseNpmUrl(npmUrl) {
+  var parsed;
+
+  try {
+    parsed = url.parse(npmUrl);
+  } catch (e) {
+    return;
+  }
+
+  var matches = betaNpmUrlRe.exec(parsed.pathname);
+
+  if (parsed.hostname !== 'cdn.cypress.io' || !matches) {
+    return;
+  }
+
+  var _matches$groups = matches.groups,
+      version = _matches$groups.version,
+      artifactSlug = _matches$groups.artifactSlug;
+  parsed.pathname = "/beta/binary/".concat(version, "/").concat(os.platform(), "-").concat(os.arch(), "/").concat(artifactSlug, "/cypress.zip");
+  return parsed.format();
+};
+
 var alreadyInstalledMsg = function alreadyInstalledMsg() {
   if (!util.isPostInstall()) {
     logger.log(stripIndent(_templateObject(), chalk.yellow('--force')));
@@ -204,6 +336,7 @@ var start = function start() {
 
   var pkgVersion = util.pkgVersion();
   var needVersion = pkgVersion;
+  var binaryUrlOverride;
   debug('version in package.json is', needVersion); // let this environment variable reset the binary version we need
 
   if (util.getEnv('CYPRESS_INSTALL_BINARY')) {
@@ -218,14 +351,9 @@ var start = function start() {
       logger.log(stripIndent(_templateObject3(), chalk.yellow('Note:')));
       logger.log();
       return Promise.resolve();
-    } // if this doesn't match the expected version
-    // then print warning to the user
-
-
-    if (envVarVersion !== needVersion) {
-      // reset the version to the env var version
-      needVersion = envVarVersion;
     }
+
+    binaryUrlOverride = envVarVersion;
   }
 
   if (util.getEnv('CYPRESS_CACHE_FOLDER')) {
@@ -242,14 +370,32 @@ var start = function start() {
   }, function (err) {
     return throwFormErrorText(errors.invalidCacheDirectory)(stripIndent(_templateObject5(), chalk.cyan(cacheDir), err.message));
   }).then(function () {
-    return state.getBinaryPkgVersionAsync(binaryDir);
-  }).then(function (binaryVersion) {
+    return Promise.all([state.getBinaryPkgVersionAsync(binaryDir), getVersionSpecifier()]);
+  }).then(function (_ref2) {
+    var _ref3 = _slicedToArray(_ref2, 2),
+        binaryVersion = _ref3[0],
+        versionSpecifier = _ref3[1];
+
+    if (!binaryUrlOverride && versionSpecifier) {
+      var computedBinaryUrl = getBinaryUrlFromPrereleaseNpmUrl(versionSpecifier);
+
+      if (computedBinaryUrl) {
+        debug('computed binary url from version specifier %o', {
+          computedBinaryUrl: computedBinaryUrl,
+          needVersion: needVersion
+        });
+        binaryUrlOverride = computedBinaryUrl;
+      }
+    }
+
+    needVersion = binaryUrlOverride || needVersion;
+    debug('installed version is', binaryVersion, 'version needed is', needVersion);
+
     if (!binaryVersion) {
       debug('no binary installed under cli version');
       return true;
     }
 
-    debug('installed version is', binaryVersion, 'version needed is', needVersion);
     logger.log();
     logger.log(stripIndent(_templateObject6(), chalk.green(binaryVersion), chalk.cyan(installDir)));
     logger.log();
@@ -332,14 +478,16 @@ var start = function start() {
 };
 
 module.exports = {
-  start: start
+  start: start,
+  _getVersionSpecifier: getVersionSpecifier,
+  _getBinaryUrlFromPrereleaseNpmUrl: getBinaryUrlFromPrereleaseNpmUrl
 };
 
-var unzipTask = function unzipTask(_ref2) {
-  var zipFilePath = _ref2.zipFilePath,
-      installDir = _ref2.installDir,
-      progress = _ref2.progress,
-      rendererOptions = _ref2.rendererOptions;
+var unzipTask = function unzipTask(_ref4) {
+  var zipFilePath = _ref4.zipFilePath,
+      installDir = _ref4.installDir,
+      progress = _ref4.progress,
+      rendererOptions = _ref4.rendererOptions;
   return {
     title: util.titleize('Unzipping Cypress'),
     task: function task(ctx, _task3) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "main": "index.js",
   "scripts": {
     "postinstall": "node index.js --exec install",

package/types/cypress.d.ts

@@ -1,10 +1,10 @@
 declare namespace Cypress {
   type FileContents = string | any[] | object
-  type HistoryDirection = "back" | "forward"
+  type HistoryDirection = 'back' | 'forward'
   type HttpMethod = string
   type RequestBody = string | object
-  type ViewportOrientation = "portrait" | "landscape"
-  type PrevSubject = "optional" | "element" | "document" | "window"
+  type ViewportOrientation = 'portrait' | 'landscape'
+  type PrevSubject = 'optional' | 'element' | 'document' | 'window'
   type PluginConfig = (on: PluginEvents, config: PluginConfigOptions) => void | ConfigOptions | Promise<ConfigOptions>
 
   interface CommandOptions {
@@ -114,7 +114,7 @@ declare namespace Cypress {
    *
    * @see https://on.cypress.io/experiments
    */
-  type CypressSpecType = "integration" | "component"
+  type CypressSpecType = 'integration' | 'component'
 
   /**
    * Window type for Application Under Test(AUT)
@@ -413,7 +413,7 @@ declare namespace Cypress {
        * Returns a boolean indicating whether an object is a DOM object.
        */
       isDom(obj: any): boolean
-      isType(element: JQuery | HTMLElement , type: string): boolean
+      isType(element: JQuery | HTMLElement, type: string): boolean
       /**
        * Returns a boolean indicating whether an element is visible.
        */
@@ -518,7 +518,7 @@ declare namespace Cypress {
     off: Actions
   }
 
-  type CanReturnChainable = void | Chainable
+  type CanReturnChainable = void | Chainable | Promise<unknown>
   type ThenReturn<S, R> =
     R extends void ? Chainable<S> :
     R extends R | undefined ? Chainable<S | Exclude<R, undefined>> :
@@ -1607,15 +1607,12 @@ declare namespace Cypress {
 
     /**
      * Traverse into an element's shadow root.
-     * Requires `experimentalShadowDomSupport: true` config option
      *
-    @example
-    ```js
-    cy.get('.top-level > my-component')
-      .shadow()
-      .find('.my-button')
-      .click()
-    ```
+     * @example
+     *    cy.get('my-component')
+     *    .shadow()
+     *    .find('.my-button')
+     *    .click()
      * @see https://on.cypress.io/experimental
      */
     shadow(): Chainable<Subject>
@@ -2302,7 +2299,7 @@ declare namespace Cypress {
      * @default {@link Timeoutable#timeout}
      * @see https://docs.cypress.io/guides/references/configuration.html#Timeouts
      */
-    requestTimeout: number,
+    requestTimeout: number
     /**
      * Time to wait for the response (ms)
      *
@@ -2485,7 +2482,7 @@ declare namespace Cypress {
      * If set to `system`, Cypress will try to find a `node` executable on your path to use when executing your plugins. Otherwise, Cypress will use the Node version bundled with Cypress.
      * @default "bundled"
      */
-    nodeVersion: "system" | "bundled"
+    nodeVersion: 'system' | 'bundled'
     /**
      * Path to plugins file. (Pass false to disable)
      * @default "cypress/plugins/index.js"
@@ -2584,12 +2581,6 @@ declare namespace Cypress {
      * @default false
      */
     experimentalNetworkStubbing: boolean
-    /**
-     * Enables shadow DOM support. Adds the `cy.shadow()` command and
-     * the `includeShadowDom` option to some DOM commands.
-     * @default false
-     */
-    experimentalShadowDomSupport: boolean
     /**
      * Number of times to retry a failed test.
      * If a number is set, tests will retry in both runMode and openMode.
@@ -2597,9 +2588,17 @@ declare namespace Cypress {
      * @default null
      */
     retries: Nullable<number | {runMode: Nullable<number>, openMode: Nullable<number>}>
+    /**
+     * Enables including elements within the shadow DOM when using querying
+     * commands (e.g. cy.get(), cy.find()). Can be set globally in cypress.json,
+     * per-suite or per-test in the test configuration object, or programmatically
+     * with Cypress.config()
+     * @default false
+     */
+    includeShadowDom: boolean
   }
 
-  interface TestConfigOverrides extends Partial<Pick<ConfigOptions, 'baseUrl' | 'defaultCommandTimeout' | 'taskTimeout' | 'animationDistanceThreshold' | 'waitForAnimations' | 'viewportHeight' | 'viewportWidth' | 'requestTimeout' | 'execTimeout' | 'env' | 'responseTimeout' | 'retries'>> {
+  interface TestConfigOverrides extends Partial<Pick<ConfigOptions, 'baseUrl' | 'defaultCommandTimeout' | 'taskTimeout' | 'animationDistanceThreshold' | 'waitForAnimations' | 'viewportHeight' | 'viewportWidth' | 'requestTimeout' | 'execTimeout' | 'env' | 'responseTimeout' | 'retries' | 'includeShadowDom'>> {
     browser?: IsBrowserMatcher | IsBrowserMatcher[]
   }
 
@@ -2699,18 +2698,18 @@ declare namespace Cypress {
     scale: boolean
     onBeforeScreenshot: ($el: JQuery) => void
     onAfterScreenshot: ($el: JQuery, props: {
-      path: string,
-      size: number,
+      path: string
+      size: number
       dimensions: {
-        width: number,
+        width: number
         height: number
-      },
-      multipart: boolean,
-      pixelRatio: number,
-      takenAt: string,
-      name: string,
-      blackout: string[],
-      duration: number,
+      }
+      multipart: boolean
+      pixelRatio: number
+      takenAt: string
+      name: string
+      blackout: string[]
+      duration: number
       testAttemptIndex: number
     }) => void
   }
@@ -2731,13 +2730,13 @@ declare namespace Cypress {
      *
      * @default 'swing'
      */
-    easing: 'swing' | 'linear',
+    easing: 'swing' | 'linear'
     /**
      * Ensure element is scrollable. Error if element is not scrollable
      *
      * @default true
      */
-    ensureScrollable: boolean,
+    ensureScrollable: boolean
   }
 
   interface ScrollIntoViewOptions extends ScrollToOptions {
@@ -2786,6 +2785,10 @@ declare namespace Cypress {
     sameSite: SameSiteStatus
   }
 
+  interface ShadowDomOptions {
+    includeShadowDom?: boolean
+  }
+
   /**
    * Options that control `cy.type` command
    *
@@ -4948,9 +4951,9 @@ declare namespace Cypress {
   }
 
   interface BrowserLaunchOptions {
-    extensions: string[],
+    extensions: string[]
     preferences: { [key: string]: any }
-    args: string[],
+    args: string[]
   }
 
   interface Dimensions {
@@ -5291,10 +5294,10 @@ declare namespace Cypress {
   }
 
   type Encodings = 'ascii' | 'base64' | 'binary' | 'hex' | 'latin1' | 'utf8' | 'utf-8' | 'ucs2' | 'ucs-2' | 'utf16le' | 'utf-16le'
-  type PositionType = "topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
+  type PositionType = 'topLeft' | 'top' | 'topRight' | 'left' | 'center' | 'right' | 'bottomLeft' | 'bottom' | 'bottomRight'
   type ViewportPreset = 'macbook-15' | 'macbook-13' | 'macbook-11' | 'ipad-2' | 'ipad-mini' | 'iphone-xr' | 'iphone-x' | 'iphone-6+' | 'iphone-6' | 'iphone-5' | 'iphone-4' | 'iphone-3' | 'samsung-s10' | 'samsung-note9'
   interface Offset {
-    top: number,
+    top: number
     left: number
   }
 
@@ -5382,6 +5385,6 @@ declare namespace Mocha {
   }
 
   interface PendingSuiteFunction {
-    (title: string,  config: Cypress.TestConfigOverrides, fn: (this: Suite) => void): Suite | void
+    (title: string, config: Cypress.TestConfigOverrides, fn: (this: Suite) => void): Suite | void
   }
 }

package/types/net-stubbing.ts

@@ -39,6 +39,11 @@ export namespace CyHttpMessages {
 
   export type IncomingRequest = BaseMessage & {
     responseTimeout?: number
+    /**
+     * Set if redirects should be followed when this request is made. By default, requests will
+     * not follow redirects before yielding the response (the 3xx redirect is yielded)
+     */
+    followRedirect?: boolean
   }
 
   export interface IncomingHttpRequest extends IncomingRequest {
@@ -173,7 +178,12 @@ export type RouteHandler = string | StaticResponse | RouteHandlerController | ob
 /**
  * Describes a response that will be sent back to the browser to fulfill the request.
  */
-export type StaticResponse = GenericStaticResponse<string, string | object>
+export type StaticResponse = GenericStaticResponse<string, string | object> & {
+  /**
+  * If set, `delayMs` will pass before the response is sent.
+  */
+ delayMs?: number
+}
 
 export interface GenericStaticResponse<Fixture, Body> {
   /**
@@ -196,6 +206,10 @@ export interface GenericStaticResponse<Fixture, Body> {
    * If `forceNetworkError` is truthy, Cypress will destroy the connection to the browser and send no response. Useful for simulating a server that is not reachable. Must not be set in combination with other options.
    */
   forceNetworkError?: boolean
+  /**
+   * If set, the `body` will be sent at `throttleKbps` kbps.
+   */
+  throttleKbps?: number
 }
 
 /**
@@ -206,7 +220,37 @@ export type StringMatcher = GlobPattern | RegExp
 declare global {
   namespace Cypress {
     interface Chainable<Subject = any> {
+      /**
+       * Use `cy.route2()` to stub and intercept HTTP requests and responses.
+       *
+       * Note: this command is only available if you have set the `experimentalNetworkStubbing`
+       * configuration option to `true`.
+       *
+       * @see https://on.cypress.io/route2
+       * @example
+       *    cy.route2('https://localhost:7777/users', [{id: 1, name: 'Pat'}])
+       * @example
+       *    cy.route2('https://localhost:7777/protected-endpoint', (req) => {
+       *      req.headers['authorization'] = 'basic fooabc123'
+       *    })
+       * @example
+       *    cy.route2('https://localhost:7777/some-response', (req) => {
+       *      req.reply(res => {
+       *        res.body = 'some new body'
+       *      })
+       *    })
+       */
       route2(url: RouteMatcher, response?: RouteHandler): Chainable<null>
+      /**
+       * Use `cy.route2()` to stub and intercept HTTP requests and responses.
+       *
+       * Note: this command is only available if you have set the `experimentalNetworkStubbing`
+       * configuration option to `true`.
+       *
+       * @see https://on.cypress.io/route2
+       * @example
+       *    cy.route2('GET', 'http://foo.com/fruits', ['apple', 'banana', 'cherry'])
+       */
       route2(method: string, url: RouteMatcher, response?: RouteHandler): Chainable<null>
     }
   }