How can I see `cy.log` output when using Cypress headlessly?

When running Cypress headlessly, I can see console.log output from the frontend code under test by using the DEBUG environment variable, like:

DEBUG='cypress:launcher' npx cypress run --browser chrome

However, I haven't found any similar way to see the output of cy.log from the Cypress test code when running headlessly. Even with DEBUG='cypress:*' I don't see them - they only seem to be visible in the interactive interface. It feels like there must be some way to see the cy.log output headlessly - can someone help with that?

The first step is to add a new task in your Cypress config file cypress.config.js (in the cypress root folder) so that you can run console.log from Node:

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on("task", {
        log(args) {
          console.log(...args);
          return null;
        }
      });
    },
  },
});

Then, you can override cy.log so that it calls this task whenever you run the command in headless mode, and console.log when you're running in headed mode. You can do this by adding the following to your commands file commands.js (in the support folder):

Cypress.Commands.overwrite("log", function(log, ...args) {
  if (Cypress.browser.isHeadless) {
    return cy.task("log", args, { log: false }).then(() => {
      return log(...args);
    });
  } else {
    console.log(...args);
    return log(...args);
  }
});

If you want the output to be tabbed/indented (so it will look nicer in the log),
you can do a slight improvement, like so:

Cypress.Commands.overwrite("log", function(log, ...args) {
  const indent = "\t"; // You can adjust the number of tabs or spaces here
  const formattedArgs = args.map((arg) =>
        typeof arg === "string" ? indent + arg : indent + JSON.stringify(arg)
  );
  if (Cypress.browser.isHeadless) {
    return cy.task("log", formattedArgs, { log: false }).then(() => {
      return log(...args);
    });
  } else {
    console.log(...formattedArgs);
    return log(...args);
  }
});

One tab should be sufficient.