Percy integration basics in Cypress - Framework Patterns

Framework Mode - Percy integration basics

Folder Structure

cypress/
├── e2e/                  # Test specs
│   └── visual.spec.js    # Visual test example
├── support/              # Support commands and setup
│   ├── commands.js       # Custom Cypress commands
│   └── e2e.js            # Global setup for tests
cypress.config.js         # Cypress configuration file
package.json             # Project dependencies and scripts
.percy.yml               # Percy configuration file

Test Framework Layers

• Test Specs (cypress/e2e): Write Cypress tests here. Include Percy snapshots to capture visual states.
• Support Layer (cypress/support): Add custom commands and global test setup. Initialize Percy commands here.
• Configuration: Manage Cypress and Percy settings in cypress.config.js and .percy.yml.
• Utilities: Helper functions or data can be added in support or separate utils folder if needed.

Configuration Patterns

• cypress.config.js: Configure base URL, test retries, and include Percy plugin setup.
• .percy.yml: Define Percy project settings like widths, minimum height, and ignore regions.
• Environment Variables: Use CYPRESS_BASE_URL and PERCY_TOKEN to keep credentials and URLs secure and flexible.
• Package.json scripts: Add scripts to run tests with Percy enabled, e.g., cypress run with Percy environment variables.

Test Reporting and CI/CD Integration

• Percy Dashboard: Visual test results appear here with diffs highlighted for UI changes.
• CI/CD Pipelines: Integrate Percy by setting PERCY_TOKEN in CI environment variables and running Cypress tests with Percy enabled.
• Test Reports: Use Cypress reporters for functional test results alongside Percy visual reports.
• Fail Builds on Visual Changes: Configure CI to fail if Percy detects unexpected visual diffs.

Best Practices

1. Take snapshots at meaningful UI states to catch visual regressions early.
2. Keep snapshots small and focused to reduce noise and speed up tests.
3. Use environment variables to keep tokens and URLs secure and flexible across environments.
4. Integrate Percy in CI/CD to automate visual testing on every code change.
5. Review Percy diffs carefully to avoid false positives and maintain UI quality.

Self Check

Where in this folder structure would you add a new visual test for the homepage using Percy snapshots?

Key Result

Organize Cypress tests with Percy snapshots in e2e folder, configure with cypress.config.js and .percy.yml, and integrate visual testing into CI/CD pipelines.