Cypress cy is Not Defined Error Fix

In this tutorial, you'll learn about Cypress cy is Not Defined Error Fix. We cover key concepts, practical examples, and best practices.

ESLint complains 'cy' is not defined when you open test files — your linter doesn't know about Cypress globals, even though the tests run fine in the Cypress browser.

The Problem

// WRONG — ESLint flags cy as undefined
describe('Login', () => {
  it('logs in successfully', () => {
    cy.visit('/login');
    cy.get('[data-cy=email]').type('user@example.com');
    cy.get('[data-cy=password]').type('password123');
    cy.get('[data-cy=submit]').click();
  });
});

'cy' is not defined  no-undef
'describe' is not defined  no-undef
'it' is not defined  no-undef

ESLint without the Cypress plugin treats cy, describe, it, expect as undefined variables because they are globals injected by Cypress at runtime.

Step-by-Step Fix

1. Install and configure eslint-plugin-cypress

npm install eslint-plugin-cypress --save-dev

// .eslintrc.json
{
  "plugins": ["cypress"],
  "env": {
    "cypress/globals": true
  },
  "extends": ["plugin:cypress/recommended"]
}

This tells ESLint that cy, <a href="/testing-qa/cypress/">Cypress</a>, expect, assert, describe, it, before, after, beforeEach, afterEach are predefined globals.

2. Or add Cypress globals manually

// .eslintrc.json
{
  "globals": {
    "cy": true,
    "Cypress": true,
    "expect": true,
    "assert": true,
    "describe": true,
    "it": true,
    "before": true,
    "after": true,
    "beforeEach": true,
    "afterEach": true
  }
}

3. Use .cy.js or .cy.ts file extension

// login.cy.js — Cypress detects this as a test file
// login.spec.js — might need explicit configuration

Modern Cypress conventions use .cy.js (or .cy.ts, .cy.tsx). Configure your ESLint overrides:

// .eslintrc.json
{
  "overrides": [
    {
      "files": ["*.cy.js", "*.cy.ts", "cypress/**/*.js"],
      "extends": ["plugin:cypress/recommended"]
    }
  ]
}

4. Add tsconfig for TypeScript projects

// cypress/tsconfig.json
{
  "compilerOptions": {
    "types": ["cypress"]
  },
  "include": ["**/*.cy.ts"]
}

Expected output:

✔  No ESLint errors in cypress/e2e/login.cy.js
  ✓ logs in successfully (2345 ms)

Prevention Tips

• Install eslint-plugin-<a href="/testing-qa/cypress/">cypress</a> in new projects from the start
• Use .cy.js extension for test files
• Configure ESLint overrides scoped to <a href="/testing-qa/cypress/">cypress</a>/** directory
• Add <a href="/testing-qa/cypress/">cypress</a>/tsconfig.json for TypeScript projects
• Run eslint <a href="/testing-qa/cypress/">cypress</a>/ --ext .cy.js to catch config issues early

Common Mistakes with cy not defined

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world CYPRESS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ