Overwriting Commands in Cypress

Sometimes you need to change the behavior of a built-in command project-wide, not just add a new one. This lesson covers Cypress.Commands.overwrite() and when it is (and isn't) the right tool.

Cypress.Commands.overwrite()

Cypress.Commands.overwrite() replaces the implementation of an existing command, built-in or custom, letting you inject shared logic (like automatic logging, or a default option) into every call site without changing any spec files.

Cypress.Commands.overwrite('type', (originalFn, subject, text, options) => {
  cy.log(`Typing "${text}"`);
  return originalFn(subject, text, options);
});

The original implementation is always passed in as the first argument, letting you wrap rather than fully replace its behavior.

Overwrite Syntax

Cypress.Commands.overwrite('commandName', (originalFn, ...args) => {
  // custom logic
  return originalFn(...args);
});

The first parameter to the callback is always the original implementation function.
Remaining parameters mirror the original command's own arguments (subject, then its normal arguments).
Always call and return originalFn(...) unless you deliberately intend to fully replace the behavior.
Works for both built-in Cypress commands and your own previously defined custom commands.

Overwrite Use Cases Cheat Sheet

Realistic reasons teams reach for Cypress.Commands.overwrite().

Use Case	Example
Add logging to every action	Overwrite `click`/`type` to log automatically
Enforce a default option project-wide	Overwrite `visit` to always set a default timeout
Add a safety check before an action	Overwrite `type` to warn on empty strings
Integrate a third-party tool	Overwrite `screenshot` to also upload the image

Enforcing a Default Option Project-Wide

Overwriting a command is useful for enforcing a consistent default across an entire suite without requiring every spec file to remember to pass a specific option.

Cypress.Commands.overwrite('visit', (originalFn, url, options = {}) => {
  return originalFn(url, {
    ...options,
    onBeforeLoad(win) {
      win.localStorage.setItem('feature-flags', JSON.stringify({ newCheckout: true }));
      options.onBeforeLoad?.(win);
    },
  });
});

Every cy.visit() call now sets a feature flag automatically, without needing to change existing spec files.

The Risks of Overwriting Built-In Commands

Because overwriting changes behavior for every call site across the entire suite, including tests written by other contributors who may not know the override exists, it should be used sparingly, documented clearly, and reserved for genuinely cross-cutting concerns.

Document any overwritten command clearly in your support file and project README.
Avoid overwriting core commands purely to work around a single test's edge case.
Prefer a new custom command over an overwrite whenever the change isn't truly universal.

Common Mistakes

Overwriting a built-in command to fix a problem specific to just one test, affecting the entire suite unnecessarily.
Forgetting to call the original implementation function, accidentally breaking the command entirely.
Not documenting an overwritten command, confusing contributors who expect standard, unmodified behavior.
Overwriting commands so heavily that debugging Cypress's actual built-in behavior becomes difficult.

Key Takeaways

Cypress.Commands.overwrite() changes behavior for every existing call site of a command.
The original implementation is always available and should usually still be called.
Reserve overwriting for genuinely cross-cutting, project-wide concerns.
Prefer adding a new custom command over overwriting when a change isn't truly universal.

Pro Tip

Before overwriting a built-in command, ask whether a new custom command with a different name would achieve the same goal without silently changing behavior every existing test already relies on, overwriting is powerful but has a much larger blast radius than adding something new.