feat: Improve UX when Test Replay upload fails due to slow upload

cli/CHANGELOG.md

@@ -3,6 +3,10 @@
 
 _Released 9/10/2024 (PENDING)_
 
+**Features:**
+
+- Cypress now displays more actionable errors when a Test Replay upload takes too long, and more verbose messages when uncategorized errors occur during the upload process. Addressed in [#30235](https://github.com/cypress-io/cypress/pull/30235).
+
 **Dependency Updates:**
 
 - Update `@cypress/request` from `3.0.1` to `3.0.4`. Addressed in [#30194](https://github.com/cypress-io/cypress/pull/30194).

packages/errors/src/errors.ts

@@ -574,6 +574,17 @@ export const AllCypressErrors = {
         This error will not affect or change the exit code.
     `
   },
+  CLOUD_PROTOCOL_UPLOAD_UNKNOWN_ERROR: (error: Error) => {
+    return errTemplate`\
+        Warning: We encountered an error while upload the Test Replay recording of this spec.
+
+        These reults will not display Test Replay recordings.
+
+        This error will not affect or change the exit code.
+
+        ${fmt.highlightSecondary(error)}
+    `
+  },
   CLOUD_PROTOCOL_UPLOAD_HTTP_FAILURE: (error: Error & { url: string, status: number, statusText: string, responseBody: string }) => {
     return errTemplate`\
         Warning: We encountered an HTTP error while uploading the Test Replay recording for this spec.
@@ -586,7 +597,7 @@ export const AllCypressErrors = {
 
         ${fmt.highlightTertiary(error.responseBody)}`
   },
-  CLOUD_PROTOCOL_UPLOAD_NEWORK_FAILURE: (error: Error & { url: string }) => {
+  CLOUD_PROTOCOL_UPLOAD_NETWORK_FAILURE: (error: Error & { url: string }) => {
     return errTemplate`\
         Warning: We encountered a network error while uploading the Test Replay recording for this spec.
 
@@ -598,14 +609,29 @@ export const AllCypressErrors = {
 
         ${fmt.highlightSecondary(error)}`
   },
+  CLOUD_PROTOCOL_UPLOAD_STREAM_STALL_FAILURE: (error: Error & { chunkSizeKB: number, maxActivityDwellTime: number }) => {
+    const kbpsThreshold = (error.chunkSizeKB * 8) / (error.maxActivityDwellTime / 1000)
+
+    return errTemplate`\
+        Warning: We encountered slow network conditions while uploading the Test Replay recording for this spec.
+
+        The upload transfer rate fell below ${fmt.highlightSecondary(`${kbpsThreshold}kbps`)} over a sampling period of ${fmt.highlightSecondary(`${error.maxActivityDwellTime}ms`)}.
+
+        If this error occurs often, the sampling period may be configured by setting the ${fmt.highlightSecondary('CYPRESS_PROTOCOL_UPLOAD_SAMPLING_INTERVAL')} environment variable to a higher value than ${fmt.stringify(error.maxActivityDwellTime)}.
+
+        To prevent long CI executing durations, this Test Replay recording will not be uploaded.
+
+        The results for this spec will not display Test Replay recordings.
+    `
+  },
   CLOUD_PROTOCOL_UPLOAD_AGGREGATE_ERROR: (error: {
     errors: (Error & { kind?: 'SystemError', url: string } | Error & { kind: 'HttpError', url: string, status?: string, statusText?: string, responseBody?: string })[]
   }) => {
     if (error.errors.length === 1) {
       const firstError = error.errors[0]
 
       if (firstError?.kind === 'SystemError') {
-        return AllCypressErrors.CLOUD_PROTOCOL_UPLOAD_NEWORK_FAILURE(firstError as Error & { url: string })
+        return AllCypressErrors.CLOUD_PROTOCOL_UPLOAD_NETWORK_FAILURE(firstError as Error & { url: string })
       }
 
       return AllCypressErrors.CLOUD_PROTOCOL_UPLOAD_HTTP_FAILURE(error.errors[0] as Error & { url: string, status: number, statusText: string, responseBody: string})

packages/errors/test/unit/visualSnapshotErrors_spec.ts

@@ -685,7 +685,7 @@ describe('visual error templates', () => {
         default: [err],
       }
     },
-    CLOUD_PROTOCOL_UPLOAD_NEWORK_FAILURE: () => {
+    CLOUD_PROTOCOL_UPLOAD_NETWORK_FAILURE: () => {
       // @ts-expect-error
       const err: Error & { url: string } = makeErr()
 
@@ -695,6 +695,17 @@ describe('visual error templates', () => {
         default: [err],
       }
     },
+    CLOUD_PROTOCOL_UPLOAD_STREAM_STALL_FAILURE: () => {
+      // @ts-expect-error
+      const err: Error & { chunkSizeKB: number, maxActivityDwellTime: number } = new Error('stream stall')
+
+      err.chunkSizeKB = 64
+      err.maxActivityDwellTime = 5000
+
+      return {
+        default: [err],
+      }
+    },
     CLOUD_PROTOCOL_UPLOAD_AGGREGATE_ERROR: () => {
       // @ts-expect-error
       const aggregateError: Error & { errors: any[] } = makeErr()
@@ -719,6 +730,13 @@ describe('visual error templates', () => {
         withSystemError: [aggregateErrorWithSystemError],
       }
     },
+    CLOUD_PROTOCOL_UPLOAD_UNKNOWN_ERROR: () => {
+      const error = new Error('some message')
+
+      return {
+        default: [error],
+      }
+    },
     CLOUD_RECORD_KEY_NOT_VALID: () => {
       return {
         default: ['record-key-123', 'project-id-123'],

packages/server/lib/cloud/api/put_protocol_artifact.ts

@@ -7,23 +7,18 @@ import { putFetch, ParseKinds } from '../network/put_fetch'
 import { isRetryableError } from '../network/is_retryable_error'
 const debug = Debug('cypress:server:cloud:api:protocol-artifact')
 
-// the upload will get canceled if the stream pipeline
-// stalls (does not push data to the `fetch` sink) for more
-// than 5 seconds
-const MAX_ACTIVITY_DWELL_TIME = 5000
-
 export const _delay = linearDelay(500)
 
 export const putProtocolArtifact = asyncRetry(
-  async (artifactPath: string, maxFileSize: number, destinationUrl: string) => {
+  async (artifactPath: string, maxFileSize: number, destinationUrl: string, uploadMonitorSamplingRate: number) => {
     debug(`Atttempting to upload Test Replay archive from ${artifactPath} to ${destinationUrl})`)
     const { size } = await fsAsync.stat(artifactPath)
 
     if (size > maxFileSize) {
       throw new Error(`Spec recording too large: artifact is ${size} bytes, limit is ${maxFileSize} bytes`)
     }
 
-    const activityMonitor = new StreamActivityMonitor(MAX_ACTIVITY_DWELL_TIME)
+    const activityMonitor = new StreamActivityMonitor(uploadMonitorSamplingRate)
     const fileStream = fs.createReadStream(artifactPath)
     const controller = activityMonitor.getController()
 

packages/server/lib/cloud/artifacts/print_protocol_upload_error.ts

@@ -0,0 +1,24 @@
+import { HttpError } from '../network/http_error'
+import { SystemError } from '../network/system_error'
+import { StreamStalledError } from '../upload/stream_stalled_error'
+import Debug from 'debug'
+import * as errors from '../../errors'
+
+const debug = Debug('cypress:server:cloud:artifacts')
+
+export const printProtocolUploadError = (error: Error) => {
+  debug('protocol error: %O', error)
+  // eslint-disable-next-line no-console
+  console.log('')
+  if ((error as AggregateError).errors) {
+    errors.warning('CLOUD_PROTOCOL_UPLOAD_AGGREGATE_ERROR', error as AggregateError)
+  } else if (HttpError.isHttpError(error)) {
+    errors.warning('CLOUD_PROTOCOL_UPLOAD_HTTP_FAILURE', error)
+  } else if (SystemError.isSystemError(error)) {
+    errors.warning('CLOUD_PROTOCOL_UPLOAD_NETWORK_FAILURE', error)
+  } else if (StreamStalledError.isStreamStalledError(error)) {
+    errors.warning('CLOUD_PROTOCOL_UPLOAD_STREAM_STALL_FAILURE', error)
+  } else {
+    errors.warning('CLOUD_PROTOCOL_UPLOAD_UNKNOWN_ERROR', error)
+  }
+}

packages/server/lib/cloud/artifacts/upload_artifacts.ts

@@ -12,7 +12,7 @@ import { createScreenshotArtifactBatch } from './screenshot_artifact'
 import { createVideoArtifact } from './video_artifact'
 import { createProtocolArtifact, composeProtocolErrorReportFromOptions } from './protocol_artifact'
 import { HttpError } from '../network/http_error'
-import { SystemError } from '../network/system_error'
+import { printProtocolUploadError } from './print_protocol_upload_error'
 
 const debug = Debug('cypress:server:cloud:artifacts')
 
@@ -230,20 +230,7 @@ export const uploadArtifacts = async (options: UploadArtifactOptions) => {
     if (postUploadProtocolFatalError && postUploadProtocolFatalError.captureMethod === 'uploadCaptureArtifact') {
       const error = postUploadProtocolFatalError.error
 
-      debug('protocol error: %O', error)
-      if ((error as AggregateError).errors) {
-        // eslint-disable-next-line no-console
-        console.log('')
-        errors.warning('CLOUD_PROTOCOL_UPLOAD_AGGREGATE_ERROR', postUploadProtocolFatalError.error as AggregateError)
-      } else if (HttpError.isHttpError(error)) {
-        // eslint-disable-next-line no-console
-        console.log('')
-        errors.warning('CLOUD_PROTOCOL_UPLOAD_HTTP_FAILURE', error)
-      } else if (SystemError.isSystemError(error)) {
-        // eslint-disable-next-line no-console
-        console.log('')
-        errors.warning('CLOUD_PROTOCOL_UPLOAD_NEWORK_FAILURE', error)
-      }
+      printProtocolUploadError(error)
     }
 
     // there is no upload results entry for protocol if we did not attempt to upload protocol due to a fatal error

packages/server/lib/cloud/protocol.ts

@@ -26,6 +26,8 @@ const DELETE_DB = !process.env.CYPRESS_LOCAL_PROTOCOL_PATH
 
 export const DB_SIZE_LIMIT = 5000000000
 
+export const DEFAULT_STREAM_SAMPLING_INTERVAL = 5000
+
 const dbSizeLimit = () => {
   return env.get('CYPRESS_INTERNAL_SYSTEM_TESTS') === '1' ?
     200 : DB_SIZE_LIMIT
@@ -320,7 +322,11 @@ export class ProtocolManager implements ProtocolManagerShape {
     debug(`uploading %s to %s with a file size of %s`, filePath, uploadUrl, fileSize)
 
     try {
-      await putProtocolArtifact(filePath, dbSizeLimit(), uploadUrl)
+      const samplingInterval = process.env.CYPRESS_PROTOCOL_UPLOAD_SAMPLING_INTERVAL ?
+        parseInt(process.env.CYPRESS_PROTOCOL_UPLOAD_SAMPLING_INTERVAL, 10) :
+        this._protocol.uploadStallSamplingInterval ?? DEFAULT_STREAM_SAMPLING_INTERVAL
+
+      await putProtocolArtifact(filePath, dbSizeLimit(), uploadUrl, samplingInterval)
 
       return {
         fileSize,

packages/server/lib/cloud/upload/stream_activity_monitor.ts

@@ -1,15 +1,9 @@
 import Debug from 'debug'
 import { Transform, Readable } from 'stream'
-
+import { StreamStalledError } from './stream_stalled_error'
 const debug = Debug('cypress:server:cloud:stream-activity-monitor')
 const debugVerbose = Debug('cypress-verbose:server:cloud:stream-activity-monitor')
 
-export class StreamStalledError extends Error {
-  constructor (maxActivityDwellTime: number) {
-    super(`Stream stalled: no activity detected in the previous ${maxActivityDwellTime}ms`)
-  }
-}
-
 /**
  * `StreamActivityMonitor` encapsulates state with regard to monitoring a stream for flow
  * failure states. Given a maxActivityDwellTime, this class can `monitor` a Node Readable
@@ -36,6 +30,9 @@ export class StreamStalledError extends Error {
  * }
  *
  */
+
+const DEFAULT_FS_READSTREAM_CHUNK_SIZE = 64 * 1024 // Kilobytes
+
 export class StreamActivityMonitor {
   private streamMonitor: Transform | undefined
   private activityTimeout: NodeJS.Timeout | undefined
@@ -81,7 +78,7 @@ export class StreamActivityMonitor {
     debug('marking activity interval')
     clearTimeout(this.activityTimeout)
     this.activityTimeout = setTimeout(() => {
-      this.controller?.abort(new StreamStalledError(this.maxActivityDwellTime))
+      this.controller?.abort(new StreamStalledError(this.maxActivityDwellTime, DEFAULT_FS_READSTREAM_CHUNK_SIZE))
     }, this.maxActivityDwellTime)
   }
 }