misc: convert server/lib/modes files to ts + add more cli options to Cloud terminal error outputs (#31211)

* chore: convert server/lib/modes files to ts

* update snapshots

* add back require

* fix call to errors.warning

* Add changelog entry.

Author: jennifer-shehane

cli/CHANGELOG.md

@@ -3,6 +3,10 @@
 
 _Released 3/11/2025 (PENDING)_
 
+**Misc:**
+
+- Additional CLI options will be displayed in the terminal for some Cloud error messages. Addressed in [#31211](https://github.com/cypress-io/cypress/pull/31211).
+
 **Dependency Updates:**
 
 - Upgraded `cli-table3` from `0.5.1` to `0.6.5`. Addressed in [#31166](https://github.com/cypress-io/cypress/pull/31166).

packages/errors/src/errors.ts

@@ -240,7 +240,7 @@ export const AllCypressErrors = {
 
         https://on.cypress.io/stale-run`
   },
-  CLOUD_ALREADY_COMPLETE: (props: {runUrl: string}) => {
+  CLOUD_ALREADY_COMPLETE: (props: {runUrl: string, tags: string, group: string, parallel: string, ciBuildId: string}) => {
     return errTemplate`\
         The run you are attempting to access is already complete and will not accept new groups.
 
@@ -257,7 +257,7 @@ export const AllCypressErrors = {
 
         https://on.cypress.io/already-complete`
   },
-  CLOUD_PARALLEL_REQUIRED: (arg1: {runUrl: string}) => {
+  CLOUD_PARALLEL_REQUIRED: (arg1: {tags: string, group: string, runUrl: string, ciBuildId: string }) => {
     return errTemplate`\
         You did not pass the ${fmt.flag(`--parallel`)} flag, but this run's group was originally created with the --parallel flag.
 
@@ -274,13 +274,14 @@ export const AllCypressErrors = {
 
         https://on.cypress.io/parallel-required`
   },
-  CLOUD_PARALLEL_DISALLOWED: (arg1: {runUrl: string}) => {
+  CLOUD_PARALLEL_DISALLOWED: (arg1: {tags: string, group: string, runUrl: string, ciBuildId: string}) => {
     return errTemplate`\
         You passed the ${fmt.flag(`--parallel`)} flag, but this run group was originally created without the --parallel flag.
 
         The existing run is: ${fmt.url(arg1.runUrl)}
 
         ${fmt.listFlags(arg1, {
+      tags: '--tag',
       group: '--group',
       parallel: '--parallel',
       ciBuildId: '--ciBuildId',
@@ -290,7 +291,7 @@ export const AllCypressErrors = {
 
         https://on.cypress.io/parallel-disallowed`
   },
-  CLOUD_PARALLEL_GROUP_PARAMS_MISMATCH: (arg1: {runUrl: string, parameters: any, payload: any }) => {
+  CLOUD_PARALLEL_GROUP_PARAMS_MISMATCH: (arg1: {group: string, runUrl: string, ciBuildId: string, parameters: any, payload: any }) => {
     let params: any = arg1.parameters
 
     if (arg1.payload?.differentParams) {
@@ -344,7 +345,7 @@ export const AllCypressErrors = {
 
         https://on.cypress.io/parallel-group-params-mismatch`
   },
-  CLOUD_RUN_GROUP_NAME_NOT_UNIQUE: (arg1: {runUrl: string, ciBuildId?: string | null}) => {
+  CLOUD_RUN_GROUP_NAME_NOT_UNIQUE: (arg1: {group: string, runUrl: string, ciBuildId?: string | null}) => {
     return errTemplate`\
         You passed the ${fmt.flag(`--group`)} flag, but this group name has already been used for this run.
 
@@ -370,7 +371,7 @@ export const AllCypressErrors = {
 
       ${fmt.off(arg1.link)}`
   },
-  CLOUD_AUTO_CANCEL_MISMATCH: (arg1: {runUrl: string}) => {
+  CLOUD_AUTO_CANCEL_MISMATCH: (arg1: {runUrl: string, tags: string, group: string, parallel: string, ciBuildId: string, autoCancelAfterFailures: string }) => {
     return errTemplate`\
         You passed the ${fmt.flag(`--auto-cancel-after-failures`)} flag, but this run originally started with a different value for the ${fmt.flag(`--auto-cancel-after-failures`)} flag.
 
@@ -1397,7 +1398,6 @@ export const AllCypressErrors = {
       https://on.cypress.io/test-retries
       `
   },
-  // TODO: test this
   INVALID_CONFIG_OPTION: (arg1: string[]) => {
     const phrase = arg1.length > 1 ? 'options are' : 'option is'
 
@@ -1886,7 +1886,7 @@ export const AllCypressErrors = {
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const _typeCheck: Record<keyof AllCypressErrorObj, (...args: any[]) => ErrTemplateResult> = AllCypressErrors
 
-type AllCypressErrorObj = typeof AllCypressErrors
+export type AllCypressErrorObj = typeof AllCypressErrors
 
 export type AllCypressErrorNames = keyof typeof AllCypressErrors
 

packages/server/__snapshots__/cypress_spec.js

@@ -2,6 +2,8 @@ exports['RECORD_PARAMS_WITHOUT_RECORDING-ciBuildId 1'] = `
 You passed the --ci-build-id, --group, --tag, --parallel, or --auto-cancel-after-failures flag without also passing the --record flag.
 
 The --ci-build-id flag you passed was: ciBuildId123
+The --parallel flag you passed was: undefined
+The --auto-cancel-after-failures flag you passed was: undefined
 
 These flags can only be used when recording to Cypress Cloud.
 
@@ -22,6 +24,8 @@ exports['RECORD_PARAMS_WITHOUT_RECORDING-group 1'] = `
 You passed the --ci-build-id, --group, --tag, --parallel, or --auto-cancel-after-failures flag without also passing the --record flag.
 
 The --group flag you passed was: e2e-tests
+The --parallel flag you passed was: undefined
+The --auto-cancel-after-failures flag you passed was: undefined
 
 These flags can only be used when recording to Cypress Cloud.
 
@@ -32,6 +36,7 @@ exports['RECORD_PARAMS_WITHOUT_RECORDING-parallel 1'] = `
 You passed the --ci-build-id, --group, --tag, --parallel, or --auto-cancel-after-failures flag without also passing the --record flag.
 
 The --parallel flag you passed was: true
+The --auto-cancel-after-failures flag you passed was: undefined
 
 These flags can only be used when recording to Cypress Cloud.
 
@@ -43,6 +48,7 @@ You passed the --ci-build-id, --group, --tag, --parallel, or --auto-cancel-after
 
 The --group flag you passed was: electron-smoke-tests
 The --parallel flag you passed was: true
+The --auto-cancel-after-failures flag you passed was: undefined
 
 These flags can only be used when recording to Cypress Cloud.
 
@@ -53,6 +59,7 @@ exports['INDETERMINATE_CI_BUILD_ID-group 1'] = `
 You passed the --group or --parallel flag but we could not automatically determine or generate a ciBuildId.
 
 The --group flag you passed was: e2e-tests
+The --parallel flag you passed was: undefined
 
 In order to use either of these features a ciBuildId must be determined.
 
@@ -221,6 +228,7 @@ You passed the --parallel flag, but this run group was originally created withou
 
 The existing run is: https://cloud.cypress.io/runs/12345
 
+The --tag flag you passed was: 
 The --group flag you passed was: electron-smoke-tests
 The --ciBuildId flag you passed was: ciBuildId123
 
@@ -275,6 +283,9 @@ https://on.cypress.io/stale-run
 exports['RECORD_PARAMS_WITHOUT_RECORDING-tag 1'] = `
 You passed the --ci-build-id, --group, --tag, --parallel, or --auto-cancel-after-failures flag without also passing the --record flag.
 
+The --parallel flag you passed was: undefined
+The --auto-cancel-after-failures flag you passed was: undefined
+
 These flags can only be used when recording to Cypress Cloud.
 
 https://on.cypress.io/record-params-without-recording
@@ -422,6 +433,7 @@ https://on.cypress.io/record-params-without-recording
 exports['RECORD_PARAMS_WITHOUT_RECORDING-auto-cancel-after-failures 1'] = `
 You passed the --ci-build-id, --group, --tag, --parallel, or --auto-cancel-after-failures flag without also passing the --record flag.
 
+The --parallel flag you passed was: undefined
 The --auto-cancel-after-failures flag you passed was: 4
 
 These flags can only be used when recording to Cypress Cloud.

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

@@ -239,7 +239,10 @@ const isRetriableError = (err) => {
 
 export type CreateRunOptions = {
   projectRoot: string
-  ci: string
+  ci: {
+    params: string
+    provider: string
+  }
   ciBuildId: string
   projectId: string
   recordKey: string
@@ -253,6 +256,7 @@ export type CreateRunOptions = {
   testingType: 'e2e' | 'component'
   timeout?: number
   project: ProjectBase
+  autoCancelAfterFailures?: number | undefined
 }
 
 type CreateRunResponse = {

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

@@ -68,7 +68,7 @@ const toUploadReportPayload = (acc: {
 type UploadArtifactOptions = {
   protocolManager?: ProtocolManager
   videoUploadUrl?: string
-  video?: string // filepath to the video artifact
+  video?: string | null // filepath to the video artifact
   screenshots?: {
     screenshotId: string
     path: string

packages/server/lib/cypress.js packages/server/lib/cypress.ts

@@ -9,16 +9,17 @@ require('./environment')
 // essentially do it all again when we boot the correct
 // mode.
 
-const Promise = require('bluebird')
-const debug = require('debug')('cypress:server:cypress')
-const { getPublicConfigKeys } = require('@packages/config')
-const argsUtils = require('./util/args')
-const { telemetry } = require('@packages/telemetry')
-const { getCtx, hasCtx } = require('@packages/data-context')
-
-const warning = (code, args) => {
-  return require('./errors').warning(code, args)
-}
+import Promise from 'bluebird'
+import Debug from 'debug'
+import { getPublicConfigKeys } from '@packages/config'
+import argsUtils from './util/args'
+import { telemetry } from '@packages/telemetry'
+import { getCtx, hasCtx } from '@packages/data-context'
+import { warning as errorsWarning } from './errors'
+
+const debug = Debug('cypress:server:cypress')
+
+type Mode = 'exit' | 'info' | 'interactive' | 'pkg' | 'record' | 'results' | 'run' | 'smokeTest' | 'version' | 'returnPkg' | 'exitWithCode'
 
 const exit = async (code = 0) => {
   // TODO: we shouldn't have to do this
@@ -27,7 +28,7 @@ const exit = async (code = 0) => {
   debug('about to exit with code', code)
 
   if (hasCtx()) {
-    await getCtx().lifecycleManager.mainProcessWillDisconnect().catch((err) => {
+    await getCtx().lifecycleManager.mainProcessWillDisconnect().catch((err: any) => {
       debug('mainProcessWillDisconnect errored with: ', err)
     })
   }
@@ -37,14 +38,14 @@ const exit = async (code = 0) => {
   span?.setAttribute('exitCode', code)
   span?.end()
 
-  await telemetry.shutdown().catch((err) => {
+  await telemetry.shutdown().catch((err: any) => {
     debug('telemetry shutdown errored with: ', err)
   })
 
   return process.exit(code)
 }
 
-const showWarningForInvalidConfig = (options) => {
+const showWarningForInvalidConfig = (options: any) => {
   const publicConfigKeys = getPublicConfigKeys()
   const invalidConfigOptions = require('lodash').keys(options.config).reduce((invalid, option) => {
     if (!publicConfigKeys.find((configKey) => configKey === option)) {
@@ -55,15 +56,17 @@ const showWarningForInvalidConfig = (options) => {
   }, [])
 
   if (invalidConfigOptions.length && options.invokedFromCli) {
-    return warning('INVALID_CONFIG_OPTION', invalidConfigOptions)
+    return errorsWarning('INVALID_CONFIG_OPTION', invalidConfigOptions)
   }
+
+  return undefined
 }
 
 const exit0 = () => {
   return exit(0)
 }
 
-const exitErr = (err) => {
+const exitErr = (err: any) => {
   // log errors to the console
   // and potentially raygun
   // and exit with 1
@@ -77,12 +80,12 @@ const exitErr = (err) => {
   })
 }
 
-module.exports = {
+export = {
   isCurrentlyRunningElectron () {
     return require('./util/electron-app').isRunning()
   },
 
-  runElectron (mode, options) {
+  runElectron (mode: Mode, options: any) {
     // wrap all of this in a promise to force the
     // promise interface - even if it doesn't matter
     // in dev mode due to cp.spawn
@@ -95,7 +98,7 @@ module.exports = {
         // if we weren't invoked from the CLI
         // then display a warning to the user
         if (!options.invokedFromCli) {
-          warning('INVOKED_BINARY_OUTSIDE_NPM_MODULE')
+          errorsWarning('INVOKED_BINARY_OUTSIDE_NPM_MODULE')
         }
 
         debug('running Electron currently')
@@ -107,7 +110,7 @@ module.exports = {
         debug('starting Electron')
         const cypressElectron = require('@packages/electron')
 
-        const fn = (code) => {
+        const fn = (code: number) => {
           // juggle up the totalFailed since our outer
           // promise is expecting this object structure
           debug('electron finished with', code)
@@ -131,7 +134,7 @@ module.exports = {
     })
   },
 
-  start (argv = []) {
+  start (argv: any = []) {
     debug('starting cypress with argv %o', argv)
 
     // if the CLI passed "--" somewhere, we need to remove it
@@ -144,7 +147,7 @@ module.exports = {
       options = argsUtils.toObject(argv)
 
       showWarningForInvalidConfig(options)
-    } catch (argumentsError) {
+    } catch (argumentsError: any) {
       debug('could not parse CLI arguments: %o', argv)
 
       // note - this is promise-returned call
@@ -153,6 +156,7 @@ module.exports = {
 
     debug('from argv %o got options %o', argv, options)
 
+    // @ts-expect-error TODO: Fix type that says attachRecordKey is not a function
     telemetry.exporter()?.attachRecordKey(options.key)
 
     if (options.headless) {
@@ -202,14 +206,14 @@ module.exports = {
     })
   },
 
-  startInMode (mode, options) {
+  startInMode (mode: Mode, options: any) {
     debug('starting in mode %s with options %o', mode, options)
 
     switch (mode) {
       case 'version':
         return require('./modes/pkg')(options)
         .get('version')
-        .then((version) => {
+        .then((version: any) => {
           return console.log(version) // eslint-disable-line no-console
         }).then(exit0)
         .catch(exitErr)
@@ -221,7 +225,7 @@ module.exports = {
 
       case 'smokeTest':
         return this.runElectron(mode, options)
-        .then((pong) => {
+        .then((pong: any) => {
           if (!this.isCurrentlyRunningElectron()) {
             return pong
           }
@@ -236,7 +240,7 @@ module.exports = {
 
       case 'returnPkg':
         return require('./modes/pkg')(options)
-        .then((pkg) => {
+        .then((pkg: any) => {
           return console.log(JSON.stringify(pkg)) // eslint-disable-line no-console
         }).then(exit0)
         .catch(exitErr)
@@ -250,7 +254,7 @@ module.exports = {
         // run headlessly and exit
         // with num of totalFailed
         return this.runElectron(mode, options)
-        .then((results) => {
+        .then((results: any) => {
           if (results.runs) {
             const isCanceled = results.runs.filter((run) => run.skippedSpec).length
 

packages/server/lib/modes/exit.js

@@ -0,0 +1,8 @@
+import { toNumber } from 'lodash'
+import Promise from 'bluebird'
+
+export = (options) => {
+  return Promise.try(() => {
+    return toNumber(options.exitWithCode)
+  })
+}

packages/server/lib/modes/exit.ts

@@ -1,13 +1,15 @@
 /* eslint-disable no-console */
-const debug = require('debug')('cypress:server:info')
-const launcher = require('@packages/launcher')
-const pluralize = require('pluralize')
-const { stripIndent } = require('common-tags')
-const browserUtils = require('../browsers/utils')
-const _ = require('lodash')
-const chalk = require('chalk')
-const { fs } = require('../util/fs')
-
+import Debug from 'debug'
+import { detect as launcherDetect } from '@packages/launcher'
+import pluralize from 'pluralize'
+import { stripIndent } from 'common-tags'
+import browserUtils from '../browsers/utils'
+import _ from 'lodash'
+import chalk from 'chalk'
+import { fs } from '../util/fs'
+import type { FoundBrowser } from '@packages/types/src/browser'
+
+const debug = Debug('cypress:server:info')
 // color for numbers and short values
 const n = chalk.green
 // color for paths
@@ -21,7 +23,7 @@ const link = chalk.blue.underline
  * If the list has at least 1 item, picks a random item
  * and returns it AND the remaining items.
  */
-const pickRandomItem = (list) => {
+const pickRandomItem = (list: any) => {
   if (!list.length) {
     return {
       item: null,
@@ -40,7 +42,7 @@ const pickRandomItem = (list) => {
 // Usually the full browser name to pass via --browser
 // is <name>:<channel>. If the channel is stable, you
 // can just do "--browser <name>"
-const formBrowserName = (browser) => {
+const formBrowserName = (browser: FoundBrowser) => {
   if (browser.channel === 'stable') {
     return browser.name
   }
@@ -51,9 +53,9 @@ const formBrowserName = (browser) => {
 // for each browser computes the profile folder
 // and checks if the folder exists. If exists,
 // adds it to the browser object as a property
-const addProfilePath = async (browsers = []) => {
+const addProfilePath = async (browsers: FoundBrowser[] = []) => {
   for (const browser of browsers) {
-    const profilePath = browserUtils.getBrowserPath(browser)
+    const profilePath: string = browserUtils.getBrowserPath(browser)
 
     debug('checking profile path %s for browser %s:%s', profilePath, browser.name, browser.channel)
     try {
@@ -71,11 +73,11 @@ const addProfilePath = async (browsers = []) => {
   return browsers
 }
 
-const print = (browsers = []) => {
+const print = (browsers: FoundBrowser[] = []) => {
   console.log('Displaying Cypress info...')
   console.log('')
   if (browsers.length) {
-    console.log('Detected %s %s installed:', n(browsers.length), pluralize('browser', browsers.length))
+    console.log('Detected %s %s installed:', n(`${browsers.length}`), pluralize('browser', browsers.length))
   } else {
     console.log('Detected no known browsers installed')
   }
@@ -126,7 +128,7 @@ const print = (browsers = []) => {
 }
 
 const info = () => {
-  return launcher.detect()
+  return launcherDetect()
   .then(addProfilePath)
   .then(print)
 }

packages/server/lib/modes/info.js packages/server/lib/modes/info.ts

@@ -0,0 +1,6 @@
+import Promise from 'bluebird'
+import pkg from '@packages/root'
+
+export = () => {
+  return Promise.resolve(pkg)
+}

packages/server/lib/modes/pkg.js

@@ -5,10 +5,10 @@ import type { FoundBrowser, SpecWithRelativeRoot } from '@packages/types'
 import path from 'path'
 
 import type { Cfg } from '../project-base'
+import type { ScreenshotMetadata } from './run'
 
 type dateTimeISO = string
 type ms = number
-type pixels = number
 
 interface TestError {
   message: string
@@ -48,20 +48,12 @@ interface HookInformation {
   body: string
 }
 
-interface ScreenshotInformation {
-  height: pixels
-  name: string
-  path: string
-  takenAt: dateTimeISO
-  width: pixels
-}
-
-interface RunResult {
+export interface RunResult {
   error: string | null
   hooks: HookInformation[]
   reporter: string
   reporterStats: object
-  screenshots: ScreenshotInformation[]
+  screenshots: ScreenshotMetadata[]
   skippedSpec: boolean
   spec: SpecWithRelativeRoot
   stats: {

packages/server/lib/modes/pkg.ts

@@ -32,7 +32,8 @@ import { CDPFailedToStartFirefox } from '../browsers/firefox'
 import type { CypressError } from '@packages/errors'
 
 type SetScreenshotMetadata = (data: TakeScreenshotProps) => void
-type ScreenshotMetadata = ReturnType<typeof screenshotMetadata>
+export type ScreenshotMetadata = ReturnType<typeof screenshotMetadata>
+
 type TakeScreenshotProps = any
 type RunEachSpec = any
 type BeforeSpecRun = any
@@ -753,7 +754,7 @@ async function waitForTestsToFinishRunning (options: { project: Project, screens
   return results
 }
 
-function screenshotMetadata (data, resp) {
+function screenshotMetadata (data: any, resp: any) {
   return {
     screenshotId: random.id(),
     name: data.name || null,
@@ -1006,7 +1007,7 @@ async function runSpec (config, spec: SpecWithRelativeRoot, options: { project:
   return { results }
 }
 
-interface ReadyOptions {
+export interface ReadyOptions {
   autoCancelAfterFailures: number | false
   browser: string
   browsers?: FoundBrowser[]

packages/server/lib/modes/record.js packages/server/lib/modes/record.ts

@@ -1,5 +1,5 @@
-module.exports = {
-  run (options) {
+export = {
+  run (options: any) {
     // eslint-disable-next-line no-console
     console.log(options.pong)