Cypress.Commands.add() - Framework Patterns

Framework Mode - Cypress.Commands.add()

Folder Structure of a Cypress Test Framework

  cypress/
  ├── e2e/                  # Test specification files
  │   ├── login.cy.js       # Example test file
  │   └── dashboard.cy.js
  ├── support/              # Support files and custom commands
  │   ├── commands.js       # Custom commands added with Cypress.Commands.add()
  │   ├── e2e.js            # Support file loaded before tests
  │   └── index.js          # Entry point for support files
  ├── fixtures/             # Test data files (JSON, etc.)
  │   └── user.json
  └── plugins/              # Plugins for extending Cypress
      └── index.js
  cypress.config.js         # Cypress configuration file
  

Test Framework Layers

• Test Specs (e2e/): Contains test scripts that use Cypress commands to automate UI actions and assertions.
• Custom Commands (support/commands.js): Extend Cypress with reusable commands using Cypress.Commands.add() to simplify tests and avoid repetition.
• Fixtures (fixtures/): Store static test data like user info or test inputs in JSON files for easy reuse.
• Plugins (plugins/): Add or modify Cypress behavior, e.g., for tasks like file system access or environment setup.
• Configuration (cypress.config.js): Define environment settings, base URLs, browser options, and test timeouts.

Configuration Patterns

Use cypress.config.js to manage settings like base URL, test retries, and browser preferences.

Manage environments by defining env variables in the config or via CLI, e.g., cypress run --env environment=staging.

Store sensitive data like credentials in environment variables or cypress.env.json (excluded from version control) to keep secrets safe.

Example snippet from cypress.config.js:

  export default defineConfig({
    e2e: {
      baseUrl: 'https://example.com',
      env: {
        username: 'testuser',
        password: 'secret'
      },
      retries: 2,
      setupNodeEvents(on, config) {
        // plugin code here
      }
    }
  })
  

Test Reporting and CI/CD Integration

Use built-in Cypress reporters or add plugins like mochawesome for detailed HTML and JSON reports.

Configure reporters in cypress.config.js or via CLI options.

Integrate Cypress tests into CI/CD pipelines (GitHub Actions, Jenkins, GitLab CI) by running cypress run commands and collecting reports as artifacts.

Example GitHub Actions step:

  - name: Run Cypress Tests
    uses: cypress-io/github-action@v5
    with:
      browser: chrome
      headless: true
  

Best Practices for Using Cypress.Commands.add()

• Keep commands simple and focused: Each custom command should do one clear task to keep tests readable.
• Use commands to abstract repetitive UI actions: For example, create a login command to reuse login steps across tests.
• Chain commands properly: Return Cypress chainables from commands to allow smooth chaining in tests.
• Document custom commands: Add comments explaining what each command does for easy maintenance.
• Store commands in support/commands.js: This keeps the framework organized and commands automatically loaded.

Self Check Question

Where in this folder structure would you add a new custom command named fillForm that types data into a form?

Key Result

Use Cypress.Commands.add() in support/commands.js to create reusable custom commands that simplify test scripts.

Practice

1. What is the main purpose of Cypress.Commands.add() in Cypress testing?

easy

A. To configure browser settings

B. To add new test cases automatically

C. To create reusable custom commands for cleaner test code

D. To generate test reports

Solution

1. Step 1: Understand the function of Cypress.Commands.add()

   This method allows you to define your own commands that you can reuse in tests.

2. Step 2: Identify the benefit of reusable commands

   Reusable commands help keep test code clean and avoid repetition.

3. Final Answer:

   To create reusable custom commands for cleaner test code -> Option C

4. Quick Check:

   Reusable commands = Cleaner code [OK]

Hint: Remember: add() creates custom commands you can reuse [OK]

Common Mistakes:

• Thinking it adds test cases automatically
• Confusing it with test report generation
• Assuming it changes browser settings

2. Which of the following is the correct syntax to add a custom command named login in Cypress?

easy

A. Cypress.Commands.create('login', () => { /* code */ })

B. Cypress.addCommand('login', () => { /* code */ })

C. Commands.add('login', () => { /* code */ })

D. Cypress.Commands.add('login', () => { /* code */ })

Solution

1. Step 1: Recall the correct method name

   The correct method to add commands is Cypress.Commands.add().

2. Step 2: Check the syntax format

   The first argument is the command name as a string, the second is a function.

3. Final Answer:

   Cypress.Commands.add('login', () => { /* code */ }) -> Option D

4. Quick Check:

   Correct method and syntax = Cypress.Commands.add('login', () => { /* code */ }) [OK]

Hint: Use Cypress.Commands.add('name', function) always [OK]

Common Mistakes:

• Using Cypress.addCommand instead of Commands.add
• Omitting Cypress.Commands prefix
• Using create instead of add

3. Given the code below, what will be the output when cy.login() is called in a test?

 Cypress.Commands.add('login', (username, password) => {
  cy.get('#user').type(username)
  cy.get('#pass').type(password)
  cy.get('#submit').click()
})

// In test
cy.login('user1', 'pass1')

medium

A. Types 'user1' in #user, 'pass1' in #pass, then clicks #submit

B. Throws an error because login needs no parameters

C. Clicks #submit without typing anything

D. Types 'user1' in #pass and 'pass1' in #user

Solution

1. Step 1: Analyze the custom command parameters

   The command takes username and password and types them into respective fields.

2. Step 2: Follow the command actions

   It types username into '#user', password into '#pass', then clicks '#submit'.

3. Final Answer:

   Types 'user1' in #user, 'pass1' in #pass, then clicks #submit -> Option A

4. Quick Check:

   Parameters map to correct fields = Types 'user1' in #user, 'pass1' in #pass, then clicks #submit [OK]

Hint: Match parameters to fields carefully [OK]

Common Mistakes:

• Assuming no parameters are needed
• Mixing up username and password fields
• Ignoring the click action

4. Identify the error in the following custom command definition:

 Cypress.Commands.add('clickButton', () => {
  cy.get('#button')
  cy.click()
})

medium

A. Missing chaining of click() to cy.get()

B. Wrong command name, should be clickbutton

C. Should use cy.find() instead of cy.get()

D. No error, code is correct

Solution

1. Step 1: Review the command chaining

   cy.get('#button') returns an element, but cy.click() is called separately, not chained.

2. Step 2: Understand correct chaining

   Click should be chained to the element: cy.get('#button').click().

3. Final Answer:

   Missing chaining of click() to cy.get() -> Option A

4. Quick Check:

   Method chaining required = Missing chaining of click() to cy.get() [OK]

Hint: Always chain commands like cy.get(...).click() [OK]

Common Mistakes:

• Calling cy.click() separately
• Changing command name unnecessarily
• Using cy.find() instead of cy.get() without reason

5. You want to create a custom command fillForm that fills multiple fields and submits a form. Which approach correctly uses Cypress.Commands.add() to accept an object with field values and perform the actions?

hard

A. Cypress.Commands.add('fillForm', () => {
cy.get('#name').type(name)
cy.get('#email').type(email)
cy.get('#submit').click()
})

B. Cypress.Commands.add('fillForm', (data) => {
cy.get('#name').type(data.name)
cy.get('#email').type(data.email)
cy.get('#submit').click()
})

C. Cypress.Commands.add('fillForm', (name, email) => {
cy.get('#name').type(name)
cy.get('#email').type(email)
cy.get('#submit').click()
})

D. Cypress.Commands.add('fillForm', (data) => {
cy.get('#name').type(data[0])
cy.get('#email').type(data[1])
cy.get('#submit').click()
})

Solution

1. Step 1: Understand parameter passing

   Using a single object parameter data with named properties is clear and flexible.

2. Step 2: Check usage of object properties

   Accessing data.name and data.email matches the object keys.

3. Final Answer:

   Cypress.Commands.add('fillForm', (data) => { cy.get('#name').type(data.name) cy.get('#email').type(data.email) cy.get('#submit').click() }) -> Option B

4. Quick Check:

   Object parameter with named fields = Cypress.Commands.add('fillForm', (data) => { cy.get('#name').type(data.name) cy.get('#email').type(data.email) cy.get('#submit').click() }) [OK]

Hint: Pass one object with named fields for clarity [OK]

Common Mistakes:

• Using undefined variables without parameters
• Passing multiple parameters instead of one object
• Accessing object fields by index instead of name