{"id":10384,"library":"cypress","title":"Cypress: Next-Generation Front-End Testing","description":"Cypress is a comprehensive front-end testing framework designed for the modern web, enabling end-to-end, integration, and component testing. Unlike traditional WebDriver-based solutions, Cypress executes tests directly within the browser, providing a unique interactive experience with real-time command logs, time-travel debugging, and automatic reloads. Its architecture allows for direct manipulation of the browser, network requests, and DOM, leading to more reliable and faster tests. The current stable version is 15.14.0. Cypress maintains a relatively fast release cadence, with minor versions often released every few weeks to introduce new features, bug fixes, and performance improvements, while major versions (e.g., v10, v12) introduce more significant breaking changes and architectural shifts. Key differentiators include its bundled nature (no external WebDriver), interactive test runner, built-in assertion library (Chai), and powerful mocking capabilities for network requests.","status":"active","version":"15.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/cypress-io/cypress","tags":["javascript","automation","browser","cypress","cypress.io","e2e","end-to-end","integration","component","typescript"],"install":[{"cmd":"npm install cypress","lang":"bash","label":"npm"},{"cmd":"yarn add cypress","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used for processing test files (e.g., TypeScript, modern JavaScript) before execution in Cypress.","package":"@cypress/webpack-preprocessor","optional":true},{"reason":"Provides linting rules specific to Cypress best practices and common pitfalls, enhancing code quality in test files.","package":"eslint-plugin-cypress","optional":true},{"reason":"Required for component testing with React. Similar packages exist for Vue and Angular.","package":"@cypress/react","optional":true}],"imports":[{"note":"`cy` is a global object injected by the Cypress test runner into the browser context. It is not typically imported as a module. For TypeScript, add `cypress` to your `tsconfig.json`'s `types` array or use a triple-slash directive.","wrong":"import { cy } from 'cypress';","symbol":"cy","correct":"/// <reference types=\"cypress\" />\n// OR add \"cypress\" to types array in tsconfig.json\n// cy is a global object provided by Cypress runtime"},{"note":"Similar to `cy`, the `Cypress` global object provides configuration, utility functions, and access to other Cypress APIs. It's also globally available in the test runner context.","wrong":"import { Cypress } from 'cypress';","symbol":"Cypress","correct":"/// <reference types=\"cypress\" />\n// OR add \"cypress\" to types array in tsconfig.json\n// Cypress is a global object provided by Cypress runtime"},{"note":"`mount` is used for component testing and is provided by specific framework adaptors (e.g., `@cypress/react`, `@cypress/vue`), not directly from the main `cypress` package. Ensure you install the correct adaptor package.","wrong":"import { mount } from 'cypress';","symbol":"mount","correct":"import { mount } from '@cypress/react'; // or '@cypress/vue', etc."}],"quickstart":{"code":"import { mount } from '@cypress/react'; // Only needed for component tests, remove for e2e\n\ndescribe('My First Cypress Test', () => {\n  beforeEach(() => {\n    // Ensure the server is running or mock API calls as needed\n    cy.visit('http://localhost:3000'); // Replace with your application's URL\n  });\n\n  it('should display the correct title and allow user interaction', () => {\n    cy.title().should('include', 'My App');\n\n    cy.get('.todo-input').type('Learn Cypress{enter}');\n    cy.get('.todo-list li').should('have.length', 1).and('contain', 'Learn Cypress');\n\n    cy.get('.todo-list li:first-child .toggle').click();\n    cy.get('.todo-list li:first-child').should('have.class', 'completed');\n\n    cy.contains('Clear completed').click();\n    cy.get('.todo-list li').should('not.exist');\n  });\n\n  it('should handle API requests (example with intercept)', () => {\n    cy.intercept('GET', '/api/todos', { fixture: 'todos.json' }).as('getTodos');\n    cy.visit('http://localhost:3000/todos');\n    cy.wait('@getTodos').its('response.statusCode').should('eq', 200);\n    cy.get('.todo-item').should('have.length', 2); // Assuming todos.json has 2 items\n  });\n});","lang":"typescript","description":"Demonstrates a basic end-to-end test verifying page title, interacting with DOM elements, asserting their state, and mocking an API request using `cy.intercept`."},"warnings":[{"fix":"Migrate your `cypress.json` and `plugins/index.js` to the new `cypress.config.js|ts` format. Refer to the official migration guide for detailed steps. Component testing now requires specific adaptors like `@cypress/react` or `@cypress/vue` configured in `cypress.config.ts`.","message":"Cypress v10 introduced a significant refactor, moving configuration from `cypress.json` to `cypress.config.js` or `cypress.config.ts` and changing how project structure and component testing are set up. `plugins/index.js` was also deprecated in favor of direct config file callbacks.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade your Node.js version to 16 or higher (Cypress recommends >=20). For cross-origin testing, refactor tests to use `cy.origin()` for navigating and interacting with different domains within a single test.","message":"Cypress v12 deprecated support for Node.js 14. Additionally, `cy.origin()` became the recommended approach for testing multi-origin workflows, replacing older workarounds for cross-domain interactions.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"Replace all instances of `cy.server()` and `cy.route()` with `cy.intercept()`. `cy.intercept()` allows for more granular control over request matching, response modification, and better handling of modern fetch APIs and service workers.","message":"The `cy.server()` and `cy.route()` commands for network mocking have been deprecated in favor of `cy.intercept()`. `cy.intercept()` offers more powerful, flexible, and reliable control over network requests.","severity":"deprecated","affected_versions":">=6.0.0"},{"fix":"Always chain Cypress commands (`.then()`, `.should()`, `.wait()`). Use `.then()` to wrap non-Cypress specific logic or interact with the results of a previous command. Avoid using `async/await` directly with Cypress commands; instead, use `cy.then(async () => { await somePromise(); })` for promises that don't involve Cypress DOM interactions.","message":"Cypress commands are asynchronous and chainable, but they do not return promises or resolve immediately. Attempting to mix Cypress commands with standard synchronous JavaScript or native async/await without careful handling can lead to unexpected behavior or tests failing due to race conditions.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure that elements are in an actionable state before interacting with them. Cypress automatically retries for actionability, but if an element remains hidden or disabled, you might need to add explicit assertions like `.should('be.visible')` or `.should('not.be.disabled')` to debug or wait for specific states, or trigger necessary UI actions.","message":"Cypress commands like `cy.get()` will retry until an element is found or assertions pass within a default timeout. However, an element must be 'actionable' (visible, not disabled, not covered) before interaction commands like `click()` or `type()` will succeed.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'15.14.0':88 'allow':65 'architectur':64,125 'assert':142 'autom':153 'automat':61 'base':36 'break':122 'browser':44,71,154 'bug':108 'built':140 'built-in':139 'bundl':131 'cadenc':95 'capabl':148 'chai':144 'chang':123 'command':54 'compon':30,163 'comprehens':12 'current':84 'cypress':1,9,38,89,155 'cypress.io':156 'debug':59 'design':18 'differenti':128 'direct':41,67 'dom':75 'e.g':116 'e2e':157 'enabl':23 'end':7,15,25,27,159,161 'end-to-end':24,158 'everi':101 'execut':39 'experi':49 'extern':134 'fast':93 'faster':81 'featur':107 'fix':109 'framework':17 'front':6,14 'front-end':5,13 'generat':4 'improv':112 'includ':129 'integr':28,162 'interact':48,136 'introduc':105,119 'javascript':152 'key':127 'lead':76 'librari':143 'log':55 'maintain':90 'major':114 'manipul':68 'minor':97 'mock':147 'modern':21 'natur':132 'network':72,150 'new':106 'next':3 'next-gener':2 'often':99 'perform':111 'power':146 'provid':45 'real':52 'real-tim':51 'relat':92 'releas':94,100 'reliabl':79 'reload':62 'request':73,151 'runner':138 'shift':126 'signific':121 'solut':37 'stabl':85 'test':8,16,31,40,82,137 'time':53,57 'time-travel':56 'tradit':33 'travel':58 'typescript':164 'uniqu':47 'unlik':32 'v10':117 'v12':118 'version':86,98,115 'web':22 'webdriv':35,135 'webdriver-bas':34 'week':103 'within':42","created_at":"2026-04-18T08:58:31.137554+00:00","updated_at":"2026-04-19T05:55:14.213295+00:00","problems":[{"fix":"For TypeScript, add `\"cypress\"` to the `types` array in your `tsconfig.json` (e.g., `\"types\": [\"node\", \"cypress\"]`). For JavaScript, ensure your editor/IDE is configured to recognize globals from Cypress or use a JSDoc `/// <reference types=\"cypress\" />` directive in your test files.","cause":"The Cypress global types are not correctly loaded in your TypeScript configuration or JavaScript file.","error":"ReferenceError: cy is not defined"},{"fix":"Investigate why the command is slow. It could be a slow network request, a complex DOM query, or an element that takes time to appear/become interactive. Increase the timeout for specific commands (e.g., `cy.get('.slow-element', { timeout: 10000 })`) or globally in `cypress.config.ts` (e.g., `defaultCommandTimeout: 10000`).","cause":"A Cypress command (e.g., `cy.get()`, `cy.wait()`, `cy.visit()`) or an assertion took longer than the default timeout to complete or pass.","error":"Cypress command timeout of 4000ms exceeded."},{"fix":"Examine the Cypress test runner output or CI logs for detailed error messages. Look for failing assertions, unhandled exceptions, or configuration errors printed to the console. The exact cause is usually logged immediately before this exit code.","cause":"This is a generic exit code indicating a test run failure. It usually means one or more tests failed, or there was a configuration error that prevented tests from running.","error":"Cypress exited with code 1"},{"fix":"Ensure all Cypress commands start with `cy.` (e.g., `cy.get('.element')` instead of `get('.element')`). If you're using a result from a previous command, chain it correctly using `.then()`.","cause":"Attempting to call a Cypress command (e.g., `get`, `visit`) directly without chaining it from the `cy` object, or trying to chain it from a non-Cypress object.","error":"Cypress commands can only be chained off of `cy`."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"cypress","cli_version":null,"type":"library","homepage":"https://www.cypress.io","github":"https://github.com/cypress-io/cypress","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/cypress","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}