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.