cypress 5.1.0 → 5.5.0

package/types/net-stubbing.ts

@@ -1,13 +1,80 @@
-/**
- * HTTP request/response types.
- */
+// Copied from https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/methods/index.d.ts
+type Method =
+    | 'ACL'
+    | 'BIND'
+    | 'CHECKOUT'
+    | 'CONNECT'
+    | 'COPY'
+    | 'DELETE'
+    | 'GET'
+    | 'HEAD'
+    | 'LINK'
+    | 'LOCK'
+    | 'M-SEARCH'
+    | 'MERGE'
+    | 'MKACTIVITY'
+    | 'MKCALENDAR'
+    | 'MKCOL'
+    | 'MOVE'
+    | 'NOTIFY'
+    | 'OPTIONS'
+    | 'PATCH'
+    | 'POST'
+    | 'PROPFIND'
+    | 'PROPPATCH'
+    | 'PURGE'
+    | 'PUT'
+    | 'REBIND'
+    | 'REPORT'
+    | 'SEARCH'
+    | 'SOURCE'
+    | 'SUBSCRIBE'
+    | 'TRACE'
+    | 'UNBIND'
+    | 'UNLINK'
+    | 'UNLOCK'
+    | 'UNSUBSCRIBE'
+    | 'acl'
+    | 'bind'
+    | 'checkout'
+    | 'connect'
+    | 'copy'
+    | 'delete'
+    | 'get'
+    | 'head'
+    | 'link'
+    | 'lock'
+    | 'm-search'
+    | 'merge'
+    | 'mkactivity'
+    | 'mkcalendar'
+    | 'mkcol'
+    | 'move'
+    | 'notify'
+    | 'options'
+    | 'patch'
+    | 'post'
+    | 'propfind'
+    | 'proppatch'
+    | 'purge'
+    | 'put'
+    | 'rebind'
+    | 'report'
+    | 'search'
+    | 'source'
+    | 'subscribe'
+    | 'trace'
+    | 'unbind'
+    | 'unlink'
+    | 'unlock'
+    | 'unsubscribe'
+
 export namespace CyHttpMessages {
   interface BaseMessage {
-    // as much stuff from `incomingmessage` as makes sense to serialize and send
     body?: any
     headers: { [key: string]: string }
     url: string
-    method?: string
+    method?: Method
     httpVersion?: string
   }
 
@@ -39,14 +106,39 @@ 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 {
+    /**
+     * Destroy the request and respond with a network error.
+     */
     destroy(): void
+    /**
+     * Control the response to this request.
+     * If a function is passed, the request will be sent outgoing, and the function will be called
+     * with the response from the upstream server.
+     * If a `StaticResponse` is passed, it will be used as the response, and no request will be made
+     * to the upstream server.
+     */
     reply(interceptor?: StaticResponse | HttpResponseInterceptor): void
+    /**
+     * Shortcut to reply to the request with a body and optional headers.
+     */
     reply(body: string | object, headers?: { [key: string]: string }): void
+    /**
+     * Shortcut to reply to the request with an HTTP status code and optional body and headers.
+     */
     reply(status: number, body?: string | object, headers?: { [key: string]: string }): void
-    redirect(location: string, statusCode: number): void
+    /**
+     * Respond to this request with a redirect to a new `location`.
+     * @param statusCode HTTP status code to redirect with. Default: 302
+     */
+    redirect(location: string, statusCode?: number): void
   }
 }
 
@@ -59,9 +151,19 @@ export interface DictMatcher<T> {
  */
 export type GlobPattern = string
 
+/**
+ * Interceptor for an HTTP request. If a Promise is returned, it will be awaited before passing the
+ * request to the next handler (if there is one), otherwise the request will be passed to the next
+ * handler synchronously.
+ */
 export type HttpRequestInterceptor = (req: CyHttpMessages.IncomingHttpRequest) => void | Promise<void>
 
-export type HttpResponseInterceptor = (res: CyHttpMessages.IncomingHttpResponse, send?: () => void) => void | Promise<void>
+/**
+ * Interceptor for an HTTP response. If a Promise is returned, it will be awaited before passing the
+ * request to the next handler (if there is one), otherwise the request will be passed to the next
+ * handler synchronously.
+ */
+export type HttpResponseInterceptor = (res: CyHttpMessages.IncomingHttpResponse) => void | Promise<void>
 
 /**
  * Matches a single number or any of an array of acceptable numbers.
@@ -125,23 +227,25 @@ export type RouteMatcherOptions = RouteMatcherOptionsGeneric<StringMatcher>
 
 export interface RouteMatcherOptionsGeneric<S> extends RouteMatcherCompatOptions {
   /**
-   * Match HTTP basic authentication.
+   * Match against the username and password used in HTTP Basic authentication.
    */
   auth?: { username: S, password: S }
   /**
-   * Match client request headers.
+   * Match against HTTP headers on the request.
    */
   headers?: DictMatcher<S>
   /**
-   * Match based on requested hostname.
+   * Match against the requested HTTP hostname.
    */
   hostname?: S
   /**
-   * Match requests served via HTTPS only.
+   * If 'true', only HTTPS requests will be matched.
+   * If 'false', only HTTP requests will be matched.
    */
   https?: boolean
   /**
-   * @default 'GET'
+   * Match against the request's HTTP method.
+   * @default '*'
    */
   method?: S
   /**
@@ -153,7 +257,8 @@ export interface RouteMatcherOptionsGeneric<S> extends RouteMatcherCompatOptions
    */
   pathname?: S
   /**
-   * Match based on requested port.
+   * Match based on requested port, or pass an array of ports
+   * to match against any in that array.
    */
   port?: NumberMatcher
   /**
@@ -161,7 +266,9 @@ export interface RouteMatcherOptionsGeneric<S> extends RouteMatcherCompatOptions
    */
   query?: DictMatcher<S>
   /**
-   * Match based on full request URL.
+   * Match against the full request URL.
+   * If a string is passed, it will be used as a substring match,
+   * not an equality match.
    */
   url?: S
 }
@@ -173,29 +280,42 @@ 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> & {
+  /**
+   * Milliseconds to delay before the response is sent.
+   */
+ delayMs?: number
+}
 
 export interface GenericStaticResponse<Fixture, Body> {
   /**
-   * If set, serve a fixture as the response body.
+   * Serve a fixture as the response body.
    */
   fixture?: Fixture
   /**
-   * If set, serve a static string/JSON object as the response body.
+   * Serve a static string/JSON object as the response body.
    */
   body?: Body
   /**
+   * HTTP headers to accompany the response.
    * @default {}
    */
   headers?: { [key: string]: string }
   /**
+   * The HTTP status code to send.
    * @default 200
    */
   statusCode?: number
   /**
-   * 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.
+   * If 'forceNetworkError' is truthy, Cypress will destroy the browser connection
+   * and send no response. Useful for simulating a server that is not reachable.
+   * Must not be set in combination with other options.
    */
   forceNetworkError?: boolean
+  /**
+   * Kilobits per second to send 'body'.
+   */
+  throttleKbps?: number
 }
 
 /**
@@ -206,8 +326,38 @@ 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>
-      route2(method: string, 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: Method, url: RouteMatcher, response?: RouteHandler): Chainable<null>
     }
   }
 }