Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversOctober DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run Scan×
Skip to content
World desk6 min

How to Extend Cypress with Plugins

Cypress extensions must be registered in the right runtime: use setupNodeEvents for Node behavior and a support file for browser commands. Here’s how to install, configure, and troubleshoot plugins.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Extend Cypress by installing a compatible npm package, then registering it where it runs: Node-side behavior belongs in setupNodeEvents in cypress.config.js or cypress.config.ts; browser-side commands belong in a support file. Some extensions need both. Installing a package alone does not activate it.

Choose the right extension point

Cypress describes plugins as extensions that customize how tests are written, run, and reported. The key decision is the runtime: Cypress test code runs in the browser, while Node event hooks run in Cypress’s Node process. Consult the Cypress plugin guide and verify a package’s stated Cypress compatibility before adopting it.

Need Where it runs Extension point
Interact with the page through a reusable test abstraction Browser Register a custom command in a support file with Cypress.Commands.add().
Use filesystem, database, or operating-system capabilities Node Register a task in setupNodeEvents and call it with cy.task().
Transform spec or support files before browser execution Node Use the file:preprocessor event.
Change lifecycle behavior or browser launch options Node Register the relevant event in setupNodeEvents.
Use a package with browser and Node components Both Follow its documentation and register each component in its respective location.

Install and register an existing plugin

  1. Find a package that covers the need in the Cypress plugin directory. It categorizes entries such as custom commands, preprocessors, API and network testing, visual and accessibility testing, CI integrations, and reporting. Check the listed version, compatibility, update information, and ownership status; directory entries may be official, community-owned, or deprecated.

  2. Install the package as a development dependency using your project’s package manager. For example, with npm: npm install --save-dev package-name. Replace package-name with the actual package name from its documentation.

    Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  3. Read that package’s README for its exact registration steps. Import or invoke Node setup from setupNodeEvents; import browser-side command registration from the support file. If a package has both parts, perform both steps.

  4. Run Cypress and a representative test to confirm the extension loaded. If startup or the test fails, temporarily disable the extension and rerun the failing test to isolate whether the failure depends on it.

Register Node-side behavior

Define setupNodeEvents(on, config) under the relevant e2e or component configuration in cypress.config.js or cypress.config.ts. Cypress calls it in Node, separate from browser test code. Event hooks handle work at particular stages of the Cypress lifecycle. If setup changes configuration values, return the updated configuration; the hook can return a value or a promise, and a returned object is merged into configuration. See the Node Events overview.

Choose an event for the job

  • before:run and after:run: run-wide setup or reporting.
  • before:spec and after:spec: work around an individual spec’s lifecycle.
  • before:browser:launch: adjust browser launch configuration, subject to browser-specific limits.
  • after:screenshot: inspect or process screenshot metadata.
  • file:preprocessor: prepare spec or support files for browser execution.
  • task: let browser test code request Node-side work, such as database seeding or file access.

Example: expose a Node task

This CommonJS example registers a task that returns a value to the test. Place the handler inside setupNodeEvents in the relevant configuration:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        seedDatabase() {
          // Perform Node-side setup here.
          return null;
        },
      });
      return config;
    },
  },
});

Call the task from a spec with cy.task('seedDatabase'). A task must resolve to a value or explicitly return null when it has no result; returning undefined causes failure. Cypress advises against using cy.task() to start a web server. For an external command, the task API guidance recommends child_process.execFileSync() with arguments supplied as an array.

Add browser-side custom commands

Register browser-facing commands from a Cypress support file, which loads before each spec. A basic command can wrap repeated test actions:

// cypress/support/commands.js
Cypress.Commands.add('getByTestId', (id) => cy.get(`[data-testid="${id}"]`));

Then a spec can call cy.getByTestId('save'). Keep commands composable rather than bundling unrelated test flows into one abstraction. Cypress recommends avoiding repeated UI setup when an API request or direct state setup can achieve the same test precondition. In TypeScript projects, document a custom command’s signature so editor tooling can provide useful type information.

Add, overwrite, or define a query?

  • Cypress.Commands.add() introduces a new command and is the usual choice for a project-specific helper.
  • Cypress.Commands.overwrite() deliberately changes existing Cypress behavior. Use it cautiously because it can affect Cypress itself.
  • Use a custom query when the returned DOM element needs Cypress’s retry behavior.

See Cypress custom commands for the supported registration patterns. In a project configured with webpack sideEffects: false, a side-effect-only registration import may be tree-shaken. Cypress documents wrapping registration in an imported function as a workaround.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Customize preprocessing

Cypress’s default webpack preprocessor supports ES2015+, JSX, TypeScript, watching, and caching. Customize compilation or use another bundler by registering file:preprocessor in setupNodeEvents. The preprocessor executes in Node, so it cannot call Cypress or cy commands. The Preprocessors API explains the hook.

Preserve source maps when transforming files: they let Cypress map stack traces back to original source and display code frames. Cypress’s examples use inline webpack source maps or inline esbuild maps. Developers publishing reusable preprocessors can use the cypress-*-preprocessor naming convention and keywords including cypress, cypress-plugin, and cypress-preprocessor.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Check ownership, compatibility, and maintenance

The directory distinguishes team-maintained, community-owned, and deprecated extensions. A community package is not maintained by Cypress: follow its own documentation and direct bugs to its maintainers. Before adding one, check whether it supports your Cypress version and whether its update history and ownership make it suitable for your project. The directory showed 131 entries when accessed on October 3, 2026; that count can change and is not a measure of package quality.

Use an existing package when it is maintained, compatible, and saves meaningful project-specific work. A custom command or Node task can be simpler when the behavior is narrow and specific to your codebase, but it becomes your team’s responsibility to maintain and debug. Commands are for browser-facing abstractions; tasks bridge browser tests to Node capabilities.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Troubleshoot common setup failures

  • The package installs, but Cypress behavior does not change: installation does not register an extension. Check its README, then add Node setup to setupNodeEvents, browser registration to the support file, or both as required.
  • Cypress fails during startup after adding a package: verify the package’s Cypress compatibility and exact setup instructions. Disable it and rerun the failing test; if the problem disappears, share Cypress and package versions plus a minimal reproduction with the package maintainers.
  • cy.task() fails because it returned undefined: return a concrete value or null when there is no result.
  • A command registration disappears in a webpack project: if sideEffects: false is configured, use the documented imported-function registration pattern so the registration is not removed as a side effect.
  • Stack traces point to transformed code: preserve and configure source maps in the preprocessor so Cypress can map errors to original files.
  • A Chrome extension no longer loads from a launch hook: Cypress’s Node Events documentation says standard Chrome 137 and newer no longer load extensions using before:browser:launch, because Chrome removed the --load-extension flag. The same guidance says Chrome for Testing or Chromium can still load extensions. Check the current Node Events guidance against your installed browser and Cypress versions before relying on this workflow.

Or skip the browser setup

If your goal is to capture a website rather than extend Cypress’s test runner, ScreenshotNeo is a separate screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. For example, using cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for setup and options. It accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Leave a Reply

Your email address will not be published. Required fields are marked *

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. Shenzhen desk3 min
    HONOR Expands Beyond Smartphones With Humanoid Robot RevealHONOR said it unveiled its first humanoid robot at MWC 2026 and named shopping assistance, workplace inspections, and supportive companionship as intended uses. Later Robotics D1 claims and a reported…
  2. Cupertino desk5 min
    Apple Unveils AirPods Max 2: The Upgrade That Should Have Happened Years AgoAirPods Max 2 adds H2-powered audio features and Apple claims up to 1.5× more effective ANC, but its design, Smart Case, and 20-hour battery rating are unchanged. Wired lossless audio…
  3. Cupertino desk4 min
    Apple’s OLED Touch MacBooks Are Coming—but the Dynamic Island Is the Real GambleApple has not announced an OLED touchscreen MacBook, but reports point to high-end models arriving in late 2026 or early 2027. The reported Mac Dynamic Island could be useful, but…
Recommended PC Tool
Recommended PC Tool
Windows Errors? Fix Them Before They SpreadFree repair scan
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.