Plugins and the Plugins File

Analogy categoryAnalogies

Why Cypress Needs a Node-Side Extension Point

Cypress test code runs inside the browser sandbox, which deliberately has no access to the file system, no ability to spawn OS processes, and no direct database connectivity — this isolation is what makes Cypress fast and predictable, but it also means tasks like seeding a test database, reading a fixture file dynamically, or reading environment configuration from outside the browser require a separate execution context. That context is the Node.js process Cypress itself runs in, and the bridge to it is setupNodeEvents, a function defined in cypress.config.js that registers event listeners for lifecycle hooks like before:browser:launch, task, and file:preprocessor, executed entirely outside the browser sandbox with full Node.js capabilities.

🏏

Cricket analogy: This is like a batter on the field being unable to personally check the pitch report or weather radar mid-innings — that information has to come through the dressing room via a runner or signal, just as browser-sandboxed test code needs setupNodeEvents as its bridge to Node-side capabilities.

The `task` Event: Running Arbitrary Node Code from a Test

The most commonly used plugin hook is on('task', {...}), which registers named Node functions that a spec can invoke via cy.task('functionName', args) — a common pattern is registering a resetDatabase task that runs a real SQL truncate/seed against a test database using a Node driver like pg or mysql2, something completely impossible from inside the browser sandbox. Because cy.task() returns a promise-like chainable that Cypress automatically retries, and because task results can be null to signal 'nothing to yield,' tasks are also the standard way to log structured debug output to the actual terminal running the CI job (cy.task('log', message)) rather than only to the browser console, which is invisible in a headless run's terminal output.

🏏

Cricket analogy: This is like a captain calling for a designated runner because of injury — the runner physically does what the injured batter cannot, executing the actual running of overs on their behalf, just as a Node task executes DOM-inaccessible work on the browser test's behalf.

javascript

// cypress.config.js
const { defineConfig } = require('cypress');
const { Client } = require('pg');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        async resetDatabase() {
          const client = new Client({ connectionString: config.env.DATABASE_URL });
          await client.connect();
          await client.query('TRUNCATE TABLE orders, users RESTART IDENTITY CASCADE');
          await client.end();
          return null;
        },
        log(message) {
          console.log(message); // prints to the terminal, not the browser console
          return null;
        },
      });
      return config;
    },
  },
});

cy.task() fails the test if the registered Node function throws or rejects, and by default has the same timeout as other commands (taskTimeout, default 60000ms) — this is intentional, since a failed database seed should stop the test immediately rather than let subsequent commands run against inconsistent data.

Other Common Plugin Hooks: Browser Launch and File Preprocessing

on('before:browser:launch', (browser, launchOptions) => {...}) lets you modify browser startup arguments before Cypress opens it — a common use is adding Chrome flags like --disable-gpu or --force-device-scale-factor=1 to normalize rendering across different CI machine specs, or granting camera/microphone permissions automatically for a video-chat feature test. on('file:preprocessor', ...) intercepts how spec and support files are compiled before execution, which is how community plugins like @cypress/webpack-preprocessor or TypeScript-specific tooling hook in — though modern Cypress ships with built-in TypeScript and bundling support via its own Vite/webpack-based preprocessor, so custom file preprocessors are now needed only for unusual build requirements.

🏏

Cricket analogy: This is like a groundskeeper adjusting pitch conditions (roller passes, grass length) before the toss to standardize playing conditions across different venues in a tournament, just as before:browser:launch normalizes browser flags across different CI machines.

As of Cypress 10+, plugins live directly in setupNodeEvents inside cypress.config.js — the older standalone cypress/plugins/index.js file from Cypress 9 and earlier is deprecated. Migrating an older project means moving that file's exported function's body into setupNodeEvents and updating any support-file-based config references accordingly.

Cypress test code runs in a browser sandbox with no file system, process, or direct database access.
setupNodeEvents in cypress.config.js is the bridge to Node.js, registering lifecycle event listeners.
on('task', {...}) exposes named Node functions callable from specs via cy.task(), commonly used for database seeding.
cy.task() fails the test if the Node function throws, and respects the taskTimeout config (default 60000ms).
before:browser:launch lets you modify browser startup flags for consistency across CI machines or to grant permissions.
file:preprocessor customizes spec compilation, though Cypress's built-in bundler now covers most standard use cases.
Cypress 10+ moved plugins into setupNodeEvents; the old standalone cypress/plugins/index.js file is deprecated.