`percy exec` exits 0 during startup before launching wrapped command, causing false-positive CI success`

[khitrenovich]

The problem

percy exec exits successfully before launching the wrapped Cypress command, causing CI to report a passing E2E run even though no tests were executed.

We intermittently observe GitHub Actions builds reporting successful E2E execution while Cypress never starts running. The last Percy startup message is typically:

[percy:core:install] Downloading Chromium 1300309...

After several minutes, the process exits successfully and the CI step is marked as passed.

Example:

$ percy exec --parallel -- cypress run --config-file ./cypress/config.ts --browser chrome ${CY_RUN_PARAMS}

[percy:core:install] Downloading Chromium 1300309...

Done in 380.53s.

Expected behavior

If Percy cannot complete startup and the wrapped command has not been launched, percy exec should exit non-zero.

At minimum, CI should fail when Cypress never starts running.

Environment

• Node version: v24.16.0
• npm version: 11.13.0
• yarn version: 1.22.22
• @percy/cli version: 1.31.14
• Percy SDK: @percy/cypress 3.1.8
• OS version: Ubuntu 24.04.4 LTS
• CI: GitHub Actions
• Type of shell command-line interface: bash

Details

The issue appears to occur during Percy startup, before the wrapped Cypress command is launched.

Observed behavior:

• Cypress never starts.

• The usual Percy log indicating execution of the wrapped command is never emitted.

• Percy logs Downloading Chromium 1300309....

• After that, no further Chromium download progress is logged.

• Percy remains alive for several minutes while only emitting monitoring metrics.

• CPU utilization remains near zero for most of the runtime.

• Percy eventually logs:

  [percy:monitoring] Stopped monitoring system metrics
  

• The process exits with status code 0.

• CI therefore reports a successful E2E run even though no tests were executed.

The relevant portion of the debug log looks like:

[percy:core:install] Downloading Chromium 1300309...

... several minutes of monitoring output ...

[percy:monitoring] Stopped monitoring system metrics
Done in 380.53s.

One additional line appears immediately before process exit in CI jobs where the app under test is running locally using webpack-dev-server:

[webpack-dev-server] Gracefully shutting down. To force exit, press ^C again. Please wait...

This line comes from our test environment rather than Percy itself, but it suggests that a graceful shutdown sequence is being triggered rather than an explicit failure path.

While investigating, we noticed that Percy CLI recently changed signal/shutdown handling in PR #2199, including explicit SIGINT/SIGTERM exit code mapping.

We have not identified the root cause, but the observed behavior seems consistent with Percy entering a shutdown path during startup and exiting successfully before the wrapped command is launched.

Regardless of the underlying cause, the externally observable behavior is that percy exec can report success even when the wrapped command never starts.

Debug logs

Relevant excerpt:

[percy:core:install] Downloading Chromium 1300309...
[percy:monitoring] cpuInfo: {"cores":4,"currentUsagePercent":1.0000000000000009,"cgroupExists":false} (5606ms)
[percy:monitoring] memoryInfo: {"currentUsagePercent":22.290926902438457,"totalMemory":16766423040} (2ms)

... monitoring output continues for several minutes ...

[percy:monitoring] Stopped monitoring system metrics (3798ms)
[webpack-dev-server] Gracefully shutting down. To force exit, press ^C again. Please wait...
Done in 380.53s.

Full debug logs are available if needed.

Code to reproduce issue

We do not currently have a minimal reproduction.

The issue started recently without any relevant code changes on our side and is observed in GitHub Actions using:

percy exec --parallel -- cypress run --config-file ./cypress/config.ts --browser chrome .....

The key symptom is that Percy exits successfully during startup and Cypress is never launched.