Task command for Node operations in Cypress - Framework Patterns

Framework Mode - Task command for Node operations

Folder Structure

cypress/
├── e2e/
│   └── example.cy.js          # Test specs using Cypress commands and tasks
├── support/
│   ├── commands.js            # Custom Cypress commands
│   └── e2e.js                 # Support file loaded before tests, registers tasks
├── plugins/                  # (Optional legacy folder, replaced by cypress.config.js in Cypress 10+)
cypress.config.js            # Main Cypress configuration file with task registration
package.json                 # Project dependencies and scripts

Test Framework Layers

• Test Specs (cypress/e2e/): Write your tests here. Use cy.task() to call Node operations.
• Support Layer (cypress/support/): Define reusable commands and setup code. Import commands and register event listeners.
• Node Task Layer (cypress.config.js): Register task event handlers that run Node.js code outside the browser context.
• Utilities: Helper functions or modules imported by tasks for file operations, API calls, or other Node tasks.
• Configuration: Central place to manage environment variables, browser settings, and task definitions.

Configuration Patterns

Use cypress.config.js to register tasks and manage environment variables.

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        readFile(filename) {
          const fs = require('fs')
          return fs.readFileSync(filename, 'utf8')
        },
        log(message) {
          console.log(message)
          return null
        }
      })
      return config
    },
    env: {
      apiUrl: 'https://api.example.com',
      userEmail: '[e-mail]'
    },
    baseUrl: 'https://app.example.com'
  }
})

Access environment variables in tests with Cypress.env('apiUrl').

Test Reporting and CI/CD Integration

• Use built-in Cypress reporters or plugins like mochawesome for detailed HTML and JSON reports.
• Configure package.json scripts to run tests headlessly in CI environments:

"scripts": {
  "test": "cypress run"
}

• Integrate with CI tools (GitHub Actions, Jenkins, GitLab CI) to run tests on pull requests or merges.
• Use cy.task() to perform Node operations like cleaning test data or generating reports during CI runs.

Best Practices

• Keep Node tasks simple and focused: Each task should do one thing, like reading a file or clearing a database.
• Return serializable data: Tasks must return data that can be sent back to the browser context (strings, objects, arrays).
• Use cy.task() for operations not possible in the browser: File system access, database queries, or external API calls.
• Register tasks in cypress.config.js: Centralize task definitions for easier maintenance.
• Secure sensitive data: Use environment variables and avoid hardcoding secrets in tasks or tests.

Self Check

Where in this framework structure would you add a new Node task to delete temporary test files?

Key Result

Use cy.task() registered in cypress.config.js to run Node operations from Cypress tests.