Organising Cypress at scale - Part 1: Custom Commands

Kevin Korenhof — Wed, 29 Apr 2026 13:47:34 +0000

Organising Cypress at scale

When you just start using Cypress for the first time it's easy to keep everything together. You start writing a few tests, add some custom commands and so on. And this works great when you have a small test suite, but when things start to grow, so do the problems... Files get bigger, commands become hard to find, documentation is non-existant and different people start solving the same issue in their own way. This is when chaos starts to emerge.

As a consultant working with Cypress I have seen a lot of different Cypress setups. Some are very well structured, while others have become a huge mess and maintanance nightmare! But luckily the mess is fixable! You can get everything organized and arranged in a scalable way to fix all the maintanance issues! But even better is preventing it in the first place!

In this blog series I will share ways to organise your Cypress setup for larger test suites. The end goal is simple: create a setup that works with hundreds or even thousands of tests, while still providing clear oversight and remaining easy to maintain.

Part 1: Custom commands

This first part will focus on custom commands. I love using them because they are a great way to keep your tests organised and maintainable. You can use them to encapsulate repeated actions across multiple tests or to improve readability of your tests by grouping steps that are part of a single action (for example, logging in a user).

The standard way of using custom commands

The 'standard' way to create and use custom commands in Cypress is to place them all in a single commands.js file and import that into your support file. If needed you can extend them with a cypress.d.ts file to add typing and you're ready to go!

For example:

//commands.js
Cypress.Commands.add("login", (username, password) =>{
    cy.visit('/login')
    cy.get('userNameInput').type(username)
    cy.get('passwordInput').type(password)
    cy.get('submitButton').click()
})

Cypress.Commands.add("logout", () =>{
    cy.get('logoutButton').click()
    cy.get('confirm').click()
})

Cypress.Commands.add('selectDropdown', (selector, value) =>{
    cy.get(selector).select(value)
    return cy.wrap(selector)
})

Cypress.Commands.add('anotherCommand', () =>{
    // bunch of code for command....
})

Cypress.Commands.add('moreCommands', () =>{
    // and even more code...
})
// ... hundreds of lines later...

//cypress.d.ts
declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      login(username: string, password: string): void;
      logout(): void;
      selectDropdown(selector: string, value: string): Chainable<JQuery<HTMLElement>>;
    }
  }
}

- I'm not going into detail now on how to best write custom commands themselves, that is a whole blogpost on it's own. For now, we'll focus on organising them. If you want to know more about writing custom commands, check out the Cypress documentation here.-

This approach works great when you have a few commands. But as your test suite grows, you will keep on adding more and more commands. This file will then quickly turn into spaghetti! And don't get me wrong, I love a good bowl of carbonara, just not in my code!

As your commands file grows, you will start to lose oversight on what commands already exist. This will increase the risk of creating duplicate commands, making the problem only bigger. On top of that, it gets harder and harder to find and maintain existing commands.

A scalable approach

Luckily, there is a simple way to fix this, or even better, prevent it from happening. There is just one very important thing to remember:

Your custom commands do not have to live in the commands.js file!

Most people assume they do, but you can put them wherever you want. They don't even have to be in a single file. You can use as many files as you want. As long as everything is imported into your support file.

So how do we organise this?
Since we can use multiple files, let's do that! In a scalable setup, each custom command has its own file. That file contains everything related to that command: logic, typing, JSDoc, etc.

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      /**
       * This command will login with provided credentials
       * @input username the username used to login
       * @input password password that is needed for login
       *
       * @example cy.login('user', 'password')
       */
      login(username: string, password: string): void;
    }
  }
}

export function login(username: string, password: string): void {
  cy.visit("/login");
  cy.get("userNameInput").type(username);
  cy.get("passwordInput").type(password);
  cy.get("submitButton").click();
}

Now, you might notice something is missing in this file. We are not registering the command with Cypress with Cypress.Commands.add()
That's intentional!
This is the only thing we won't do in the specific command file. All of our commands still need to be added to Cypress. But we can centralize this part to keep things clean and maintainable.

In our folder with the command files we will add an index.ts file. In this file we import all of our command functions and then register them in Cypress in bulk using Cypress.Commands.addAll({}).

Example:

import { loginUi } from "./loginUI";
import { loginFacebook } from "./loginFacebook";
import { loginGoogle } from "./loginGoogle";
import { loginAPI } from "./loginAPI";

Cypress.Commands.addAll({ loginUi, loginFacebook, loginGoogle, loginAPI });

NOTE: When using child, dual and parent commands, you need to register these commands separately per command type. You can't combine them in a single Cypress.Commands.addAll() call.

We can take this a step further! Instead of placing all the files in a single folder, let's set up a folder structure to organize our commands even more.

commands/
├── login/
│   ├── index.ts
│   ├── loginAPI.ts
│   ├── loginFacebook.ts
│   ├── loginGoogle.ts
│   ├── loginUI.ts
├── dropdown/
│   ├── index.ts
│   ├── selectDropdown.ts
│   ├── getDropdownValue.ts
├── otherCommands/
│   ├── subFolder1/
│   │   ├── index.ts
│   │   ├── command1.ts
│   │   ├── command2.ts
├── subFolder2/
│   │   ├── index.ts
│   │   ├── command1.ts
│   │   ├── command2.ts
│   ├── index.ts
├── index.ts

With this we can group the files that have a shared use. For example: login commands, dropdowns, grouped actions, mocking data, etc. This will make it even easier to find all the commands we have.
Each folder will have its own index.ts file. These files will group everything for that folder and can do two things:

import subfolders
register commands within that folder to Cypress (as we did above)

// commands/otherCommands/index.ts
import 'subFolder1'
import 'subFolder2'

// commands/index.ts
import 'login'
import 'dropdown'
import 'otherCommands'

There is now only one thing left, and that is to go to your support folder and add this one line:
import '/commands'
And that's it. All of your commands are now neatly organised and ready to scale!

Conclusion!

Custom commands in Cypress are amazing! But as your test suite grows, organisation becomes essential.
By splitting commands into separate files and grouping them by purpose, we create a scalable structure that is easy to navigate and maintain. It gets easy to see what commands already exist and you can quickly find them when making changes. By keeping all logic for a single command in one place, you avoid spreading out related code across multiple files. This makes the use of you custom commands predictable and easy to work with at scale.

In the next part of this series we'll continue organising our Cypress setup! We will start to look at organizing our test files to make sure we can quickly see what the test is doing.

DEV Community: Kevin Korenhof

Organising Cypress at scale - Part 1: Custom Commands