Learn Cypress - Custom Commands & Utilities

#Introduction

The more tests you write, the more repeated patterns you see: login, preparing data, opening a specific page. Episode 7 teaches you how to package those patterns into custom commands and utilities so your tests stay short, consistent, and easy to maintain.

Custom commands also enable technical abstraction: tests read cy.login("admin"), while the details of the login mechanism are hidden in one place.

#Adding Custom Commands in commands.js

A custom command is defined with Cypress.Commands.add. Its home is cypress/support/commands.js:

cypress/support/commands.js

Cypress.Commands.add("login", (email, password) => {
  cy.visit("/login");
  cy.get("[data-cy=email]").type(email);
  cy.get("[data-cy=password]").type(password);
  cy.get("[data-cy=submit]").click();
  cy.url().should("include", "/dashboard");
});

Cypress.Commands.add("login", (email, password) => { ... }) registers a new command named login that accepts two arguments. Every test in the project can now call cy.login(...).

For the command to load, make sure commands.js is imported by the support file. By default cypress/support/e2e.js loads it:

cypress/support/e2e.js

import "./commands";

import "./commands" ensures all custom commands are available before a spec runs.

#Using Them in Tests

Using a custom command

it("menambahkan produk ke keranjang", () => {
  cy.login("user@example.com", "rahasia123");
  cy.get("[data-cy=produk-pertama]").click();
  cy.contains("Ditambahkan ke keranjang").should("be.visible");
});

cy.login("user@example.com", "rahasia123") replaces five lines of login interaction with a single line. Every test that needs login is now consistent — and if the login flow changes, you only have to change one definition.

#Reusable Helpers for Test Flows

Besides commands, you can use plain JavaScript functions as helpers. Store them in cypress/support/utils.js:

cypress/support/utils.js

export const formatHarga = (angka) =>
  `Rp${angka.toLocaleString("id-ID")}`;
 
export const buatEmailAcak = () =>
  `user-${Date.now()}@example.com`;

Then import them in your spec file:

Using helpers

import { formatHarga, buatEmailAcak } from "../support/utils";
 
it("menampilkan harga terformat", () => {
  cy.contains(formatHarga(45000)).should("be.visible");
});
 
it("mendaftar dengan email acak", () => {
  cy.get("[data-cy=email]").type(buatEmailAcak());
});

formatHarga(45000) and buatEmailAcak() are pure functions — easy to test on their own and free of browser state. This is the right place for pure logic that does not need access to Cypress.

#Configuring baseUrl and Environment Variables

#baseUrl in the Configuration

We set baseUrl in episode 3. Its value keeps cy.visit("/") concise and makes moving between environments easy:

Configuring baseUrl

module.exports = defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
  },
});

#Environment Variables

For values that differ between environments, use environment variables. Set them in the config or via the CLI:

npx cypress run --env apiBaseUrl=http://localhost:8080

Access them from tests with Cypress.env:

Reading an env var

const api = Cypress.env("apiBaseUrl");
 
cy.intercept("GET", `${api}/produk`).as("produk");

Cypress.env("apiBaseUrl") reads the value passed via --env. For secret values, do not write them directly in the config — we will discuss secure credential management in episode 13.

#Organizing Test Utilities

#A Clean Support Structure

As the project grows, split responsibilities:

cypress/support/
  commands.js
  commands/
    auth.js
    checkout.js
  utils.js
  e2e.js

• commands.js: imports and organizes the built-in commands.
• commands/auth.js: commands related to login and sessions.
• commands/checkout.js: commands related to the shopping flow.
• utils.js: pure functions without access to Cypress.

commands.js importing modules

import "./commands/auth";
import "./commands/checkout";

import "./commands/auth" loads the authentication commands. With this pattern, teams can add commands per domain without creating one giant file.

#Rules for Custom Commands

A few guidelines keep commands healthy:

• Give them names that clearly describe what they do, not how.
• Include assertions inside the command so failures are detected quickly.
• Do not hide too much detail — commands that contain too much logic are hard to debug.
• Use pure helpers for logic that does not need a browser.

#Closing

Episode 7 expanded the Cypress vocabulary: custom commands with Cypress.Commands.add in commands.js, pure helpers for reusable logic, managing baseUrl and environment vars via --env and Cypress.env, and a support structure split by domain.

Key takeaways:

• Cypress.Commands.add("nama", fn) registers a command you can call as cy.nama().
• cypress/support/e2e.js loads commands.js so commands are available globally.
• Pure helpers in utils.js for non-browser logic like price formatting.
• Env vars are passed via --env and read with Cypress.env.
• Organizing support by domain keeps files lean.

In the next episode, episode 8, we will cover advanced interactions — handling iframes, popups, and multiple windows, drag and drop, uploads, keyboard events, testing single-page apps, and network stubbing with cy.intercept(). Your test interactions are about to touch real, complex scenarios.