{ "doc": { "id": "app/core-concepts/writing-and-organizing-tests", "title": "Writing and Organizing Tests", "description": "Learn how to organize your tests in Cypress and the types of supported files, how to write tests in Cypress including hooks, exclusions, and configurations.", "section": "app", "source_path": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md", "version": "24a73f8a97175663aaffd3b016289fb2a523a4ea", "updated_at": "2026-05-14T20:17:33.301Z", "headings": [ { "id": "app/core-concepts/writing-and-organizing-tests#writing-and-organizing-tests", "text": "Writing and Organizing Tests", "level": 1 }, { "id": "app/core-concepts/writing-and-organizing-tests#what-youll-learn", "text": "What you'll learn", "level": 5 }, { "id": "app/core-concepts/writing-and-organizing-tests#folder-structure", "text": "Folder structure", "level": 2 }, { "id": "app/core-concepts/writing-and-organizing-tests#configuring-folder-structure", "text": "Configuring Folder Structure", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#spec-files", "text": "Spec files", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#fixture-files", "text": "Fixture Files", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#asset-files", "text": "Asset Files", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#download-files", "text": "Download Files", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#screenshot-files", "text": "Screenshot Files", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#video-files", "text": "Video Files", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#asset-file-paths", "text": "Asset File Paths", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#assets-in-cypress-cloud", "text": "Assets in Cypress Cloud", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#plugins-file", "text": "Plugins file", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#support-file", "text": "Support file", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#execution", "text": "Execution", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#troubleshooting", "text": "Troubleshooting", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#writing-tests", "text": "Writing tests", "level": 2 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-structure", "text": "Test Structure", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#hooks", "text": "Hooks", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#the-order-of-hook-and-test-execution-is-as-follows", "text": "The order of hook and test execution is as follows:", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#excluding-and-including-tests", "text": "Excluding and Including Tests", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-isolation", "text": "Test Isolation", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-configuration", "text": "Test Configuration", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#syntax", "text": "Syntax", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#allowed-config-values", "text": "Allowed config values", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#suite-configuration", "text": "Suite configuration", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#single-test-configuration", "text": "Single test configuration", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#dynamically-generate-tests", "text": "Dynamically Generate Tests", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#assertion-styles", "text": "Assertion Styles", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#running-tests", "text": "Running tests", "level": 2 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-statuses", "text": "Test statuses", "level": 2 }, { "id": "app/core-concepts/writing-and-organizing-tests#passed", "text": "Passed", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#failed", "text": "Failed", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#pending", "text": "Pending", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#skipped", "text": "Skipped", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#watching-tests", "text": "Watching tests", "level": 2 }, { "id": "app/core-concepts/writing-and-organizing-tests#what-is-watched", "text": "What is watched?", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#files", "text": "Files", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#folders", "text": "Folders", "level": 4 }, { "id": "app/core-concepts/writing-and-organizing-tests#what-isnt-watched", "text": "What isn't watched?", "level": 3 }, { "id": "app/core-concepts/writing-and-organizing-tests#configuration", "text": "Configuration", "level": 3 } ] }, "chunks": [ { "id": "app/core-concepts/writing-and-organizing-tests#what-youll-learn", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "What you'll learn", "heading_level": 5, "content_markdown": "##### What you'll learn\n\n* How to organize your tests in Cypress and the types of supported files\n* How to write tests in Cypress including hooks, exclusions, and configurations\n* Test statuses and how to interpret them\n* What files are automatically watched while writing Cypress tests\n", "section": "app", "anchors": [ "what-youll-learn" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 64 }, { "id": "app/core-concepts/writing-and-organizing-tests#folder-structure", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Folder structure", "heading_level": 2, "content_markdown": "## Folder structure\n\nAfter adding a new project, Cypress will automatically scaffold out a suggested folder structure. By default it will create:\n\n* JavaScript\n* TypeScript\n\n```\nE2E:/cypress.config.js/cypress/fixtures/example.json/cypress/support/commands.js/cypress/support/e2e.jsComponent:/cypress.config.js/cypress/fixtures/example.json/cypress/support/commands.js/cypress/support/component.js/cypress/support/component-index.htmlBoth:/cypress.config.js/cypress/fixtures/example.json/cypress/support/commands.js/cypress/support/e2e.js/cypress/support/component.js/cypress/support/component-index.html\n```\n\n```\nE2E:/cypress.config.ts/cypress/fixtures/example.json/cypress/support/commands.ts/cypress/support/e2e.tsComponent:/cypress.config.ts/cypress/fixtures/example.json/cypress/support/commands.ts/cypress/support/component.ts/cypress/support/component-index.htmlBoth:/cypress.config.ts/cypress/fixtures/example.json/cypress/support/commands.ts/cypress/support/e2e.ts/cypress/support/component.ts/cypress/support/component-index.html\n```\n\n### Configuring Folder Structure\n\nWhile Cypress allows you to configure where your tests, fixtures, and support files are located, if you're starting your first project, we recommend you use the above structure.\n\nYou can modify the folder configuration in your configuration file. See the [Cypress configuration](/llm/markdown/app/references/configuration.md) for more detail.\n\n**What files should I add to my '.gitignore file' ?**\n\nCypress may create [asset files](#Asset-Files) in a [`downloadsFolder`](#Download-Files), a [`screenshotsFolder`](#Screenshot-Files) or a [`videosFolder`](#Video-Files) to store any downloads, screenshots or videos created during the testing of your application. Many users will opt to add these folders to their [.gitignore](https://git-scm.com/docs/gitignore) file (see [below](#Asset-Files) for an example). Additionally, if you are storing sensitive variables in your [Cypress configuration](/llm/markdown/app/references/configuration.md) these should also be ignored when you check into source control.\n\n### Spec files\n\nTest files are located in `cypress/e2e` by default, but can be [configured](/llm/markdown/app/references/configuration.md#e2e) to another directory. Test files may be written as:\n\n* `.js`\n* `.jsx`\n* `.ts`\n* `.tsx`\n* `.coffee`\n* `.cjsx`\n\nCypress also supports `ES2015` out of the box. You can use either `ES2015 modules` or `CommonJS modules`. This means you can `import` or `require` both **npm packages** and **local relative modules**.\n\n**Example Recipe**\n\nCheck out our recipe using [ES2015 and CommonJS modules](/llm/markdown/app/references/recipes.md#Fundamentals).\n\nTo see an example of every command used in Cypress, open the [`2-advanced-examples` folder](https://github.com/cypress-io/cypress-example-kitchensink/tree/master/cypress/e2e/2-advanced-examples) within your `cypress/e2e` folder.\n\n### Fixture Files\n\nFixtures are used as external pieces of static data that can be used by your tests. Fixture files are located in `cypress/fixtures` by default, but can be [configured](/llm/markdown/app/references/configuration.md#Folders--Files) to another directory.\n\nYou would typically use them with the [`cy.fixture()`](/llm/markdown/api/commands/fixture.md) command and most often when you're stubbing [Network Requests](/llm/markdown/app/guides/network-requests.md).\n\n### Asset Files\n\nThere are some folders that may be generated after a test run, containing assets that were generated during the test run.\n\nYou may consider adding these folders to your [.gitignore](https://git-scm.com/docs/gitignore) file to prevent checking files in these folders into source control, for example, using the default folder locations:\n\n```\n# Cypress asset folders to exclude from source controlcypress/downloads/cypress/screenshots/cypress/videos/\n```\n\n#### Download Files\n\nAny files downloaded while testing an application's file download feature will be stored in the [`downloadsFolder`](/llm/markdown/app/references/configuration.md#Downloads) which is set to `cypress/downloads` by default.\n\n```\n/cypress /downloads - records.csv\n```\n\n#### Screenshot Files\n\nIf screenshots were taken via the [cy.screenshot()](/llm/markdown/api/commands/screenshot.md) command or automatically when a test fails, the screenshots are stored in the [`screenshotsFolder`](/llm/markdown/app/references/configuration.md#Screenshots) which is set to `cypress/screenshots` by default.\n\n```\n/cypress /screenshots /app.cy.js - Navigates to main menu (failures).png\n```\n\nTo learn more about screenshots and settings available, see [Screenshots and Videos](/llm/markdown/app/guides/screenshots-and-videos.md#Screenshots)\n\n#### Video Files\n\nAny videos recorded of the run are stored in the [`videosFolder`](/llm/markdown/app/references/configuration.md#Videos) which is set to `cypress/videos` by default.\n\n```\n/cypress /videos - app.cy.js.mp4\n```\n\n#### Asset File Paths\n\nGenerated screenshots and videos are saved inside their respective folders (`cypress/screenshots`, `cypress/videos`). The paths of the generated files will be stripped of any common ancestor paths shared between all spec files found by the `specPattern` option (or via the `--spec` command line option or `spec` module API option, if specified)\n\n**Example 1:**\n\n* Spec file found\n * `cypress/e2e/path/to/file/one.cy.js`\n* Common ancestor paths (calculated at runtime)\n * `cypress/e2e/path/to/file`\n* Generated screenshot file\n * `cypress/screenshots/one.cy.js/your-screenshot.png`\n* Generated video file\n * `cypress/videos/one.cy.js.mp4`\n\n**Example 2:**\n\n* Spec files found\n * `cypress/e2e/path/to/file/one.cy.js`\n * `cypress/e2e/path/to/two.cy.js`\n* Common ancestor paths (calculated at runtime)\n * `cypress/e2e/path/to/`\n* Generated screenshot files\n * `cypress/screenshots/file/one.cy.js/your-screenshot.png`\n * `cypress/screenshots/two.cy.js/your-screenshot.png`\n* Generated video files\n * `cypress/videos/file/one.cy.js.mp4`\n * `cypress/videos/two.cy.js.mp4`\n\n#### Assets in Cypress Cloud\n\nInstead of administering assets yourself, you can [save them to the cloud with Cypress Cloud](/llm/markdown/cloud/features/recorded-runs.md#Run-Details).\n\nReplay the test as it executed during the recorded run with full debug capability using [Cypress Test Replay](/llm/markdown/cloud/features/test-replay.md).\n\nScreenshots and videos are stored permanently, attached to their respective test results, and easily shared or browsed through our web interface. To learn more about videos and settings available, see [Screenshots and Videos](/llm/markdown/app/guides/screenshots-and-videos.md#Screenshots).\n\n### Plugins file\n\nThe plugins file is a special file that executes in Node before the project is loaded, before the browser launches, and during your test execution. While the Cypress tests execute in the browser, the plugins file runs in the background Node process, giving your tests the ability to access the file system and the rest of the operating system by calling the [cy.task()](/llm/markdown/api/commands/task.md) command.\n\nThe plugins file is a good place to define how you want to bundle the spec files via the [preprocessors](/llm/markdown/api/node-events/preprocessors-api.md), how to find and launch the browsers via the [browser launch API](/llm/markdown/api/node-events/browser-launch-api.md), and other cool things. Read our [plugins guide](/llm/markdown/app/plugins/plugins-guide.md) for more details and examples.\n\nThe initial imported plugins file can be [configured to another file](/llm/markdown/app/references/configuration.md#Folders--Files).\n\n### Support file\n\nTo include code before your test files, set the [`supportFile`](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options) path. By default, [`supportFile`](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options) is set to look for one of the following files:\n\n**Component:**\n\n* `cypress/support/component.js`\n* `cypress/support/component.jsx`\n* `cypress/support/component.ts`\n* `cypress/support/component.tsx`\n\n**E2E:**\n\n* `cypress/support/e2e.js`\n* `cypress/support/e2e.jsx`\n* `cypress/support/e2e.ts`\n* `cypress/support/e2e.tsx`\n\nFor a given testing type, multiple matching `supportFile` files will result in an error when Cypress loads.\n\n**supportFile per testing type**\n\nDepending on which [testing type](/llm/markdown/app/core-concepts/testing-types.md) you are using, you can configure your `supportFile` accordingly.\n\n* [Component](/llm/markdown/app/references/configuration.md#component)\n* [E2E](/llm/markdown/app/references/configuration.md#e2e)\n\nCypress automatically creates an example support file for each configured testing type, which has several commented out examples.\n\nThis file runs **before** every single spec file. We do this purely as a convenience mechanism so you don't have to import this file.\n\nBy default Cypress will automatically include type-specific support files. For E2E, the default is `cypress/support/e2e.{js,jsx,ts,tsx}`, and for Component Testing `cypress/support/component.{js,jsx,ts,tsx}`.\n\nThe support file is a great place to put reusable behavior such as [custom commands](/llm/markdown/api/cypress-api/custom-commands.md) or global overrides that you want applied and available to all of your spec files.\n\nThe initial imported support file can be configured to another file or turned off completely using the [supportFile](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options) configuration. From your support file you can `import` or `require` other files to keep things organized.\n\nYou can define behaviors in a `before` or `beforeEach` within any of the `cypress/support` files:\n\n```\nbeforeEach(() => { cy.log('I run before every test in every spec file!!!!!!')})\n```\n\n**Note:** This example assumes you are already familiar with Mocha [hooks](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Hooks).\n\n#### Execution\n\nCypress executes the support file before the spec file. For example, when Cypress executes a spec file via `cypress open` or `cypress run`, it executes the files in the following order:\n\n**e2e example:**\n\n1. `support/e2e.js` (your support file)\n2. `e2e/spec-a.cy.js` (your spec file)\n\n**component example:**\n\n1. `support/component.js` (your support file)\n2. `components/Button/Button.cy.js` (your spec file)\n\n### Troubleshooting\n\nIf Cypress does not find the spec files for some reason, you can troubleshoot its logic by opening or running Cypress with [debug logs](/llm/markdown/app/references/troubleshooting.md#Print-DEBUG-logs) enabled:\n\n```\nDEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-context:sources:ProjectDataSource npx cypress open## orDEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-context:sources:ProjectDataSource npx cypress run\n```\n", "section": "app", "anchors": [ "folder-structure" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 1513 }, { "id": "app/core-concepts/writing-and-organizing-tests#configuring-folder-structure", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Configuring Folder Structure", "heading_level": 3, "content_markdown": "### Configuring Folder Structure\n\nWhile Cypress allows you to configure where your tests, fixtures, and support files are located, if you're starting your first project, we recommend you use the above structure.\n\nYou can modify the folder configuration in your configuration file. See the [Cypress configuration](/llm/markdown/app/references/configuration.md) for more detail.\n\n**What files should I add to my '.gitignore file' ?**\n\nCypress may create [asset files](#Asset-Files) in a [`downloadsFolder`](#Download-Files), a [`screenshotsFolder`](#Screenshot-Files) or a [`videosFolder`](#Video-Files) to store any downloads, screenshots or videos created during the testing of your application. Many users will opt to add these folders to their [.gitignore](https://git-scm.com/docs/gitignore) file (see [below](#Asset-Files) for an example). Additionally, if you are storing sensitive variables in your [Cypress configuration](/llm/markdown/app/references/configuration.md) these should also be ignored when you check into source control.\n", "section": "app", "anchors": [ "configuring-folder-structure" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 167 }, { "id": "app/core-concepts/writing-and-organizing-tests#spec-files", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Spec files", "heading_level": 3, "content_markdown": "### Spec files\n\nTest files are located in `cypress/e2e` by default, but can be [configured](/llm/markdown/app/references/configuration.md#e2e) to another directory. Test files may be written as:\n\n* `.js`\n* `.jsx`\n* `.ts`\n* `.tsx`\n* `.coffee`\n* `.cjsx`\n\nCypress also supports `ES2015` out of the box. You can use either `ES2015 modules` or `CommonJS modules`. This means you can `import` or `require` both **npm packages** and **local relative modules**.\n\n**Example Recipe**\n\nCheck out our recipe using [ES2015 and CommonJS modules](/llm/markdown/app/references/recipes.md#Fundamentals).\n\nTo see an example of every command used in Cypress, open the [`2-advanced-examples` folder](https://github.com/cypress-io/cypress-example-kitchensink/tree/master/cypress/e2e/2-advanced-examples) within your `cypress/e2e` folder.\n", "section": "app", "anchors": [ "spec-files" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 128 }, { "id": "app/core-concepts/writing-and-organizing-tests#fixture-files", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Fixture Files", "heading_level": 3, "content_markdown": "### Fixture Files\n\nFixtures are used as external pieces of static data that can be used by your tests. Fixture files are located in `cypress/fixtures` by default, but can be [configured](/llm/markdown/app/references/configuration.md#Folders--Files) to another directory.\n\nYou would typically use them with the [`cy.fixture()`](/llm/markdown/api/commands/fixture.md) command and most often when you're stubbing [Network Requests](/llm/markdown/app/guides/network-requests.md).\n", "section": "app", "anchors": [ "fixture-files" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 68 }, { "id": "app/core-concepts/writing-and-organizing-tests#asset-files", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Asset Files", "heading_level": 3, "content_markdown": "### Asset Files\n\nThere are some folders that may be generated after a test run, containing assets that were generated during the test run.\n\nYou may consider adding these folders to your [.gitignore](https://git-scm.com/docs/gitignore) file to prevent checking files in these folders into source control, for example, using the default folder locations:\n\n```\n# Cypress asset folders to exclude from source controlcypress/downloads/cypress/screenshots/cypress/videos/\n```\n\n#### Download Files\n\nAny files downloaded while testing an application's file download feature will be stored in the [`downloadsFolder`](/llm/markdown/app/references/configuration.md#Downloads) which is set to `cypress/downloads` by default.\n\n```\n/cypress /downloads - records.csv\n```\n\n#### Screenshot Files\n\nIf screenshots were taken via the [cy.screenshot()](/llm/markdown/api/commands/screenshot.md) command or automatically when a test fails, the screenshots are stored in the [`screenshotsFolder`](/llm/markdown/app/references/configuration.md#Screenshots) which is set to `cypress/screenshots` by default.\n\n```\n/cypress /screenshots /app.cy.js - Navigates to main menu (failures).png\n```\n\nTo learn more about screenshots and settings available, see [Screenshots and Videos](/llm/markdown/app/guides/screenshots-and-videos.md#Screenshots)\n\n#### Video Files\n\nAny videos recorded of the run are stored in the [`videosFolder`](/llm/markdown/app/references/configuration.md#Videos) which is set to `cypress/videos` by default.\n\n```\n/cypress /videos - app.cy.js.mp4\n```\n\n#### Asset File Paths\n\nGenerated screenshots and videos are saved inside their respective folders (`cypress/screenshots`, `cypress/videos`). The paths of the generated files will be stripped of any common ancestor paths shared between all spec files found by the `specPattern` option (or via the `--spec` command line option or `spec` module API option, if specified)\n\n**Example 1:**\n\n* Spec file found\n * `cypress/e2e/path/to/file/one.cy.js`\n* Common ancestor paths (calculated at runtime)\n * `cypress/e2e/path/to/file`\n* Generated screenshot file\n * `cypress/screenshots/one.cy.js/your-screenshot.png`\n* Generated video file\n * `cypress/videos/one.cy.js.mp4`\n\n**Example 2:**\n\n* Spec files found\n * `cypress/e2e/path/to/file/one.cy.js`\n * `cypress/e2e/path/to/two.cy.js`\n* Common ancestor paths (calculated at runtime)\n * `cypress/e2e/path/to/`\n* Generated screenshot files\n * `cypress/screenshots/file/one.cy.js/your-screenshot.png`\n * `cypress/screenshots/two.cy.js/your-screenshot.png`\n* Generated video files\n * `cypress/videos/file/one.cy.js.mp4`\n * `cypress/videos/two.cy.js.mp4`\n\n#### Assets in Cypress Cloud\n\nInstead of administering assets yourself, you can [save them to the cloud with Cypress Cloud](/llm/markdown/cloud/features/recorded-runs.md#Run-Details).\n\nReplay the test as it executed during the recorded run with full debug capability using [Cypress Test Replay](/llm/markdown/cloud/features/test-replay.md).\n\nScreenshots and videos are stored permanently, attached to their respective test results, and easily shared or browsed through our web interface. To learn more about videos and settings available, see [Screenshots and Videos](/llm/markdown/app/guides/screenshots-and-videos.md#Screenshots).\n", "section": "app", "anchors": [ "asset-files" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 485 }, { "id": "app/core-concepts/writing-and-organizing-tests#download-files", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Download Files", "heading_level": 4, "content_markdown": "#### Download Files\n\nAny files downloaded while testing an application's file download feature will be stored in the [`downloadsFolder`](/llm/markdown/app/references/configuration.md#Downloads) which is set to `cypress/downloads` by default.\n\n```\n/cypress /downloads - records.csv\n```\n", "section": "app", "anchors": [ "download-files" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 43 }, { "id": "app/core-concepts/writing-and-organizing-tests#screenshot-files", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Screenshot Files", "heading_level": 4, "content_markdown": "#### Screenshot Files\n\nIf screenshots were taken via the [cy.screenshot()](/llm/markdown/api/commands/screenshot.md) command or automatically when a test fails, the screenshots are stored in the [`screenshotsFolder`](/llm/markdown/app/references/configuration.md#Screenshots) which is set to `cypress/screenshots` by default.\n\n```\n/cypress /screenshots /app.cy.js - Navigates to main menu (failures).png\n```\n\nTo learn more about screenshots and settings available, see [Screenshots and Videos](/llm/markdown/app/guides/screenshots-and-videos.md#Screenshots)\n", "section": "app", "anchors": [ "screenshot-files" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 72 }, { "id": "app/core-concepts/writing-and-organizing-tests#asset-file-paths", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Asset File Paths", "heading_level": 4, "content_markdown": "#### Asset File Paths\n\nGenerated screenshots and videos are saved inside their respective folders (`cypress/screenshots`, `cypress/videos`). The paths of the generated files will be stripped of any common ancestor paths shared between all spec files found by the `specPattern` option (or via the `--spec` command line option or `spec` module API option, if specified)\n\n**Example 1:**\n\n* Spec file found\n * `cypress/e2e/path/to/file/one.cy.js`\n* Common ancestor paths (calculated at runtime)\n * `cypress/e2e/path/to/file`\n* Generated screenshot file\n * `cypress/screenshots/one.cy.js/your-screenshot.png`\n* Generated video file\n * `cypress/videos/one.cy.js.mp4`\n\n**Example 2:**\n\n* Spec files found\n * `cypress/e2e/path/to/file/one.cy.js`\n * `cypress/e2e/path/to/two.cy.js`\n* Common ancestor paths (calculated at runtime)\n * `cypress/e2e/path/to/`\n* Generated screenshot files\n * `cypress/screenshots/file/one.cy.js/your-screenshot.png`\n * `cypress/screenshots/two.cy.js/your-screenshot.png`\n* Generated video files\n * `cypress/videos/file/one.cy.js.mp4`\n * `cypress/videos/two.cy.js.mp4`\n", "section": "app", "anchors": [ "asset-file-paths" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 157 }, { "id": "app/core-concepts/writing-and-organizing-tests#assets-in-cypress-cloud", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Assets in Cypress Cloud", "heading_level": 4, "content_markdown": "#### Assets in Cypress Cloud\n\nInstead of administering assets yourself, you can [save them to the cloud with Cypress Cloud](/llm/markdown/cloud/features/recorded-runs.md#Run-Details).\n\nReplay the test as it executed during the recorded run with full debug capability using [Cypress Test Replay](/llm/markdown/cloud/features/test-replay.md).\n\nScreenshots and videos are stored permanently, attached to their respective test results, and easily shared or browsed through our web interface. To learn more about videos and settings available, see [Screenshots and Videos](/llm/markdown/app/guides/screenshots-and-videos.md#Screenshots).\n", "section": "app", "anchors": [ "assets-in-cypress-cloud" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 95 }, { "id": "app/core-concepts/writing-and-organizing-tests#plugins-file", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Plugins file", "heading_level": 3, "content_markdown": "### Plugins file\n\nThe plugins file is a special file that executes in Node before the project is loaded, before the browser launches, and during your test execution. While the Cypress tests execute in the browser, the plugins file runs in the background Node process, giving your tests the ability to access the file system and the rest of the operating system by calling the [cy.task()](/llm/markdown/api/commands/task.md) command.\n\nThe plugins file is a good place to define how you want to bundle the spec files via the [preprocessors](/llm/markdown/api/node-events/preprocessors-api.md), how to find and launch the browsers via the [browser launch API](/llm/markdown/api/node-events/browser-launch-api.md), and other cool things. Read our [plugins guide](/llm/markdown/app/plugins/plugins-guide.md) for more details and examples.\n\nThe initial imported plugins file can be [configured to another file](/llm/markdown/app/references/configuration.md#Folders--Files).\n", "section": "app", "anchors": [ "plugins-file" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 164 }, { "id": "app/core-concepts/writing-and-organizing-tests#support-file", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Support file", "heading_level": 3, "content_markdown": "### Support file\n\nTo include code before your test files, set the [`supportFile`](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options) path. By default, [`supportFile`](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options) is set to look for one of the following files:\n\n**Component:**\n\n* `cypress/support/component.js`\n* `cypress/support/component.jsx`\n* `cypress/support/component.ts`\n* `cypress/support/component.tsx`\n\n**E2E:**\n\n* `cypress/support/e2e.js`\n* `cypress/support/e2e.jsx`\n* `cypress/support/e2e.ts`\n* `cypress/support/e2e.tsx`\n\nFor a given testing type, multiple matching `supportFile` files will result in an error when Cypress loads.\n\n**supportFile per testing type**\n\nDepending on which [testing type](/llm/markdown/app/core-concepts/testing-types.md) you are using, you can configure your `supportFile` accordingly.\n\n* [Component](/llm/markdown/app/references/configuration.md#component)\n* [E2E](/llm/markdown/app/references/configuration.md#e2e)\n\nCypress automatically creates an example support file for each configured testing type, which has several commented out examples.\n\nThis file runs **before** every single spec file. We do this purely as a convenience mechanism so you don't have to import this file.\n\nBy default Cypress will automatically include type-specific support files. For E2E, the default is `cypress/support/e2e.{js,jsx,ts,tsx}`, and for Component Testing `cypress/support/component.{js,jsx,ts,tsx}`.\n\nThe support file is a great place to put reusable behavior such as [custom commands](/llm/markdown/api/cypress-api/custom-commands.md) or global overrides that you want applied and available to all of your spec files.\n\nThe initial imported support file can be configured to another file or turned off completely using the [supportFile](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options) configuration. From your support file you can `import` or `require` other files to keep things organized.\n\nYou can define behaviors in a `before` or `beforeEach` within any of the `cypress/support` files:\n\n```\nbeforeEach(() => { cy.log('I run before every test in every spec file!!!!!!')})\n```\n\n**Note:** This example assumes you are already familiar with Mocha [hooks](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Hooks).\n\n#### Execution\n\nCypress executes the support file before the spec file. For example, when Cypress executes a spec file via `cypress open` or `cypress run`, it executes the files in the following order:\n\n**e2e example:**\n\n1. `support/e2e.js` (your support file)\n2. `e2e/spec-a.cy.js` (your spec file)\n\n**component example:**\n\n1. `support/component.js` (your support file)\n2. `components/Button/Button.cy.js` (your spec file)\n", "section": "app", "anchors": [ "support-file" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 409 }, { "id": "app/core-concepts/writing-and-organizing-tests#execution", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Execution", "heading_level": 4, "content_markdown": "#### Execution\n\nCypress executes the support file before the spec file. For example, when Cypress executes a spec file via `cypress open` or `cypress run`, it executes the files in the following order:\n\n**e2e example:**\n\n1. `support/e2e.js` (your support file)\n2. `e2e/spec-a.cy.js` (your spec file)\n\n**component example:**\n\n1. `support/component.js` (your support file)\n2. `components/Button/Button.cy.js` (your spec file)\n", "section": "app", "anchors": [ "execution" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 76 }, { "id": "app/core-concepts/writing-and-organizing-tests#troubleshooting", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Troubleshooting", "heading_level": 3, "content_markdown": "### Troubleshooting\n\nIf Cypress does not find the spec files for some reason, you can troubleshoot its logic by opening or running Cypress with [debug logs](/llm/markdown/app/references/troubleshooting.md#Print-DEBUG-logs) enabled:\n\n```\nDEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-context:sources:ProjectDataSource npx cypress open## orDEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-context:sources:ProjectDataSource npx cypress run\n```\n", "section": "app", "anchors": [ "troubleshooting" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 49 }, { "id": "app/core-concepts/writing-and-organizing-tests#writing-tests", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Writing tests", "heading_level": 2, "content_markdown": "## Writing tests\n\nCypress is built on top of [Mocha](/llm/markdown/app/references/bundled-libraries.md#Mocha) and [Chai](/llm/markdown/app/references/bundled-libraries.md#Chai). We support both Chai's `BDD` and `TDD` assertion styles. Tests you write in Cypress will mostly adhere to this style.\n\nIf you're familiar with writing tests in JavaScript, then writing tests in Cypress will be a breeze.\n\nTo start writing tests for your app, follow our guides for writing your first [Component](/llm/markdown/app/component-testing/get-started.md) or [End-to-End](/llm/markdown/app/end-to-end-testing/writing-your-first-end-to-end-test.md) test.\n\nNeeding a low code approach to create tests? Use [Cypress Studio](/llm/markdown/app/guides/cypress-studio.md) to record your browser interactions. With [Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md), you also get **Studio AI**—AI-powered assertion recommendations as you record.\n\n### Test Structure\n\nThe test interface, borrowed from [Mocha](/llm/markdown/app/references/bundled-libraries.md#Mocha), provides `describe()`, `context()`, `it()` and `specify()`.\n\n`context()` is identical to `describe()` and `specify()` is identical to `it()`, so choose whatever terminology works best for you.\n\n```\n// -- Start: Our Application Code --function add(a, b) { return a + b}function subtract(a, b) { return a - b}function divide(a, b) { return a / b}function multiply(a, b) { return a * b}// -- End: Our Application Code --// -- Start: Our Cypress Tests --describe('Unit test our math functions', () => { context('math', () => { it('can add numbers', () => { expect(add(1, 2)).to.eq(3) }) it('can subtract numbers', () => { expect(subtract(5, 12)).to.eq(-7) }) specify('can divide numbers', () => { expect(divide(27, 9)).to.eq(3) }) specify('can multiply numbers', () => { expect(multiply(5, 4)).to.eq(20) }) })})// -- End: Our Cypress Tests --\n```\n\n### Hooks\n\nCypress also provides hooks (borrowed from [Mocha](/llm/markdown/app/references/bundled-libraries.md#Mocha)).\n\nThese are helpful to set conditions that you want to run before a set of tests or before each test. They're also helpful to clean up conditions after a set of tests or after each test.\n\n```\nbefore(() => { // root-level hook // runs once before all tests})beforeEach(() => { // root-level hook // runs before every test block})afterEach(() => { // runs after each test block})after(() => { // runs once all tests are done})describe('Hooks', () => { before(() => { // runs once before all tests in the block }) beforeEach(() => { // runs before each test in the block }) afterEach(() => { // runs after each test in the block }) after(() => { // runs once after all tests in the block })})\n```\n\n#### The order of hook and test execution is as follows:\n\n* All `before()` hooks run (once)\n* Any `beforeEach()` hooks run\n* Tests run\n* Any `afterEach()` hooks run\n* All `after()` hooks run (once)\n\n🚨 Before writing `after()` or `afterEach()` hooks, please see our [thoughts on the anti-pattern of cleaning up state with `after()` or `afterEach()`](/llm/markdown/app/core-concepts/best-practices.md#Using-after-Or-afterEach-Hooks).\n\n### Excluding and Including Tests\n\nTo run a specified suite or test, append `.only` to the function. All nested suites will also be executed. This gives us the ability to run one test at a time and is the recommended way to write a test suite.\n\n```\n// -- Start: Our Application Code --function fizzbuzz(num) { if (num % 3 === 0 && num % 5 === 0) { return 'fizzbuzz' } if (num % 3 === 0) { return 'fizz' } if (num % 5 === 0) { return 'buzz' }}// -- End: Our Application Code --// -- Start: Our Cypress Tests --describe('Unit Test FizzBuzz', () => { function numsExpectedToEq(arr, expected) { // loop through the array of nums and make // sure they equal what is expected arr.forEach((num) => { expect(fizzbuzz(num)).to.eq(expected) }) } // only run this test it.only('returns \"fizz\" when number is multiple of 3', () => { numsExpectedToEq([9, 12, 18], 'fizz') }) it('returns \"buzz\" when number is multiple of 5', () => { numsExpectedToEq([10, 20, 25], 'buzz') }) it('returns \"fizzbuzz\" when number is multiple of both 3 and 5', () => { numsExpectedToEq([15, 30, 60], 'fizzbuzz') })})\n```\n\nTo skip a specified suite or test, append `.skip()` to the function. All nested suites will also be skipped.\n\n```\nit.skip('returns \"fizz\" when number is multiple of 3', () => { numsExpectedToEq([9, 12, 18], 'fizz')})\n```\n\n### Test Isolation\n\n**Best Practice:** Tests should always be able to be run independently from one another **and still pass**.\n\nAs stated in our mission, we hold ourselves accountable to champion a testing process that actually works, and have built Cypress to guide developers towards writing independent tests from the start.\n\nWe do this by cleaning up test state and the browser context _before_ each test to ensure that the operation of one test does not affect another test later on. The goal for each test should be to **reliably pass** whether run in isolation or consecutively with other tests. Having tests that depend on the state of an earlier test can potentially cause nondeterministic test failures which makes debugging challenging.\n\nThe behavior of running tests in a clean browser context is described as `testIsolation`.\n\nThe test isolation is a global configuration and can be overridden for end-to-end testing at the `describe` level with the [`testIsolation`](/llm/markdown/app/references/configuration.md#e2e) option.\n\nTo learn more about this behavior and the trade-offs of disabling it, review our [Test Isolation guide](/llm/markdown/app/core-concepts/test-isolation.md).\n\n### Test Configuration\n\nIt is possible to apply [test configuration](/llm/markdown/app/references/configuration.md#Test-Configuration) values to a suite or test. Pass a configuration object to the test or suite function as the second argument.\n\nThis configuration will take effect during the suite or tests where they are set then return to their previous default values after the suite or tests are complete.\n\n#### Syntax\n\n```\ndescribe(name, config, fn)context(name, config, fn)it(name, config, fn)specify(name, config, fn)\n```\n\n#### Allowed config values\n\n**Note:** Some configuration values are readonly and cannot be changed via test configuration. Be sure to review the list of [test configuration options](/llm/markdown/app/references/configuration.md#Test-Configuration).\n\n#### Suite configuration\n\nIf you want to target a suite of tests to run or be excluded when run in a specific browser, you can override the `browser` configuration within the suite configuration. The `browser` option accepts the same arguments as [Cypress.isBrowser()](/llm/markdown/api/cypress-api/isbrowser.md).\n\nThe following suite of tests will be skipped if running tests in Chrome browsers.\n\n```\ndescribe('When NOT in Chrome', { browser: '!chrome' }, () => { it('Shows warning', () => { cy.get('[data-testid=\"browser-warning\"]').should( 'contain', 'For optimal viewing, use Chrome browser' ) }) it('Links to browser compatibility doc', () => { cy.get('a.browser-compat') .should('have.attr', 'href') .and('include', 'browser-compatibility') })})\n```\n\nThe following suite of tests will only execute when running in the Firefox browser. Additionally, it will overwrite the viewport resolution.\n\n```\ndescribe( 'When in Firefox', { browser: 'firefox', viewportWidth: 1024, viewportHeight: 700, }, () => { it('Sets the expected viewport and API URL', () => { expect(cy.config('viewportWidth')).to.equal(1024) expect(cy.config('viewportHeight')).to.equal(700) }) })\n```\n\n#### Single test configuration\n\nYou can configure the number of retry attempts during `cypress run` or `cypress open`. See [Test Retries](/llm/markdown/app/guides/test-retries.md) for more information.\n\n```\nit('should redirect unauthenticated user to sign-in page', { retries: { runMode: 3, openMode: 2 } } () => { // test code... })})\n```\n\n### Dynamically Generate Tests\n\nYou can dynamically generate tests using JavaScript.\n\n```\ndescribe('if your app uses jQuery', () => { ;['mouseover', 'mouseout', 'mouseenter', 'mouseleave'].forEach((event) => { it('triggers event: ' + event, () => { // if your app uses jQuery, then we can trigger a jQuery // event that causes the event callback to fire cy.get('#with-jquery') .invoke('trigger', event) .get('[data-testid=\"messages\"]') .should('contain', 'the event ' + event + 'was fired') }) })})\n```\n\nThe code above will produce a suite with 4 tests:\n\n```\n> if your app uses jQuery > triggers event: 'mouseover' > triggers event: 'mouseout' > triggers event: 'mouseenter' > triggers event: 'mouseleave'\n```\n\n### Assertion Styles\n\nCypress supports both BDD (`expect`/`should`) and TDD (`assert`) style plain assertions. [Read more about plain assertions.](/llm/markdown/app/references/assertions.md)\n\n```\nit('can add numbers', () => { expect(add(1, 2)).to.eq(3)})it('can subtract numbers', () => { assert.equal(subtract(5, 12), -7, 'these numbers are equal')})\n```\n\nThe [.should()](/llm/markdown/api/commands/should.md) command and its alias [.and()](/llm/markdown/api/commands/and.md) can also be used to more easily chain assertions off of Cypress commands. [Read more about assertions.](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)\n\n```\ncy.wrap(add(1, 2)).should('equal', 3)\n```\n", "section": "app", "anchors": [ "writing-tests" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 1740 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-structure", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Test Structure", "heading_level": 3, "content_markdown": "### Test Structure\n\nThe test interface, borrowed from [Mocha](/llm/markdown/app/references/bundled-libraries.md#Mocha), provides `describe()`, `context()`, `it()` and `specify()`.\n\n`context()` is identical to `describe()` and `specify()` is identical to `it()`, so choose whatever terminology works best for you.\n\n```\n// -- Start: Our Application Code --function add(a, b) { return a + b}function subtract(a, b) { return a - b}function divide(a, b) { return a / b}function multiply(a, b) { return a * b}// -- End: Our Application Code --// -- Start: Our Cypress Tests --describe('Unit test our math functions', () => { context('math', () => { it('can add numbers', () => { expect(add(1, 2)).to.eq(3) }) it('can subtract numbers', () => { expect(subtract(5, 12)).to.eq(-7) }) specify('can divide numbers', () => { expect(divide(27, 9)).to.eq(3) }) specify('can multiply numbers', () => { expect(multiply(5, 4)).to.eq(20) }) })})// -- End: Our Cypress Tests --\n```\n", "section": "app", "anchors": [ "test-structure" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 183 }, { "id": "app/core-concepts/writing-and-organizing-tests#hooks", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Hooks", "heading_level": 3, "content_markdown": "### Hooks\n\nCypress also provides hooks (borrowed from [Mocha](/llm/markdown/app/references/bundled-libraries.md#Mocha)).\n\nThese are helpful to set conditions that you want to run before a set of tests or before each test. They're also helpful to clean up conditions after a set of tests or after each test.\n\n```\nbefore(() => { // root-level hook // runs once before all tests})beforeEach(() => { // root-level hook // runs before every test block})afterEach(() => { // runs after each test block})after(() => { // runs once all tests are done})describe('Hooks', () => { before(() => { // runs once before all tests in the block }) beforeEach(() => { // runs before each test in the block }) afterEach(() => { // runs after each test in the block }) after(() => { // runs once after all tests in the block })})\n```\n\n#### The order of hook and test execution is as follows:\n\n* All `before()` hooks run (once)\n* Any `beforeEach()` hooks run\n* Tests run\n* Any `afterEach()` hooks run\n* All `after()` hooks run (once)\n\n🚨 Before writing `after()` or `afterEach()` hooks, please see our [thoughts on the anti-pattern of cleaning up state with `after()` or `afterEach()`](/llm/markdown/app/core-concepts/best-practices.md#Using-after-Or-afterEach-Hooks).\n", "section": "app", "anchors": [ "hooks" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 264 }, { "id": "app/core-concepts/writing-and-organizing-tests#the-order-of-hook-and-test-execution-is-as-follows", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "The order of hook and test execution is as follows:", "heading_level": 4, "content_markdown": "#### The order of hook and test execution is as follows:\n\n* All `before()` hooks run (once)\n* Any `beforeEach()` hooks run\n* Tests run\n* Any `afterEach()` hooks run\n* All `after()` hooks run (once)\n\n🚨 Before writing `after()` or `afterEach()` hooks, please see our [thoughts on the anti-pattern of cleaning up state with `after()` or `afterEach()`](/llm/markdown/app/core-concepts/best-practices.md#Using-after-Or-afterEach-Hooks).\n", "section": "app", "anchors": [ "the-order-of-hook-and-test-execution-is-as-follows" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 77 }, { "id": "app/core-concepts/writing-and-organizing-tests#excluding-and-including-tests", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Excluding and Including Tests", "heading_level": 3, "content_markdown": "### Excluding and Including Tests\n\nTo run a specified suite or test, append `.only` to the function. All nested suites will also be executed. This gives us the ability to run one test at a time and is the recommended way to write a test suite.\n\n```\n// -- Start: Our Application Code --function fizzbuzz(num) { if (num % 3 === 0 && num % 5 === 0) { return 'fizzbuzz' } if (num % 3 === 0) { return 'fizz' } if (num % 5 === 0) { return 'buzz' }}// -- End: Our Application Code --// -- Start: Our Cypress Tests --describe('Unit Test FizzBuzz', () => { function numsExpectedToEq(arr, expected) { // loop through the array of nums and make // sure they equal what is expected arr.forEach((num) => { expect(fizzbuzz(num)).to.eq(expected) }) } // only run this test it.only('returns \"fizz\" when number is multiple of 3', () => { numsExpectedToEq([9, 12, 18], 'fizz') }) it('returns \"buzz\" when number is multiple of 5', () => { numsExpectedToEq([10, 20, 25], 'buzz') }) it('returns \"fizzbuzz\" when number is multiple of both 3 and 5', () => { numsExpectedToEq([15, 30, 60], 'fizzbuzz') })})\n```\n\nTo skip a specified suite or test, append `.skip()` to the function. All nested suites will also be skipped.\n\n```\nit.skip('returns \"fizz\" when number is multiple of 3', () => { numsExpectedToEq([9, 12, 18], 'fizz')})\n```\n", "section": "app", "anchors": [ "excluding-and-including-tests" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 304 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-isolation", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Test Isolation", "heading_level": 3, "content_markdown": "### Test Isolation\n\n**Best Practice:** Tests should always be able to be run independently from one another **and still pass**.\n\nAs stated in our mission, we hold ourselves accountable to champion a testing process that actually works, and have built Cypress to guide developers towards writing independent tests from the start.\n\nWe do this by cleaning up test state and the browser context _before_ each test to ensure that the operation of one test does not affect another test later on. The goal for each test should be to **reliably pass** whether run in isolation or consecutively with other tests. Having tests that depend on the state of an earlier test can potentially cause nondeterministic test failures which makes debugging challenging.\n\nThe behavior of running tests in a clean browser context is described as `testIsolation`.\n\nThe test isolation is a global configuration and can be overridden for end-to-end testing at the `describe` level with the [`testIsolation`](/llm/markdown/app/references/configuration.md#e2e) option.\n\nTo learn more about this behavior and the trade-offs of disabling it, review our [Test Isolation guide](/llm/markdown/app/core-concepts/test-isolation.md).\n", "section": "app", "anchors": [ "test-isolation" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 232 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-configuration", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Test Configuration", "heading_level": 3, "content_markdown": "### Test Configuration\n\nIt is possible to apply [test configuration](/llm/markdown/app/references/configuration.md#Test-Configuration) values to a suite or test. Pass a configuration object to the test or suite function as the second argument.\n\nThis configuration will take effect during the suite or tests where they are set then return to their previous default values after the suite or tests are complete.\n\n#### Syntax\n\n```\ndescribe(name, config, fn)context(name, config, fn)it(name, config, fn)specify(name, config, fn)\n```\n\n#### Allowed config values\n\n**Note:** Some configuration values are readonly and cannot be changed via test configuration. Be sure to review the list of [test configuration options](/llm/markdown/app/references/configuration.md#Test-Configuration).\n\n#### Suite configuration\n\nIf you want to target a suite of tests to run or be excluded when run in a specific browser, you can override the `browser` configuration within the suite configuration. The `browser` option accepts the same arguments as [Cypress.isBrowser()](/llm/markdown/api/cypress-api/isbrowser.md).\n\nThe following suite of tests will be skipped if running tests in Chrome browsers.\n\n```\ndescribe('When NOT in Chrome', { browser: '!chrome' }, () => { it('Shows warning', () => { cy.get('[data-testid=\"browser-warning\"]').should( 'contain', 'For optimal viewing, use Chrome browser' ) }) it('Links to browser compatibility doc', () => { cy.get('a.browser-compat') .should('have.attr', 'href') .and('include', 'browser-compatibility') })})\n```\n\nThe following suite of tests will only execute when running in the Firefox browser. Additionally, it will overwrite the viewport resolution.\n\n```\ndescribe( 'When in Firefox', { browser: 'firefox', viewportWidth: 1024, viewportHeight: 700, }, () => { it('Sets the expected viewport and API URL', () => { expect(cy.config('viewportWidth')).to.equal(1024) expect(cy.config('viewportHeight')).to.equal(700) }) })\n```\n\n#### Single test configuration\n\nYou can configure the number of retry attempts during `cypress run` or `cypress open`. See [Test Retries](/llm/markdown/app/guides/test-retries.md) for more information.\n\n```\nit('should redirect unauthenticated user to sign-in page', { retries: { runMode: 3, openMode: 2 } } () => { // test code... })})\n```\n", "section": "app", "anchors": [ "test-configuration" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 396 }, { "id": "app/core-concepts/writing-and-organizing-tests#suite-configuration", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Suite configuration", "heading_level": 4, "content_markdown": "#### Suite configuration\n\nIf you want to target a suite of tests to run or be excluded when run in a specific browser, you can override the `browser` configuration within the suite configuration. The `browser` option accepts the same arguments as [Cypress.isBrowser()](/llm/markdown/api/cypress-api/isbrowser.md).\n\nThe following suite of tests will be skipped if running tests in Chrome browsers.\n\n```\ndescribe('When NOT in Chrome', { browser: '!chrome' }, () => { it('Shows warning', () => { cy.get('[data-testid=\"browser-warning\"]').should( 'contain', 'For optimal viewing, use Chrome browser' ) }) it('Links to browser compatibility doc', () => { cy.get('a.browser-compat') .should('have.attr', 'href') .and('include', 'browser-compatibility') })})\n```\n\nThe following suite of tests will only execute when running in the Firefox browser. Additionally, it will overwrite the viewport resolution.\n\n```\ndescribe( 'When in Firefox', { browser: 'firefox', viewportWidth: 1024, viewportHeight: 700, }, () => { it('Sets the expected viewport and API URL', () => { expect(cy.config('viewportWidth')).to.equal(1024) expect(cy.config('viewportHeight')).to.equal(700) }) })\n```\n", "section": "app", "anchors": [ "suite-configuration" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 200 }, { "id": "app/core-concepts/writing-and-organizing-tests#single-test-configuration", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Single test configuration", "heading_level": 4, "content_markdown": "#### Single test configuration\n\nYou can configure the number of retry attempts during `cypress run` or `cypress open`. See [Test Retries](/llm/markdown/app/guides/test-retries.md) for more information.\n\n```\nit('should redirect unauthenticated user to sign-in page', { retries: { runMode: 3, openMode: 2 } } () => { // test code... })})\n```\n", "section": "app", "anchors": [ "single-test-configuration" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 65 }, { "id": "app/core-concepts/writing-and-organizing-tests#dynamically-generate-tests", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Dynamically Generate Tests", "heading_level": 3, "content_markdown": "### Dynamically Generate Tests\n\nYou can dynamically generate tests using JavaScript.\n\n```\ndescribe('if your app uses jQuery', () => { ;['mouseover', 'mouseout', 'mouseenter', 'mouseleave'].forEach((event) => { it('triggers event: ' + event, () => { // if your app uses jQuery, then we can trigger a jQuery // event that causes the event callback to fire cy.get('#with-jquery') .invoke('trigger', event) .get('[data-testid=\"messages\"]') .should('contain', 'the event ' + event + 'was fired') }) })})\n```\n\nThe code above will produce a suite with 4 tests:\n\n```\n> if your app uses jQuery > triggers event: 'mouseover' > triggers event: 'mouseout' > triggers event: 'mouseenter' > triggers event: 'mouseleave'\n```\n", "section": "app", "anchors": [ "dynamically-generate-tests" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 140 }, { "id": "app/core-concepts/writing-and-organizing-tests#assertion-styles", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Assertion Styles", "heading_level": 3, "content_markdown": "### Assertion Styles\n\nCypress supports both BDD (`expect`/`should`) and TDD (`assert`) style plain assertions. [Read more about plain assertions.](/llm/markdown/app/references/assertions.md)\n\n```\nit('can add numbers', () => { expect(add(1, 2)).to.eq(3)})it('can subtract numbers', () => { assert.equal(subtract(5, 12), -7, 'these numbers are equal')})\n```\n\nThe [.should()](/llm/markdown/api/commands/should.md) command and its alias [.and()](/llm/markdown/api/commands/and.md) can also be used to more easily chain assertions off of Cypress commands. [Read more about assertions.](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)\n\n```\ncy.wrap(add(1, 2)).should('equal', 3)\n```\n", "section": "app", "anchors": [ "assertion-styles" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 93 }, { "id": "app/core-concepts/writing-and-organizing-tests#running-tests", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Running tests", "heading_level": 2, "content_markdown": "## Running tests\n\nYou can run a test by clicking on the spec filename. For example the [Cypress RealWorld App](https://github.com/cypress-io/cypress-example-realworld) has multiple test files, but below we run the \"new-transaction.spec.ts\" test file by clicking on it.\n", "section": "app", "anchors": [ "running-tests" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 48 }, { "id": "app/core-concepts/writing-and-organizing-tests#test-statuses", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Test statuses", "heading_level": 2, "content_markdown": "## Test statuses\n\nAfter the Cypress spec completes every test has one of four statuses: **passed**, **failed**, **pending**, or **skipped**. The behavior of these statuses are inherited from the Mocha, since this is the test runner leveraged by Cypress.\n\n### Passed\n\nPassed tests have successfully completed all their hooks and commands without failing any assertions. The test screenshot below shows a passed test:\n\nNote that a test can pass after several [test retries](/llm/markdown/app/guides/test-retries.md). In that case the Command Log shows some failed attempts, but ultimately the entire test finishes successfully.\n\n### Failed\n\nGood news - the failed hook or test has found a problem. Could be much worse - it could be a user hitting this bug!\n\nAfter a test fails, the [Test Replay](/llm/markdown/cloud/features/test-replay.md) or screenshots and videos with Cypress Cloud can help find the problem so it can be fixed.\n\n### Pending\n\nYou can write _placeholder_ tests in several ways as shown below, and Cypress knows NOT to run them. Additionally, you can conditionally specify which browser(s) and tests should run, including if the test should not run for the browser currently being tested, it is marked as _pending_.\n\nCypress marks all the tests below as _pending_.\n\n```\ndescribe('TodoMVC', () => { it('is not written yet') it.skip('adds 2 todos', function () { cy.visit('/') cy.get('[data-testid=\"new-todo\"]').as('new').type('learn testing{enter}') cy.get('@new').type('be cool{enter}') cy.get('[data-testid=\"todo-list\"] li').should('have.length', 100) }) xit('another test', () => { expect(false).to.true }) it('only test chrome', { browser: 'chrome' }, () => { cy.visit('/') cy.contains('To Do') })})\n```\n\nAll four tests above are marked _pending_ when Cypress finishes running the spec file.\n\nSo remember - if you (the test writer) knowingly skip a test using one of the above three ways, Cypress counts it as a _pending_ test.\n\n### Skipped\n\nThe last test status is for tests that you _meant_ to run, but these tests were skipped due to some run-time error. For example, imagine a group of tests sharing the same `beforeEach` hook - where you visit the page in the `beforeEach` hook.\n\nIf a command inside the `beforeEach` hook fails - for example, if we want to visit a non-existent page `/does-not-exist` instead of the `/` - and we change our `beforeEach` to fail:\n\n```\nbeforeEach(() => { cy.visit('/does-not-exist')})\n```\n\nWhen Cypress starts executing the first test, the `beforeEach` hook fails. Now the first test is marked as **failed**. BUT if the `beforeEach` hook failed once, why would we execute it _again_ before the second test? It would just fail the same way! So Cypress _skips_ the remaining tests in that block, because they would also fail due to the `beforeEach` hook failure.\n\nIf we collapse the test commands, we can see the empty box marking the skipped test \"adds 2 todos\".\n\nThe tests that were meant to be executed but were skipped due to some run-time problem are marked \"skipped\" by Cypress. This is typically observed when a `before`, `beforeEach` or `afterEach` hook fails.\n", "section": "app", "anchors": [ "test-statuses" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 644 }, { "id": "app/core-concepts/writing-and-organizing-tests#passed", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Passed", "heading_level": 3, "content_markdown": "### Passed\n\nPassed tests have successfully completed all their hooks and commands without failing any assertions. The test screenshot below shows a passed test:\n\nNote that a test can pass after several [test retries](/llm/markdown/app/guides/test-retries.md). In that case the Command Log shows some failed attempts, but ultimately the entire test finishes successfully.\n", "section": "app", "anchors": [ "passed" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 68 }, { "id": "app/core-concepts/writing-and-organizing-tests#failed", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Failed", "heading_level": 3, "content_markdown": "### Failed\n\nGood news - the failed hook or test has found a problem. Could be much worse - it could be a user hitting this bug!\n\nAfter a test fails, the [Test Replay](/llm/markdown/cloud/features/test-replay.md) or screenshots and videos with Cypress Cloud can help find the problem so it can be fixed.\n", "section": "app", "anchors": [ "failed" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 68 }, { "id": "app/core-concepts/writing-and-organizing-tests#pending", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Pending", "heading_level": 3, "content_markdown": "### Pending\n\nYou can write _placeholder_ tests in several ways as shown below, and Cypress knows NOT to run them. Additionally, you can conditionally specify which browser(s) and tests should run, including if the test should not run for the browser currently being tested, it is marked as _pending_.\n\nCypress marks all the tests below as _pending_.\n\n```\ndescribe('TodoMVC', () => { it('is not written yet') it.skip('adds 2 todos', function () { cy.visit('/') cy.get('[data-testid=\"new-todo\"]').as('new').type('learn testing{enter}') cy.get('@new').type('be cool{enter}') cy.get('[data-testid=\"todo-list\"] li').should('have.length', 100) }) xit('another test', () => { expect(false).to.true }) it('only test chrome', { browser: 'chrome' }, () => { cy.visit('/') cy.contains('To Do') })})\n```\n\nAll four tests above are marked _pending_ when Cypress finishes running the spec file.\n\nSo remember - if you (the test writer) knowingly skip a test using one of the above three ways, Cypress counts it as a _pending_ test.\n", "section": "app", "anchors": [ "pending" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 191 }, { "id": "app/core-concepts/writing-and-organizing-tests#skipped", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Skipped", "heading_level": 3, "content_markdown": "### Skipped\n\nThe last test status is for tests that you _meant_ to run, but these tests were skipped due to some run-time error. For example, imagine a group of tests sharing the same `beforeEach` hook - where you visit the page in the `beforeEach` hook.\n\nIf a command inside the `beforeEach` hook fails - for example, if we want to visit a non-existent page `/does-not-exist` instead of the `/` - and we change our `beforeEach` to fail:\n\n```\nbeforeEach(() => { cy.visit('/does-not-exist')})\n```\n\nWhen Cypress starts executing the first test, the `beforeEach` hook fails. Now the first test is marked as **failed**. BUT if the `beforeEach` hook failed once, why would we execute it _again_ before the second test? It would just fail the same way! So Cypress _skips_ the remaining tests in that block, because they would also fail due to the `beforeEach` hook failure.\n\nIf we collapse the test commands, we can see the empty box marking the skipped test \"adds 2 todos\".\n\nThe tests that were meant to be executed but were skipped due to some run-time problem are marked \"skipped\" by Cypress. This is typically observed when a `before`, `beforeEach` or `afterEach` hook fails.\n", "section": "app", "anchors": [ "skipped" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 265 }, { "id": "app/core-concepts/writing-and-organizing-tests#watching-tests", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Watching tests", "heading_level": 2, "content_markdown": "## Watching tests\n\nWhen running in using [cypress open](/llm/markdown/app/references/command-line.md#cypress-open), Cypress watches the filesystem for changes to your spec files. Soon after adding or updating a test Cypress will reload it and run all of the tests in that spec file.\n\nThis makes for a productive development experience because you can add and edit tests as you're implementing a feature and the Cypress user interface will always reflect the results of your latest edits.\n\nRemember to use [`.only`](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Excluding-and-Including-Tests) to limit which tests are run: this can be especially useful when you've got a lot of tests in a single spec file that you're constantly editing; consider also splitting your tests into smaller files each dealing with logically related behavior.\n\n### What is watched?\n\n#### Files\n\n* [Cypress configuration](/llm/markdown/app/references/configuration.md)\n* [cypress.env.json](/llm/markdown/app/guides/environment-variables.md#2-cypressenvjson)\n\n#### Folders\n\n* E2E directory (`cypress/e2e/` by default)\n* Support directory (`cypress/support/` by default)\n\nThe folder, the files within the folder, and all child folders and their files (recursively) are watched.\n\nThose folder paths refer to the [default folder paths](/llm/markdown/app/references/configuration.md#Folders--Files). If you've configured Cypress to use different folder paths then the folders specific to your configuration will be watched.\n\n### What isn't watched?\n\nEverything else; this includes, but isn't limited to, the following:\n\n* Your application code\n* `node_modules`\n* `cypress/fixtures/`\n\nIf you're developing using a modern JS-based web application stack then you've likely got support for some form of hot module replacement which is responsible for watching your application code—HTML, CSS, JS, etc.—and transparently reloading your application in response to changes.\n\n### Configuration\n\nSet the [`watchForFileChanges`](/llm/markdown/app/references/configuration.md#Global) configuration property to `false` to disable file watching.\n\n**Nothing** is watched during [cypress run](/llm/markdown/app/references/command-line.md#cypress-run).\n\nThe `watchForFileChanges` property is only in effect when running Cypress using [cypress open](/llm/markdown/app/references/command-line.md#cypress-open).\n\nThe component responsible for the file-watching behavior in Cypress is the [`webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor). This is the default file-watcher packaged with Cypress.\n\nIf you need further control of the file-watching behavior you can configure this preprocessor explicitly: it exposes options that allow you to configure behavior such as _what_ is watched and the delay before emitting an \"update\" event after a change.\n\nCypress also ships other [file-watching preprocessors](/llm/markdown/app/plugins/plugins-list.md) - you'll have to configure these explicitly if you want to use them.\n\n* [Cypress Watch Preprocessor](https://github.com/cypress-io/cypress-watch-preprocessor)\n* [Cypress webpack Preprocessor](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor)\n", "section": "app", "anchors": [ "watching-tests" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 493 }, { "id": "app/core-concepts/writing-and-organizing-tests#what-is-watched", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "What is watched?", "heading_level": 3, "content_markdown": "### What is watched?\n\n#### Files\n\n* [Cypress configuration](/llm/markdown/app/references/configuration.md)\n* [cypress.env.json](/llm/markdown/app/guides/environment-variables.md#2-cypressenvjson)\n\n#### Folders\n\n* E2E directory (`cypress/e2e/` by default)\n* Support directory (`cypress/support/` by default)\n\nThe folder, the files within the folder, and all child folders and their files (recursively) are watched.\n\nThose folder paths refer to the [default folder paths](/llm/markdown/app/references/configuration.md#Folders--Files). If you've configured Cypress to use different folder paths then the folders specific to your configuration will be watched.\n", "section": "app", "anchors": [ "what-is-watched" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 93 }, { "id": "app/core-concepts/writing-and-organizing-tests#folders", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Folders", "heading_level": 4, "content_markdown": "#### Folders\n\n* E2E directory (`cypress/e2e/` by default)\n* Support directory (`cypress/support/` by default)\n\nThe folder, the files within the folder, and all child folders and their files (recursively) are watched.\n\nThose folder paths refer to the [default folder paths](/llm/markdown/app/references/configuration.md#Folders--Files). If you've configured Cypress to use different folder paths then the folders specific to your configuration will be watched.\n", "section": "app", "anchors": [ "folders" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 79 }, { "id": "app/core-concepts/writing-and-organizing-tests#what-isnt-watched", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "What isn't watched?", "heading_level": 3, "content_markdown": "### What isn't watched?\n\nEverything else; this includes, but isn't limited to, the following:\n\n* Your application code\n* `node_modules`\n* `cypress/fixtures/`\n\nIf you're developing using a modern JS-based web application stack then you've likely got support for some form of hot module replacement which is responsible for watching your application code—HTML, CSS, JS, etc.—and transparently reloading your application in response to changes.\n", "section": "app", "anchors": [ "what-isnt-watched" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 84 }, { "id": "app/core-concepts/writing-and-organizing-tests#configuration", "doc_id": "app/core-concepts/writing-and-organizing-tests", "heading": "Configuration", "heading_level": 3, "content_markdown": "### Configuration\n\nSet the [`watchForFileChanges`](/llm/markdown/app/references/configuration.md#Global) configuration property to `false` to disable file watching.\n\n**Nothing** is watched during [cypress run](/llm/markdown/app/references/command-line.md#cypress-run).\n\nThe `watchForFileChanges` property is only in effect when running Cypress using [cypress open](/llm/markdown/app/references/command-line.md#cypress-open).\n\nThe component responsible for the file-watching behavior in Cypress is the [`webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor). This is the default file-watcher packaged with Cypress.\n\nIf you need further control of the file-watching behavior you can configure this preprocessor explicitly: it exposes options that allow you to configure behavior such as _what_ is watched and the delay before emitting an \"update\" event after a change.\n\nCypress also ships other [file-watching preprocessors](/llm/markdown/app/plugins/plugins-list.md) - you'll have to configure these explicitly if you want to use them.\n\n* [Cypress Watch Preprocessor](https://github.com/cypress-io/cypress-watch-preprocessor)\n* [Cypress webpack Preprocessor](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor)\n", "section": "app", "anchors": [ "configuration" ], "path": "/llm/json/chunked/app/core-concepts/writing-and-organizing-tests.json", "token_estimate": 159 } ] }