Cypress folder structure - Deep Dive

Overview - Cypress folder structure

What is it?

Cypress folder structure is the way files and folders are organized in a Cypress testing project. It helps keep tests, configuration, and support files in clear places. This structure makes it easier to write, run, and maintain automated tests for web applications. It is designed to be simple and intuitive for testers of all skill levels.

Why it matters

Without a clear folder structure, test projects become messy and hard to manage. Testers might lose track of where tests or helpers are, causing confusion and errors. A good structure saves time, reduces mistakes, and helps teams work together smoothly. It also makes scaling tests easier as projects grow.

Where it fits

Before learning Cypress folder structure, you should know basic web testing concepts and how Cypress runs tests. After this, you can learn how to write tests, use Cypress commands, and organize complex test suites. This knowledge fits early in the Cypress learning path, right after installation and setup.

Mental Model

Core Idea

Cypress folder structure organizes tests and support files into clear, standard folders to keep testing projects clean and manageable.

Think of it like...

It's like organizing your desk with labeled drawers: one for pens, one for papers, one for tools. When you need something, you know exactly where to look without making a mess.

cypress_project/
├── cypress/
│   ├── fixtures/       # Sample data files
│   ├── integration/    # Test spec files
│   ├── plugins/        # Extend Cypress with plugins
│   └── support/        # Custom commands and reusable code
├── cypress.json        # Configuration file
└── package.json        # Project metadata and dependencies

Build-Up - 7 Steps

1

Foundation

Basic Cypress Project Setup

Concept: Introduce the main folders Cypress creates by default.

When you run 'npx cypress open' for the first time, Cypress creates a folder named 'cypress' with subfolders: 'integration', 'fixtures', 'plugins', and 'support'. Each folder has a specific role to keep tests organized.

Result

You get a ready-to-use folder structure that separates test files, test data, plugins, and support code.

Understanding the default folders helps you know where to put each type of file, preventing confusion as your tests grow.

2

Foundation

Role of Each Default Folder

Concept: Explain what each default folder is for in simple terms.

Integration folder holds your test scripts that run in the browser. Fixtures store sample data like JSON files for testing. Plugins allow you to add or modify Cypress behavior. Support contains reusable commands and setup code that runs before tests.

Result

You can correctly place your test code, data, and helpers in the right folders.

Knowing folder roles prevents mixing different types of files, which keeps tests clean and easier to maintain.

3

Intermediate

Customizing Folder Structure

🤔Before reading on: do you think Cypress allows changing default folder names or locations? Commit to your answer.

Concept: Learn how to customize folder paths in Cypress configuration.

Cypress lets you change default folder locations by editing 'cypress.json' or 'cypress.config.js'. For example, you can set 'integrationFolder' to a different path if you want to organize tests differently. This flexibility helps fit Cypress into existing project structures.

Result

You can adapt Cypress folder structure to your team's preferences or project needs.

Knowing how to customize folders helps integrate Cypress smoothly into diverse projects without forcing a fixed layout.

4

Intermediate

Organizing Tests Within Integration Folder

🤔Before reading on: do you think all test files must be in one folder, or can they be grouped in subfolders? Commit to your answer.

Concept: Learn to create subfolders inside 'integration' to group tests logically.

You can create subfolders inside 'integration' like 'login', 'checkout', or 'dashboard' to group related tests. Cypress will find and run all test files recursively. This helps keep tests organized by feature or module.

Result

Tests are easier to find and maintain as your suite grows.

Organizing tests by feature reduces confusion and speeds up debugging when tests fail.

5

Intermediate

Using Support Folder for Reusable Code

Concept: Understand how to use the support folder to share code across tests.

The 'support' folder contains files like 'commands.js' where you can write custom commands or setup code that runs before every test. This avoids repeating code and keeps tests simple. You can import helper functions here too.

Result

Your tests become cleaner and easier to read because common code is centralized.

Centralizing reusable code prevents duplication and makes updates easier across all tests.

6

Advanced

Plugins Folder for Extending Cypress

🤔Before reading on: do you think plugins run inside the browser or Node.js? Commit to your answer.

Concept: Learn how plugins work and where to put them.

Plugins run in the Node.js environment, not the browser. The 'plugins' folder contains 'index.js' where you can add code to modify Cypress behavior, like changing browser launch options or adding tasks. Plugins help integrate Cypress with other tools or customize test runs.

Result

You can extend Cypress capabilities beyond default features.

Knowing plugins run outside the browser clarifies their role and prevents confusion about where code executes.

7

Expert

Advanced Folder Structure for Large Projects

🤔Before reading on: do you think a flat folder structure works well for hundreds of tests? Commit to your answer.

Concept: Explore best practices for scaling folder structure in big projects.

Large projects often create multiple layers of subfolders in 'integration' to separate tests by domain, feature, or test type (e.g., 'e2e', 'api'). They may also add folders like 'utils' inside 'support' for helpers. Some teams split tests by environment or user roles. Keeping a consistent naming scheme and structure is key.

Result

Your test suite stays manageable and scalable even as it grows very large.

A well-planned folder structure prevents chaos and supports team collaboration in complex projects.

Under the Hood

Cypress reads the folder paths from its configuration file at startup. It scans the 'integration' folder recursively to find all test files with supported extensions. The 'support' files are automatically loaded before tests run to set up commands and hooks. Plugins run in a separate Node.js process to extend Cypress's core functionality without affecting browser tests.

Why designed this way?

The structure was designed to separate concerns clearly: tests, data, helpers, and extensions. This separation helps beginners understand where to put files and allows advanced users to customize behavior. Running plugins outside the browser avoids security and performance issues. The default structure balances simplicity and flexibility.

Cypress Project
├─ cypress.json (config)
├─ cypress/
│  ├─ integration/ (test files)
│  │   ├─ featureA/
│  │   └─ featureB/
│  ├─ fixtures/ (test data)
│  ├─ support/ (commands, hooks)
│  └─ plugins/ (Node.js extensions)

Test Runner → Loads support files → Runs tests from integration → Uses fixtures as data → Plugins extend behavior

Myth Busters - 4 Common Misconceptions

Quick: Do you think the 'support' folder runs test code directly in the browser? Commit yes or no.

Common Belief: The support folder contains test scripts that run like normal tests in the browser.

Reality: Support files run before tests to set up commands and hooks; they are not test scripts themselves.

Why it matters: Misunderstanding this leads to putting test code in support files, causing tests not to run and confusion about test results.

Quick: Can you put test files anywhere in the project and Cypress will find them? Commit yes or no.

Common Belief: Cypress will find and run any test file regardless of its folder location.

Reality: Cypress only runs test files inside the configured 'integration' folder or its subfolders.

Why it matters: Placing tests outside the integration folder means they won't run, wasting time and causing frustration.

Quick: Do plugins run inside the browser environment? Commit yes or no.

Common Belief: Plugins run inside the browser along with tests.

Reality: Plugins run in Node.js outside the browser to modify Cypress behavior safely.

Why it matters: Confusing plugin environment causes errors when trying to use browser-only APIs in plugins.

Quick: Is it best to keep all tests in one flat folder? Commit yes or no.

Common Belief: Keeping all tests in one folder is simpler and better for organization.

Reality: Grouping tests in subfolders by feature or type improves clarity and maintainability.

Why it matters: Flat structures become messy and hard to navigate as test suites grow large.

Expert Zone

1

Support files are loaded once per test run, so heavy code here can slow all tests; use sparingly.

2

Plugins can communicate with the browser tests via tasks, enabling complex workflows like database resets.

3

Custom folder paths must be consistent across team members and CI environments to avoid test failures.

When NOT to use

If your project uses a different test runner or framework, Cypress folder structure is not applicable. For API-only testing without UI, consider dedicated API testing tools. Also, if your project requires a monorepo with multiple apps, you might need a more complex structure or separate Cypress projects.

Production Patterns

Teams often create feature-based subfolders inside 'integration' to mirror app structure. They use 'support' for global commands and 'plugins' for CI integration tasks. Some use environment-specific folders or split tests by speed (smoke vs full). Naming conventions and README files in folders help new team members onboard quickly.

Connections

Modular Programming

Builds-on

Understanding Cypress folder structure is like modular programming: separating code into clear parts improves maintainability and reuse.

Library Organization in Software Development

Same pattern

Just as libraries organize code into folders by purpose, Cypress organizes tests and helpers to keep projects clean and scalable.

Warehouse Inventory Management

Analogy in logistics

Organizing test files in folders is like storing items in labeled warehouse sections, making retrieval efficient and reducing errors.

Common Pitfalls

#1 Placing test files outside the integration folder.

Wrong approach:

cypress/
fixtures/
support/
my_test_spec.js # test file placed here instead of integration/

Correct approach:

cypress/
integration/
my_test_spec.js # test file inside integration folder

Root cause:

Not knowing Cypress only runs tests inside the integration folder.

#2 Adding heavy setup code directly in support files causing slow tests.

Wrong approach:

// support/commands.js
import largeLibrary from 'heavy-lib';
// code that runs on every test causing delays

Correct approach:

// support/commands.js
// Keep support lightweight
// Load heavy code only inside specific tests or plugins

Root cause:

Misunderstanding that support files load before every test run.

#3 Trying to use browser-only APIs inside plugins folder code.

Wrong approach:

// plugins/index.js
window.alert('Hello'); // This will fail because plugins run in Node.js

Correct approach:

// plugins/index.js
// Use Node.js APIs only
module.exports = (on, config) => { /* plugin code */ }

Root cause:

Confusing the execution environment of plugins with browser tests.

Key Takeaways

Cypress folder structure separates tests, data, helpers, and plugins into clear folders to keep projects organized.

The integration folder holds test scripts, support contains reusable commands, fixtures store test data, and plugins extend Cypress behavior.

You can customize folder paths in configuration to fit your project needs.

Organizing tests into subfolders by feature improves maintainability as your test suite grows.

Understanding the execution environment of support and plugins prevents common mistakes and improves test reliability.