TypeScript support for custom commands in Cypress - Deep Dive

Overview - TypeScript support for custom commands

What is it?

TypeScript support for custom commands in Cypress allows you to add your own reusable commands with full type safety and autocompletion. This means you can extend Cypress's built-in commands with your own functions and have TypeScript check that you use them correctly. It helps catch errors early and improves developer experience when writing tests.

Why it matters

Without TypeScript support, custom commands in Cypress are just plain JavaScript functions without type checking. This can lead to mistakes like calling commands with wrong arguments or forgetting what a command returns. TypeScript support prevents these bugs before running tests, saving time and frustration. It also makes your test code easier to understand and maintain.

Where it fits

Before learning this, you should know basic Cypress commands and have a grasp of TypeScript basics like types and interfaces. After this, you can explore advanced Cypress features like custom assertions, plugins, and integrating with CI/CD pipelines.

Mental Model

Core Idea

TypeScript support for custom commands lets you safely add your own test actions with clear input and output types, making tests easier to write and less error-prone.

Think of it like...

It's like adding new tools to a toolbox that come with instructions and labels, so you always know how to use them correctly without guessing.

┌───────────────────────────────┐
│ Cypress built-in commands      │
│  (typed by Cypress)            │
├─────────────┬─────────────────┤
│ Custom      │ TypeScript      │
│ commands    │ declaration     │
│ (your code) │ merging         │
└─────────────┴─────────────────┘
          ↓
┌───────────────────────────────┐
│ Test code with autocompletion │
│ and type checking             │
└───────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What are Cypress custom commands

Concept: Custom commands let you add your own reusable test actions to Cypress.

Cypress has many built-in commands like cy.visit() or cy.get(). Sometimes you want to create your own commands to simplify repeated steps, like logging in or filling forms. You add these commands using Cypress.Commands.add('name', () => {...}).

Result

You can call cy.name() in your tests to run your custom code.

Knowing that custom commands extend Cypress lets you write cleaner, DRY tests by reusing common actions.

2

Foundation

Basics of TypeScript in Cypress tests

Concept: TypeScript adds types to JavaScript, helping catch errors and improve code completion.

In Cypress tests, TypeScript lets you declare types for variables, function parameters, and return values. This helps your editor warn you if you use something wrong, like passing a number where a string is expected.

Result

Your test code is safer and easier to write with fewer mistakes.

Understanding TypeScript basics is essential before adding types to custom commands.

3

Intermediate

Declaring types for custom commands

🤔Before reading on: do you think you can add types to custom commands by just typing the function you pass to Cypress.Commands.add? Commit to your answer.

Concept: You declare types for custom commands by merging with Cypress's Chainable interface in a TypeScript declaration file.

Simply typing the function passed to Cypress.Commands.add is not enough. You must create a types file (e.g., cypress/support/index.d.ts) and add a namespace Cypress with interface Chainable that declares your command's name and its function signature. This tells TypeScript what arguments your command takes and what it returns.

Result

Your editor now knows about your custom command and can check its usage and provide autocompletion.

Knowing that you extend Cypress's Chainable interface is key to integrating custom commands with TypeScript's type system.

4

Intermediate

Writing a typed custom command example

🤔Before reading on: do you think your custom command can return a value other than Chainable? Commit to your answer.

Concept: Custom commands can return values, and you can type those returns to improve test code clarity.

For example, a custom command cy.login(username, password) might return a Chainable object. You declare this in the Chainable interface as login(username: string, password: string): Chainable. Then in your implementation, you return cy.wrap(user) to keep chaining.

Result

Tests calling cy.login() get proper type hints about the returned user object.

Typing return values of custom commands unlocks better chaining and clearer test intentions.

5

Advanced

Handling commands with multiple overloads

🤔Before reading on: can a single custom command have multiple type signatures? Commit to your answer.

Concept: You can declare multiple overloads for a custom command to support different argument patterns.

Sometimes a command behaves differently based on arguments. For example, cy.customCommand() might accept either one string or two numbers. You declare multiple signatures in the Chainable interface to reflect this. TypeScript picks the right one based on usage.

Result

Your tests get accurate type checking and autocompletion for all valid ways to call your command.

Understanding overloads lets you write flexible yet type-safe custom commands.

6

Expert

Avoiding pitfalls with declaration merging

🤔Before reading on: do you think declaring custom commands in multiple files can cause type conflicts? Commit to your answer.

Concept: Declaration merging requires careful file organization to avoid duplicate or conflicting types.

If you declare your custom commands in multiple .d.ts files without proper module augmentation, TypeScript may show errors or ignore some declarations. The best practice is to keep all custom command typings in one place or use module augmentation with 'declare global' to merge types cleanly.

Result

Your project compiles without type errors and your custom commands are recognized everywhere.

Knowing how TypeScript merges declarations prevents frustrating type conflicts in large test suites.

Under the Hood

TypeScript uses declaration merging to extend the Cypress namespace and its Chainable interface. When you add a custom command, you also add a new method signature to Chainable. This lets TypeScript understand that cy.yourCommand() exists and what arguments and return types it has. At runtime, Cypress.Commands.add registers the command so it can be called on cy. The type declarations and runtime registration work together but are separate: one for compile-time safety, one for runtime behavior.

Why designed this way?

Cypress chose to use declaration merging because it fits TypeScript's design for extending existing libraries without modifying their source. This approach avoids rewriting Cypress's core types and lets users add commands incrementally. Alternatives like subclassing cy would be more complex and less flexible. Declaration merging also aligns with TypeScript's ecosystem standards.

┌───────────────────────────────┐
│ Cypress core types             │
│  interface Chainable<T>       │
├─────────────┬─────────────────┤
│ User adds   │ TypeScript      │
│ declarations│ merges new      │
│ in .d.ts    │ methods into    │
│ files       │ Chainable       │
└─────────────┴─────────────────┘
          ↓
┌───────────────────────────────┐
│ Test code calls cy.customCmd()│
│ TypeScript checks types       │
│ Runtime calls registered cmd  │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: do you think adding a custom command in JavaScript automatically gives you TypeScript types? Commit to yes or no.

Common Belief: If I add a custom command in Cypress, TypeScript will automatically know its types without extra work.

Reality: You must explicitly declare the types for your custom commands in a TypeScript declaration file; otherwise, TypeScript treats them as unknown.

Why it matters: Without declaring types, you lose autocompletion and type safety, leading to possible runtime errors and harder-to-maintain tests.

Quick: do you think you can declare custom command types anywhere in your project and TypeScript will find them? Commit to yes or no.

Common Belief: I can put my custom command type declarations in any file, and TypeScript will pick them up automatically.

Reality: Type declarations must be in a place TypeScript recognizes, usually a .d.ts file included in tsconfig.json, or inside the cypress/support folder with proper module augmentation.

Why it matters: If declarations are misplaced, TypeScript won't apply them, causing missing types and confusing errors.

Quick: do you think a custom command can return any type without wrapping it in Chainable? Commit to yes or no.

Common Belief: Custom commands can return plain values like strings or objects directly without wrapping in Chainable.

Reality: Custom commands should return Chainable to maintain Cypress's command chaining and asynchronous behavior.

Why it matters: Returning plain values breaks Cypress's command queue and can cause flaky or broken tests.

Quick: do you think you can overload custom commands with different argument types without declaring multiple signatures? Commit to yes or no.

Common Belief: One function signature is enough for all argument variations in a custom command.

Reality: You must declare multiple overload signatures in the Chainable interface to support different argument patterns properly.

Why it matters: Without overloads, TypeScript cannot infer correct types, leading to poor autocompletion and possible type errors.

Expert Zone

1

Custom commands can be chained with built-in commands only if they return Chainable, so always wrap return values with cy.wrap().

2

Declaration merging affects global types, so improper declarations can cause conflicts or unexpected behavior across your test suite.

3

Using module augmentation with 'declare global' inside a .d.ts file is the safest way to extend Cypress types without polluting the global namespace.

When NOT to use

If your custom command involves complex logic or side effects better handled outside Cypress commands, consider writing helper functions instead. Also, avoid custom commands for one-off actions that don't benefit from reuse or chaining. For very dynamic commands, TypeScript typing may become cumbersome and reduce flexibility.

Production Patterns

In real projects, teams keep all custom command typings in a single support/types.d.ts file for maintainability. They use strict typing for commands that return data and overloads for commands with multiple behaviors. Some use code generation tools to keep types in sync with backend APIs. Continuous integration runs type checks to catch errors before tests run.

Connections

TypeScript Declaration Merging

Builds-on

Understanding how TypeScript merges declarations helps grasp how Cypress custom commands extend the Chainable interface safely.

Fluent Interface Pattern

Same pattern

Cypress commands use fluent interfaces to chain actions; typing custom commands correctly preserves this pattern and its benefits.

API Design in Software Engineering

Builds-on

Designing custom commands with clear input/output types mirrors good API design principles, improving usability and maintainability.

Common Pitfalls

#1 Custom command types declared inside a regular .ts file without module augmentation.

Wrong approach:

declare namespace Cypress {
interface Chainable {
login(username: string, password: string): Chainable
}
}
// placed in cypress/support/index.ts

Correct approach:

declare namespace Cypress {
interface Chainable {
login(username: string, password: string): Chainable
}
}
// placed in cypress/support/index.d.ts or a .d.ts file with 'declare global' if using modules

Root cause:

TypeScript only merges declarations from .d.ts files or properly augmented modules; placing them in regular .ts files doesn't extend global types.

#2 Returning plain values from custom commands breaking Cypress chaining.

Wrong approach:

Cypress.Commands.add('getUser', () => {
return { id: 1, name: 'Alice' } // plain object
})

Correct approach:

Cypress.Commands.add('getUser', () => {
return cy.wrap({ id: 1, name: 'Alice' })
})

Root cause:

Cypress commands must return Chainable to maintain asynchronous command queue and chaining.

#3 Not declaring multiple overloads for commands with different argument types.

Wrong approach:

declare namespace Cypress {
interface Chainable {
customCmd(arg: string): Chainable
}
}
// but implementation accepts string or number

Correct approach:

declare namespace Cypress {
interface Chainable {
customCmd(arg: string): Chainable
customCmd(arg: number): Chainable
}
}

Root cause:

TypeScript needs explicit overloads to understand different valid argument types.

Key Takeaways

TypeScript support for Cypress custom commands improves test safety by enforcing correct usage through types.

You must declare custom command types by extending Cypress's Chainable interface in a .d.ts file for TypeScript to recognize them.

Custom commands should return Chainable to maintain Cypress's command chaining and asynchronous behavior.

Using declaration merging and overloads properly allows flexible and type-safe custom commands.

Careful organization of type declarations prevents conflicts and ensures smooth developer experience.