Running Cypress Tests Locally

This document explains how to run Cypress tests locally on your machine, with a focus on ensuring color profiles match those used in GitHub Actions for consistent visual testing results.

Running Tests

You can run Cypress tests using the following commands:

Run all tests headlessly:

pnpm cy

Run a specific test file:

pnpm cypress run --spec "cypress/e2e/smoke.spec.js"

Color Profile Configuration

Why Color Profiles Matter

Visual regression tests in Cypress compare screenshots pixel-by-pixel. Different color profiles can cause the same UI to render with slightly different colors, leading to false test failures. To match the GitHub Actions environment, we use the sRGB color profile.

Automatic Configuration

Our Cypress configuration automatically forces the sRGB color profile when running tests. This is configured in cypress/plugins/index.js with the following code:

on("before:browser:launch", (browser = {}, launchOptions) => {
  if (browser.family === "chromium" && browser.name !== "electron") {
    launchOptions.args.push("--force-color-profile=srgb");
  }
});

Configuring macOS Color Profile

For the most consistent results, you should also configure your macOS system to use the sRGB color profile:

Open System Preferences (or System Settings on newer macOS versions)
Go to "Displays"
Select the "Color" tab
Click "Calibrate" to open the Display Calibrator Assistant
Follow the wizard and when prompted for a color profile, select "sRGB"
Complete the calibration and save the profile

Alternatively, you can directly select an existing sRGB profile:

Open System Preferences > Displays > Color
From the list of color profiles, select "sRGB IEC61966-2.1" or a similar sRGB profile
Click "Apply"

Troubleshooting Visual Test Failures

If you encounter visual test failures despite using the sRGB profile:

Check that your display brightness is set to a consistent level
Ensure you're using the same browser version as GitHub Actions (Chrome)
Verify that your OS theme/appearance settings match the CI environment (light mode is recommended)
If necessary, adjust the threshold in the image snapshot configuration:

cy.document().toMatchImageSnapshot({
  imageConfig: { threshold: 0.012 }, // Increase this value if needed
  capture: "viewport",
});

2.7 KiB Raw Blame History