QA
If your Cypress tests work flawlessly on your machine but mysteriously fail in CI — you’re not alone.
Every QA Engineer, SDET, or automation enthusiast has faced the classic “works locally but fails in CI” headache 😩
Let’s break down why this happens, and how to make your Cypress suite CI-proof 👇
🧠 1. Understanding the Root Cause: The Environment Mismatch
Your local setup ≠ CI environment.
That’s the first mindset shift you need.
Local CI Interactive browser Headless mode Full OS + GUI Minimal Docker image Manual control Scripted execution Real network latency Mocked / restricted environment
Even small differences — like viewport, caching, or base URL — can cause big failures.
✅ Pro Tip:
Always run your local tests using the same configuration as your CI.
npx cypress run --headless --browser chrome
⚙️ 2. The Hidden Culprit: Environment Variables
In local setups, .env files or shell variables are loaded automatically.
But in CI (like GitHub Actions, Jenkins, or GitLab), you might forget to pass them.
Example:
// cypress.config.js
env: {
apiUrl: process.env.API_URL || 'https://staging.myapp.com/api',
}
✅ Fix:
In your CI YAML or pipeline, inject them explicitly:
env:
API_URL: https://staging.myapp.com/api
🧩 3. Base URL Chaos
If your base URL changes between environments, your tests might hit the wrong domain or port.
✅ Best Practice:
- Keep base URLs consistent (
CYPRESS_BASE_URL) - Define one central config file per environment:
{
"baseUrl": "https://qa.myapp.com",
"env": { "login_user": "qa_user" }
}Then run:
npx cypress run --config-file cypress.qa.json
🕵️ 4. The Headless Mode Trap
Headless browsers sometimes render differently or skip animations too fast.
✅ Solution:
Add explicit waits for UI stability, not time-based waits:
cy.get('.card').should('be.visible')❌ Don’t use:
cy.wait(5000)
Headless Chrome may also have memory or GPU limits — try adding flags:
--disable-gpu --no-sandbox --disable-dev-shm-usage
🌐 5. Network Stubs Gone Wild
If your tests mock API calls using cy.intercept(), they might fail if:
- CI runs too fast before intercepts register
- Base URL doesn’t match
- Dynamic tokens differ
✅ Fix:
Ensure intercepts are defined before page loads:
cy.intercept('GET', '/api/users').as('getUsers')
cy.visit('/dashboard')
cy.wait('@getUsers')🧩 6. Flaky Timings in CI? Introduce Smart Retries
CI environments can be slower, so timeouts can easily fail.
✅ Add retries in config:
retries: {
runMode: 2,
openMode: 0
}✅ Use conditional waits instead of static ones:
cy.get('.status', { timeout: 10000 }).should('contain', 'Success')💡 7. Run in Parallel for Stability + Speed
CI should not just run tests, but run them efficiently.
Leverage Cypress Dashboard or --parallel mode to distribute tests smartly.
npx cypress run --record --key <your-key> --parallel
🧰 8. Debugging CI Failures Like a Pro
When tests fail in CI:
- Capture screenshots/videos:
screenshotsFolder: "cypress/screenshots",
videosFolder: "cypress/videos"
2. Print logs (cy.task('log', message))
3. Check network logs in CI runner (curl or wget tests)
🚀 TL;DR — The “CI-Ready” Checklist
✅ Match local and CI configs
✅ Pass all env variables
✅ Use stable waits (.should() not cy.wait())
✅ Fix intercept order
✅ Add retries + screenshots
✅ Test in headless mode locally before CI
💬 Final Thoughts
If your Cypress tests only work locally, they don’t truly work.
The goal isn’t “green checkmarks” — it’s consistent, deterministic quality across all environments.
Make your automation CI-first, and you’ll never dread those mysterious CI red marks again. ❤️🔥
