tessl/npm-eslint-plugin-cypress
An ESLint plugin for projects using Cypress that provides comprehensive linting rules to enforce best practices for writing Cypress tests
—
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
configurations.mddocs/
Configuration Presets
Pre-configured ESLint configurations providing different levels of Cypress linting support. The plugin offers two configurations: globals for basic Cypress global definitions and recommended for a comprehensive rule set with essential linting rules enabled.
Capabilities
globals Configuration
Provides Cypress-specific global variable definitions without enabling any linting rules. Ideal when you want to define Cypress globals but configure rules manually.
/**
* Globals-only configuration for Cypress environments
* Defines cy, Cypress, expect, assert, chai globals plus browser/mocha globals
* No rules enabled - allows manual rule configuration
*/
interface GlobalsConfig {
name: 'cypress/globals';
plugins: {
cypress: CypressPlugin;
};
languageOptions: {
globals: {
cy: false; // Cypress command object (read-only)
Cypress: false; // Main Cypress object (read-only)
expect: false; // Assertion library (read-only)
assert: false; // Assertion library (read-only)
chai: false; // Assertion library (read-only)
// Plus all globals from globals.browser and globals.mocha
};
};
}
const globals: GlobalsConfig;Usage Example:
// eslint.config.mjs
import pluginCypress from 'eslint-plugin-cypress';
export default [
pluginCypress.configs.globals,
{
// Add your own rules configuration
rules: {
'cypress/no-assigning-return-values': 'error',
'cypress/no-debug': 'warn'
}
}
];recommended Configuration
Comprehensive configuration that includes both global definitions and a curated set of essential linting rules. This is the recommended starting point for most Cypress projects.
/**
* Recommended configuration with essential rules enabled
* Includes globals configuration plus 4 core problem-detection rules
* Suitable for most Cypress projects as a complete linting setup
*/
interface RecommendedConfig {
name: 'cypress/recommended';
plugins: {
cypress: CypressPlugin;
};
rules: {
'cypress/no-assigning-return-values': 'error';
'cypress/no-unnecessary-waiting': 'error';
'cypress/no-async-tests': 'error';
'cypress/unsafe-to-chain-command': 'error';
};
languageOptions: {
globals: {
cy: false;
Cypress: false;
expect: false;
assert: false;
chai: false;
// Plus browser and mocha globals
};
};
}
const recommended: RecommendedConfig;Usage Example:
// eslint.config.mjs
import pluginCypress from 'eslint-plugin-cypress';
export default [
// Complete setup with globals and essential rules
pluginCypress.configs.recommended,
// Optional: Override specific rules
{
rules: {
'cypress/no-unnecessary-waiting': 'warn' // Downgrade to warning
}
}
];Global Variables Defined
Both configurations define the same set of global variables for Cypress test environments:
interface CypressGlobals {
/** Cypress command object - provides access to all Cypress commands */
cy: false;
/** Main Cypress object - provides access to configuration and utilities */
Cypress: false;
/** Expectation/assertion library (typically from Chai) */
expect: false;
/** Assertion library (typically from Chai) */
assert: false;
/** Chai assertion library */
chai: false;
}Additionally, both configurations include all globals from:
globals.browser- Browser environment globals (window, document, etc.)globals.mocha- Mocha testing framework globals (describe, it, beforeEach, etc.)
Configuration Usage Patterns
Basic Setup (Recommended)
Most projects should start with the recommended configuration:
// eslint.config.mjs
import pluginCypress from 'eslint-plugin-cypress';
export default [
pluginCypress.configs.recommended
];Custom Rule Configuration
Use globals configuration when you need fine-grained control over rules:
// eslint.config.mjs
import pluginCypress from 'eslint-plugin-cypress';
export default [
pluginCypress.configs.globals,
{
rules: {
// Enable only specific rules you want
'cypress/no-assigning-return-values': 'error',
'cypress/no-force': 'warn',
'cypress/require-data-selectors': 'error'
}
}
];Mixed Configuration
Combine recommended config with additional rules:
// eslint.config.mjs
import pluginCypress from 'eslint-plugin-cypress';
export default [
pluginCypress.configs.recommended,
{
rules: {
// Add non-recommended rules
'cypress/no-debug': 'error',
'cypress/no-pause': 'error',
'cypress/require-data-selectors': 'warn',
// Override recommended rule severity
'cypress/no-unnecessary-waiting': 'warn'
}
}
];File-Specific Configuration
Apply Cypress rules only to test files:
// eslint.config.mjs
import pluginCypress from 'eslint-plugin-cypress';
export default [
// Base configuration for all files
{
// ... base config
},
// Cypress configuration only for test files
{
files: ['cypress/**/*.{js,ts}', '**/*.cy.{js,ts}'],
...pluginCypress.configs.recommended
}
];Configuration Comparison
| Feature | globals | recommended |
|---|---|---|
| Global Variables | ✅ | ✅ |
| Rules Enabled | ❌ (0 rules) | ✅ (4 rules) |
| Manual Rule Setup Required | ✅ | ❌ |
| Best For | Custom configurations | Most projects |
Recommended Configuration Rules
The recommended configuration enables these 4 essential rules:
- no-assigning-return-values - Prevents assigning Cypress command return values
- no-unnecessary-waiting - Discourages arbitrary wait times
- no-async-tests - Prevents async/await in test functions
- unsafe-to-chain-command - Prevents unsafe command chaining
These rules catch the most common and problematic patterns in Cypress tests while maintaining a minimal, non-intrusive linting experience.
Environment Compatibility
Both configurations are designed for:
- ESLint v9+ with flat configuration format
- Cypress test environments with proper global variable definitions
- Modern JavaScript/TypeScript projects
- Node.js and browser execution contexts
Install with Tessl CLI
npx tessl i tessl/npm-eslint-plugin-cypress