Custom plugin development in Cypress - Framework Patterns

Framework Mode - Custom plugin development

Folder Structure

cypress/
├── e2e/                  # Test specs
│   └── example.cy.js
├── support/              # Support files and commands
│   ├── commands.js       # Custom commands
│   └── e2e.js            # Support file loaded before tests
├── plugins/              # Custom plugins
│   └── index.js          # Plugin entry point
cypress.config.js         # Cypress configuration file
package.json             # Project dependencies and scripts

Test Framework Layers

• Plugins Layer: Contains custom plugin code to extend Cypress functionality, located in cypress/plugins/index.js.
• Support Layer: Houses reusable commands and setup code, e.g., commands.js for custom commands.
• Test Specs Layer: Contains the actual test files inside cypress/e2e/.
• Configuration Layer: Central place for Cypress settings in cypress.config.js.
• Utilities Layer: Optional helpers or utilities can be added inside cypress/support/ or a separate folder.

Configuration Patterns

• Environment Variables: Use env property in cypress.config.js to store environment-specific data like URLs or credentials.
• Browser Selection: Configure browsers via CLI or cypress.config.js to run tests on Chrome, Firefox, etc.
• Plugin Configuration: Export a function in cypress/plugins/index.js that receives on and config objects to register event handlers or modify config dynamically.
• Secrets Management: Use environment variables or CI secrets to avoid hardcoding sensitive data.

Test Reporting and CI/CD Integration

• Test Reporting: Integrate reporters like mochawesome or junit via cypress.config.js to generate readable test reports.
• CI/CD Integration: Run Cypress tests in pipelines (GitHub Actions, Jenkins, GitLab CI) using commands like npx cypress run.
• Plugin Usage in CI: Ensure plugins are loaded correctly in CI environment by verifying cypress/plugins/index.js is included and configured.
• Artifacts: Save screenshots, videos, and reports as build artifacts for debugging failed tests.

Best Practices for Custom Plugin Development

1. Keep Plugins Focused: Each plugin should have a single responsibility to keep code clean and maintainable.
2. Use Event Listeners Properly: Register event handlers in cypress/plugins/index.js using the on argument to hook into Cypress lifecycle events.
3. Do Not Modify Tests Directly: Plugins should extend Cypress capabilities without changing test logic.
4. Document Plugin APIs: Clearly comment plugin functions and expected inputs/outputs for easier team collaboration.
5. Handle Errors Gracefully: Plugins should catch and log errors without crashing the test run.

Self Check

Where in this folder structure would you add a new plugin that modifies the browser launch behavior?

Key Result

Organize Cypress tests with clear separation of plugins, support, and test specs for scalable custom plugin development.

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