chore: refactor `cypress/cli` to TypeScript #32063

AtofStryker · 2025-07-21T18:46:25Z

Closes N/A

Additional details

Converts the Cypress CLI from JavaScript to TypeScript. This is to help with our eventual goal of moving to an ESM based repository, which is much easier when compiling to source. The files in the package have been migrated to TypeScript and now compile down to CommonJS (for now).

We still only ship the JavaScript files with the CLI

It's important with this migration to make sure there are NOT breaking changes to the CLI. This is confirmed below:

Loaded from CommonJS (in comparison with the `15.0.0` CLI)

Loaded from ESM (in comparison with the `15.0.0` CLI)

With this, it is easier to visualize that there isn't a breaking change to the CLI.

What is in scope for this PR

update all JavaScript files, source and test, to TypeScript
Allow mocha to run TypeScript tests with ts-node
Fully remove all require() statements and use ES6 style import statements
compile the TypeScript down to CommonJS
preserve existing public API to avoid breaking change

What is not in scope for this PR

improving/changing the build process inside the CLI
perfecting the types used by the CLI. Many types will be any
rewriting then/catch to async/await
improving existing tests or migrating test harness

Steps to test

How has the user experience changed?

This change should go unnoticed to the end user as it is just a refactor

PR Tasks

Have tests been added/updated?
Has a PR for user-facing changes been opened in cypress-documentation?
Have API changes been updated in the type definitions?

cypress · 2025-07-21T20:45:29Z

cypress Run #64974

Run Properties: Passed #64974 • c1b0126335: Merge branch 'chore/refactor_cli_to_ts' of github.com:cypress-io/cypress into ch...

Project	`cypress`
Branch Review	`chore/refactor_cli_to_ts`
Run status	`Passed #64974`
Run duration	`11m 07s`
Commit	`c1b0126335: Merge branch 'chore/refactor_cli_to_ts' of github.com:cypress-io/cypress into ch...`
Committer	`Bill Glesias`
View all properties for this run ↗︎

Test results
Failures	`0`
Flaky	`0`
Pending	`1`
Skipped	`0`
Passing	`681`
View all changes introduced in this branch ↗︎

UI Coverage `37.38%`
Untested elements	`129`
Tested elements	`77`

Accessibility `97.35%`
Failed rules	`3 critical` `7 serious` `1 moderate` `1 minor`
Failed elements	`62`

rebase into first

rebase into second

…piled down to CommonJS

…s differently since the refactor and is printing non deterministic outputs into our tests that do not have a large impact on the area we are testing and mostly served to actually test the renders of the listr2 framework itself

AtofStryker · 2025-07-22T18:33:42Z

passing CI on 1ddfa5e empty commit

cli/lib/exec/run.ts

cli/lib/tasks/cache.ts

cli/lib/tasks/download.ts

cli/lib/tasks/verify.ts

jennifer-shehane · 2025-08-22T19:18:29Z

cli/lib/tasks/verify.ts

@@ -104,18 +113,18 @@ const runSmokeTest = (binaryDir, options) => {
    const stdioOptions = _.extend({}, {
      env: {
        ...process.env,
-        FORCE_COLOR: 0,
+        FORCE_COLOR: '0',


@AtofStryker I've confused myself on whether this is actually testing what it should be testing. https://force-color.org/ This was the original PR: #28994

When this variable is present and not an empty string (regardless of its value), it should force the addition of ANSI color.

Wasn't the original intention to have this evaluate to OFF?

We want to turn it off because the colored ANSI output was causing out verification task to fail. This should still be testing what we want

@AtofStryker So FORCE_COLOR is evaluating to true here which is what we want?

It would still evaluate to false (or at least should) because anything piped into execa would evaluate to a string as its an env variable in the process. It's the equivalent of doing something like FORCE_COLOR=0 node index.js where process.env.FORCE_COLOR inside index.js would actually be '0'

jennifer-shehane · 2025-08-22T19:35:58Z

cli/lib/tasks/verify.ts


  const rendererOptions = {
    renderer,
  }

  const tasks = new Listr([
    {
-      options: { title: util.titleize('Verifying Cypress can run', chalk.gray(binaryDir)) },
-      task: (ctx, task) => {
+      title: util.titleize('Verifying Cypress can run', chalk.gray(binaryDir)),


@AtofStryker I think this change is fixing behavior - this wasn't logging before (it's not in the snapshots) - is this the change in the snapshots that you were seeing?

oh duh that would explain it. It's been a while since I visited this PR and couldn't remember. Yes this was the change I saw in the snapshots not being deterministic. I'm going to double confirm by fixing this on develop and seeing if I see the same determinism problems

yeah this happens if you apply the fix on develop

Well I feel dumb now 🤣 . At least its working correctly. I will audit those tests and see if there are some additional assertions I can make that aren't so dependent on the snapshot

jennifer-shehane · 2025-08-22T19:42:13Z

cli/lib/util.ts

+const isPossibleLinuxWithIncorrectDisplay = (): boolean => {
+  return isLinux() && !!process.env.DISPLAY


Kind of feel like there are situations before where this may have not been working also?

possibly but unlikely? Any use cases you can think of?

cli/lib/util.ts

jennifer-shehane · 2025-08-22T19:50:30Z

cli/lib/util.ts

+        const { stdout } = await execa('uname', ['-m']).catch(() => ({ stdout: '' }))

        debug('arm uname -m result: %o ', { stdout })


Suggested change

const { stdout } = await execa('uname', ['-m']).catch(() => ({ stdout: '' }))

debug('arm uname -m result: %o ', { stdout })

const stdout = await execa('uname', ['-m']).catch(() => ({ stdout: '' }))

debug('arm uname -m result: %o ', stdout)

I think what is implement currently is correct based on https://www.npmjs.com/package/execa/v/5.1.0#usage. the print statement is just electing to print this as an object

Just seems like double destructuring

The first is valid. The other wants to key an object with stdout in the print which I can see why but it seems unnecessary? Either way probably fine to leave as is

cli/lib/util.ts

…r undefined

jennifer-shehane · 2025-08-22T20:06:37Z

cli/lib/tasks/download.ts

-const getUrl = (arch, version) => {
-  if (is.url(version)) {
+const getUrl = (arch: string, version: string): string => {
+  if (is.webUrl(version)) {


weirdly url is an alias of webUrl 🙄 so no change of behavior here but the type is right

correct I thought the same thing. One has types the other doesn't but it is the exact same thing!

jennifer-shehane · 2025-08-22T20:16:51Z

cli/test/lib/tasks/install_spec.ts

      sinon.stub(fs, 'removeAsync').resolves()
      sinon.stub(state, 'getVersionDir').returns('/cache/Cypress/1.2.3')
      sinon.stub(state, 'getBinaryDir').returns('/cache/Cypress/1.2.3/Cypress.app')
      sinon.stub(state, 'getBinaryPkgAsync').resolves()
      sinon.stub(fs, 'ensureDirAsync').resolves(undefined)
-      os.platform.returns('darwin')
+
+      ;(os.platform as any).returns('darwin')


@AtofStryker Might prefer something like below - there's a lot of these leading semicolon cases which I don't think are super intuitive. Do we want to replace them all?

const platformStub = (os.platform as any) platformStub.returns('darwin')

it reads better, but I don't know if it worth the effort to make this look better since we eventually plan on replacing mocha with vitest and will likely get rid of the spec_helper all together? I think we just live with the syntax for now and clean it up when we migrate the testing harness

jennifer-shehane · 2025-08-22T20:17:31Z

cli/test/lib/tasks/install_spec.ts

@@ -345,7 +347,7 @@ describe('/lib/tasks/install', function () {
        beforeEach(function () {
          sinon.stub(util, 'isInstalledGlobally').returns(true)

-          state.getBinaryPkgAsync.resolves({ version: 'x.x.x' })
+          ;(state.getBinaryPkgAsync as any).resolves({ version: 'x.x.x' })


same - a few leading semicolons in this file

personally I'm fine with it until we either improve the types or migrate the testing harness. The other sane option with spec files at least is to just us an @ts-expect-error as we get a lot of typing errors when we writing tests. something like:

// @ts-expect-error state.getBinaryPkgAsync.resolves({ version: 'x.x.x' })

is completely normal

cli/test/lib/tasks/unzip_spec.ts

cli/test/lib/util_spec.ts

…ib references

…ess into chore/refactor_cli_to_ts

migrate cli scripts to TypeScript

63255a1

This comment was marked as outdated.

Sign in to view

AtofStryker force-pushed the chore/refactor_cli_to_ts branch from 5e4e990 to b06e770 Compare July 21, 2025 22:20

This comment was marked as outdated.

Sign in to view

jennifer-shehane assigned AtofStryker Jul 22, 2025

AtofStryker added 11 commits July 22, 2025 10:29

convert all javascript source files in the CLI to TypeScript

5563b94

rebase into first

chore: refactor all tests to TypeScript

bcb9824

rebase into second

add npmignore for cli for typescript files

522a60a

update build process

4d88bf0

fix publically available exports

0b22909

Fix cy-in-cy tests

3ad4c62

add ts-expect-error to failing files

5d70d9e

fix projectConfigIpc failures as there are now multiple installs of tsx

79512d8

fix after-pack hook

78388d3

fix binary script

c942b9d

chore: update publish binary to account for CLI being an ESModule com…

34448c3

…piled down to CommonJS

AtofStryker force-pushed the chore/refactor_cli_to_ts branch from b06e770 to 34448c3 Compare July 22, 2025 14:41

This comment was marked as outdated.

Sign in to view

does this work?

6b0e69e

This comment was marked as outdated.

Sign in to view

empty commit

1ddfa5e

This comment was marked as outdated.

Sign in to view

fix group name rename in CLI

5d02799

AtofStryker requested a review from jennifer-shehane August 22, 2025 16:35

remove babel deps from cli and explicitly install typescript

39ade4b

cacieprins approved these changes Aug 22, 2025

View reviewed changes