Custom plugin development in Cypress

Introduction

Custom plugins let you add new features to Cypress tests easily. They help you reuse code and make tests simpler.

You want to add a new command to Cypress that you use often.

You need to handle special setup or cleanup before or after tests.

You want to connect Cypress with other tools or APIs.

You want to share common test logic across many test files.

You want to customize how Cypress behaves for your project.

Syntax

Cypress

module.exports = (on, config) => {
  // register event listeners or tasks here
  on('task', {
    myTask(arg) {
      // do something with arg
      return null;
    }
  });
  // return updated config if needed
  return config;
}

on lets you listen to Cypress events or define tasks.

config holds Cypress settings you can change.

Examples

This plugin adds a task named log that prints messages to the console.

Cypress

module.exports = (on, config) => {
  on('task', {
    log(message) {
      console.log(message);
      return null;
    }
  });
}

This plugin changes Chrome browser launch options to disable GPU.

Cypress

module.exports = (on, config) => {
  on('before:browser:launch', (browser = {}, launchOptions) => {
    if (browser.name === 'chrome') {
      launchOptions.args.push('--disable-gpu');
    }
    return launchOptions;
  });
}

Sample Program

This example shows a plugin that adds a greet task. The test calls this task with 'Alice' and checks the returned message.

Cypress

// cypress/plugins/index.js
module.exports = (on, config) => {
  on('task', {
    greet(name) {
      console.log(`Hello, ${name}!`);
      return `Greeted ${name}`;
    }
  });
};

// cypress/e2e/sample.cy.js
describe('Custom Plugin Test', () => {
  it('uses greet task', () => {
    cy.task('greet', 'Alice').then((result) => {
      expect(result).to.equal('Greeted Alice');
    });
  });
});

Important Notes

Always return a value or null from tasks to avoid hanging tests.

Use tasks for code that runs in Node.js, not in the browser.

Keep plugins simple and focused on reusable logic.

Summary

Custom plugins add new commands or tasks to Cypress.

They help share code and customize test behavior.

Plugins run in the Node.js environment, separate from browser tests.

Practice

1. What is the main purpose of creating a custom plugin in Cypress?

easy

A. To add new commands or tasks that extend Cypress functionality

B. To change the browser's default behavior during tests

C. To write test cases in a different programming language

D. To speed up the execution of all tests automatically

Solution

1. Step 1: Understand what plugins do in Cypress

   Plugins allow adding new commands or tasks that Cypress does not provide by default.

2. Step 2: Differentiate from other options

   Changing browser behavior or writing tests in other languages is not the role of plugins. Speeding up tests automatically is not guaranteed by plugins.

3. Final Answer:

   To add new commands or tasks that extend Cypress functionality -> Option A

4. Quick Check:

   Plugins extend Cypress features = D [OK]

Hint: Plugins add new commands or tasks to Cypress [OK]

Common Mistakes:

• Thinking plugins change browser behavior directly
• Confusing plugins with test case languages
• Assuming plugins automatically speed up tests

2. Which file is typically used to define custom plugins in a Cypress project?

easy

A. cypress/plugins/index.js

B. cypress/support/commands.js

C. cypress/integration/spec.js

D. cypress.json

Solution

1. Step 1: Identify the plugin file location

   Custom plugins are defined in the cypress/plugins/index.js file where Node.js code runs.

2. Step 2: Differentiate from support and config files

   support/commands.js is for custom commands in browser tests, integration/spec.js is for test specs, and cypress.json is config.

3. Final Answer:

   cypress/plugins/index.js -> Option A

4. Quick Check:

   Plugins file = C [OK]

Hint: Plugins go in cypress/plugins/index.js file [OK]

Common Mistakes:

• Confusing plugins file with support commands file
• Choosing test spec files for plugins
• Selecting config file for plugin code

3. Given this plugin code snippet in cypress/plugins/index.js:

module.exports = (on, config) => {
  on('task', {
    logMessage(message) {
      console.log(message)
      return null
    }
  })
}

What happens when the test calls cy.task('logMessage', 'Hello')?

medium

A. The test fails because 'logMessage' is not a valid Cypress command

B. The message 'Hello' is printed in the browser console, and the task returns undefined

C. The message 'Hello' is printed in the Node.js console, and the task returns null

D. Nothing happens because tasks cannot receive arguments

Solution

1. Step 1: Understand the plugin task definition

   The plugin defines a task named 'logMessage' that logs the message to the Node.js console and returns null.

2. Step 2: Understand cy.task behavior

   Calling cy.task('logMessage', 'Hello') sends 'Hello' to the plugin task, which logs it in Node.js, not browser, and returns null.

3. Final Answer:

   The message 'Hello' is printed in the Node.js console, and the task returns null -> Option C

4. Quick Check:

   cy.task logs in Node.js console = A [OK]

Hint: cy.task runs plugin code in Node.js, not browser console [OK]

Common Mistakes:

• Thinking console.log prints in browser console
• Assuming tasks cannot take arguments
• Confusing tasks with custom commands

4. Identify the error in this plugin code snippet:

module.exports = (on, config) => {
  on('task', {
    multiplyNumbers(a, b) {
      return a * b
    }
  })
}

And select the correct fix.

medium

A. No error, the code is correct as is

B. Change the task to accept a single argument object like {a, b} instead of two arguments

C. Replace 'on' with 'off' to register the task properly

D. Return a Promise instead of a direct value

Solution

1. Step 1: Understand how Cypress tasks receive arguments

   Cypress tasks accept only one argument. Multiple arguments must be wrapped in an object.

2. Step 2: Identify the error and fix

   The function multiplyNumbers expects two arguments, but Cypress will pass only one. Fix by accepting a single object with properties a and b.

3. Final Answer:

   Change the task to accept a single argument object like {a, b} instead of two arguments -> Option B

4. Quick Check:

   Tasks accept one argument object = B [OK]

Hint: Tasks get one argument; use object to pass multiple values [OK]

Common Mistakes:

• Defining task functions with multiple parameters
• Using 'off' instead of 'on' to register tasks
• Thinking tasks must return Promises always

5. You want to create a custom plugin that reads a JSON file from disk and returns its content to your test. Which approach correctly implements this plugin task?

hard

A. Use console.log to print file content and return undefined

B. Use cy.readFile inside the plugin task to read the file asynchronously

C. Use browser fetch API inside the plugin task to get the file content

D. Use Node.js fs.readFileSync inside the plugin task and return parsed JSON

Solution

1. Step 1: Understand plugin environment

   Plugins run in Node.js, so Node.js modules like fs can be used to read files synchronously or asynchronously.

2. Step 2: Choose correct method to read file

   cy.readFile is a test command, not available in plugins. Browser fetch is not available in Node.js plugin context. Using fs.readFileSync and returning parsed JSON is correct.

3. Final Answer:

   Use Node.js fs.readFileSync inside the plugin task and return parsed JSON -> Option D

4. Quick Check:

   Plugins use Node.js fs to read files = A [OK]

Hint: Use Node.js fs module in plugins, not cy commands [OK]

Common Mistakes:

• Trying to use cy commands inside plugins
• Using browser APIs in Node.js plugin code
• Returning undefined instead of file content