cypress-terminal-report puts Cypress logs in the terminal where CI can read them

The problem it solves is CI log readability

Cypress has a rich graphical runner, which is a liability in a pipeline. When a test fails in CI, the interesting information is in the browser log and in the network traffic the test produced, and the standard way to get at it is to open the Cypress GUI on a developer's machine and reproduce the failure locally. That is a slow loop, and it is the loop this plugin is built to shorten.

The plugin's own summary is that it adds better terminal output for easier debugging, and that it prints cy commands, browser console logs, cy.request and cy.intercept data, and is great for your pipelines. The feature list adds that it looks pretty in console, logs all commands, requests and browser console logs, supports logging to files, offers an option between logging only on failure, which is the default, or always, and provides options for trimming and compacting logs.

The last of those matters more than it sounds. A Cypress run against a real application produces a lot of output, and a CI log with ten thousand lines of it is no easier to read than a screenshot of the GUI. The trimming and compaction options are the mechanism that makes the output usable rather than merely present.

The repository metadata describes the project as a plugin for cypress that logs to terminal and files while mimicking the Cypress UI, with topics for ci, cli, console, cypress, log, output, pretty and print. The primary language is TypeScript, the licence is MIT, and the package on npm is cypress-terminal-report at version 7.4.0 in the package.json.

One structural point before anything else. The README's documentation is for Cypress 12.0.0 and newer, and older versions are pointed at the 4.x.x and 3.x.x branches. The peer dependency in package.json is cypress>=10.0.0, and the requirements section in the README tracks the same history: version 4.0.0 and above requires Cypress 10.0.0 and node 12, version 3.0.0 requires Cypress 4.10.0, and anything below 3.0.0 requires Cypress 3.8.0.

Two registration calls, one for the printer and one for the collector

The install is two npm commands' worth of steps, and the second half matters more than it looks.

First the package:

   npm i --save-dev cypress-terminal-report

Then the printer, registered in cypress.config.js or cypress.config.ts:

   module.exports = defineConfig({
     e2e: {
       setupNodeEvents(on, config) {
         require('cypress-terminal-report/src/installLogsPrinter')(on)
       }
     }
   })

And then the collector, registered in the support file at cypress/support/e2e.js or e2e.ts:

   require('cypress-terminal-report/src/installLogsCollector')()

Two installs, two different sides of the system. The printer lives in the Node process, where it hooks into Cypress's own event stream and writes to the console and to files. The collector lives in the browser, where it intercepts the commands and the console output so that there is something to print. Install only the printer and the plugin has a stream with nothing in it; install only the collector and there is data with no one writing it out.

There is one extra step for TypeScript projects, and the README states it plainly: if using typescript and es6 imports ensure esModuleInterop is enabled. That is a tsconfig concern rather than a plugin concern, but it is the step that trips people up, because the failure looks like a module resolution error rather than a config flag.

The options are passed to the printer call, require('cypress-terminal-report/src/installLogsPrinter')(on, options), while the support-side install takes its own options through require('cypress-terminal-report/src/installLogsCollector') with the options documented separately.

Trimming, compaction and the difference between terminal and file output

The options are the substance of the plugin, and the three that control volume come first.

defaultTrimLength is an integer with a default of 800 and is the max length of cy.log and console.warn or console.error output. commandTrimLength is also 800 by default and caps the length of cy commands. routeTrimLength defaults to 5000 and caps cy.request and XHR data. The asymmetry is deliberate: network payloads are the ones most likely to contain the information you need when something fails, so they get the longer budget.

Then there are the compaction options, and these are the ones that change the shape of the output rather than the size of individual lines.

compactLogs is an integer or null with a default of null. If it is set to a number greater or equal to 0, that amount of logs will be printed only around failing commands. The stated use is shorter output when there are a lot of commands in tests. There is an important interaction: when it is used with options.printLogsToConsole set to always, for tests that do not have any severity=error logs, nothing will be printed. So compaction plus always is a combination that can produce an empty log for a passing suite, which is the intended behaviour but reads like a bug.

outputCompactLogs is an integer or false with a default of null, and it overrides compactLogs for the file log output specifically, when options.outputTarget is specified. That allows compacting of the terminal and the file output logs to different levels. If outputCompactLogs is unspecified, file output will use compactLogs, and if it is set to false, output file logs will not compact even if compactLogs is set.

That last option is the reason the plugin is worth reading closely rather than skimming. A team that wants a full transcript on disk for later analysis but a short summary in the CI log can have both, and that is a genuinely different debugging workflow from the one you get by picking one setting for everything.

When to print, and the two switches that control it

Two options decide when output appears, and they are independent.

printLogsToConsole is a string with a default of onFail. The possible values are always, onFail and never, and when set to always, logs will be printed to console for successful tests as well as failing ones. printLogsToFile behaves identically for file output, with the same three values and the same default.

The default of onFail for both is a defensible choice and it has a stated reason in the related hook option. Commands from before all and after all hooks by default get logged only if a command from them failed, and the README says this default is in accordance with the defaults on options.printLogsTo* to avoid printing too many, possibly irrelevant, information.

The exception is includeSuccessfulHookLogs, a boolean defaulting to false. Setting it to true gives you more extensive logging, but the README warns that commands will be logged to terminal from these hooks regardless whether there were failing tests in the suite, and explains why: we can't know for sure in advance if a test fails or not.

That is an honest limitation stated plainly rather than papered over. Hook commands can run before any assertion has failed, so there is no reliable way to know at the time the command runs whether the suite will end up failing. The plugin chooses to log those commands when the option is on, and accepts the noise.

Two more switches round out the behaviour. outputVerbose is a boolean defaulting to true and currently just writes out additional file write information, if any. debug is a boolean defaulting to false and is described as useful in cases of difficult to reproduce issues with the plugin. The last is the one to reach for when the plugin itself seems to be the thing that is wrong, and it is a sensible thing to expose given that the plugin's job is to report on other people's software.

Writing logs to files, and the hook that does it after the run

File output is the feature that makes this more than a console prettifier, and it comes with its own options.

outputTarget is an object with a default of null, and setting it is what enables output logs to files. outputRoot is a string defaulting to null and is required if options.outputTarget is provided. specRoot is a string defaulting to null and is the Cypress specs root relative to the package json, which is what lets the plugin build a directory structure that mirrors your spec layout when writing separate files per spec.

The naming is a little confusing and worth pinning down. The option that enables file output is outputTarget, the option that says where to put things is outputRoot, and the option that describes your test layout is specRoot.

There is a second, separate path for writing logs: logToFilesOnAfterRun, a boolean defaulting to false. When set to true it enables an additional log write pass to files using the cypress after:run plugin hook. The README is precise about the constraints: this option can only be used with cypress 6.2.0 onwards, and with the additional experimentalRunEvents configuration on versions smaller than 6.7.0.

So there are two mechanisms, not one. The ordinary path writes logs as the run proceeds. The after:run path defers the write until the run has finished, which is the useful one when you want the full picture of a run including hooks, or when you want the write to happen against a final state.

There is also a callback option for collecting logs yourself. collectTestLogs is a function of the form ([spec, test, state], {type, message, severity}[]) => void with a default of undefined, called to collect each test case's logs after its run. The first argument contains information about the test, namely the spec, test title and state fields, and the second contains the test logs. The type field comes from the same list as the collectTypes support install option, and severity can be one of empty string, error or warning.

That callback is the extension point for anyone who wants the logs in their own reporting system rather than in a file, and it is the option that makes the plugin composable with whatever your team already uses for CI output.

The console.log trap, and why the plugin ignores it

The limitations section has two entries, and the second one catches nearly everyone.

The first is the default behaviour itself: by default logs are not printed for successful tests, with a pointer to the printLogsToConsole option to change that. That is a design choice rather than a defect, and it is the right default for CI, where the log is read mostly when something has already gone wrong.

The second is the important one. console.log usage was never meant to be used in the Cypress test code, and using it will not log anything with this plugin. Using it also goes against the queue nature of Cypress. The README directs you to use cy.log instead and links an issue for more details.

The reasoning is worth understanding rather than working around. Cypress commands are queued and executed in order, and cy.log is a command, so it participates in that queue and produces a result that the runner can attach to a test. console.log is a plain function call that happens to write to the browser console, and because the browser console is not part of the command queue, the plugin has no way to associate that output with a specific test or a specific point in the sequence.

So the plugin is not missing your console.log output by accident. It is capturing the browser console as a stream, but without the queue discipline there is no reliable anchor for it, and the plugin is explicit that you should be using cy.log.

This also has a knock-on effect for anyone planning a migration. If your test suite logs heavily with console.log, adding this plugin will not surface those lines, and the first symptom will look like the plugin not working at all.

The repository layout supports the rest of the picture. There is a src/ directory for the plugin code, index.js and index.d.ts as the published entry points, an index.internal.d.ts, a test/ directory, a tsconfig.json, and a .circleci/ directory for the CI configuration that the README's build badge points at. The build script is tsc, with a watch script, a format script running prettier, and prepublishOnly running the build.

Where a different approach is the right call

The first limitation is that this reports and does not interact. Cypress's GUI is not going away, and the plugin does not replace it, it replaces the need to open it to read a failure in a pipeline. If your workflow depends on stepping through a test manually, driving the application and inspecting state at a particular point, this plugin does nothing for you.

The second limitation is the version floor. The peer dependency is cypress>=10.0.0, and the README documentation targets Cypress 12 and newer. If you are on an older Cypress, you are in the 4.x.x or 3.x.x branch world, where the options and the registration calls differ.

The third limitation is the scope of what it captures. It prints cy commands, browser console logs, cy.request and cy.intercept data, and it supports multiple and nested mocha contexts. It does not capture application state, screenshots of the failure, or anything about the DOM. For a team that already uses Cypress's own artefacts alongside the plugin, this is a complement rather than a replacement, and the plugin's own value is that the log lands in the pipeline output where a human reading the build can see it without downloading artefacts.

The alternative to weigh is the built-in reporting that ships with Cypress itself. The difference in approach is where the output lives. The built-in reporter produces a file you download and open, or a JUnit XML you feed to a CI reporting service. This plugin writes to the terminal, which is where a developer or a bot is already looking when a build breaks.

For a local run, the built-in artefacts are better, because they give you the full picture including screenshots and the video. For a CI run where the failure notification is a link to a log line, this plugin is better. And the collectTestLogs callback exists precisely so you can have both, by forwarding what the plugin collects into the reporting system you already run.

The licence is MIT, recorded in the package.json and with a LICENSE file at the repository root, so there is no copyleft constraint on using it in a commercial project. That is a licensing note rather than legal advice. On maintenance, the last push was on 2026-10-12 and the repository is not archived, and the package.json records version 7.4.0 while the repository publishes no GitHub releases, so the npm version is the reference point.

Editorial conclusion

Adopt cypress-terminal-report if you run Cypress in CI and your failure output is unreadable, because the plugin prints the command log, the browser console and the request and intercept data into the pipeline log with trimming and compaction controls. Do not adopt it to replace the Cypress GUI, since it reports rather than interacts, and note that console.log calls in test code are not captured. Verify first that you register both the printer and the collector as documented, that your Cypress version is at least 10, and whether the onFail default is the behaviour you want when you switch to always.

Frequently asked questions

Official sources

1. archfz/cypress-terminal-report on GitHub
2. Issues
3. License: MIT
4. README