Heuristic:Cypress io Cypress Browser Version Workarounds
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Debugging, Cross_Browser |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Cypress contains extensive browser-version-specific workarounds, particularly for Firefox event handling differences across versions 91, 98, 106, and 129. Knowing these version boundaries helps diagnose test failures.
Description
The Cypress driver contains conditional code paths that adjust behavior based on the specific browser and its major version. The most significant workarounds are in the type command (`cy.type()`), where Firefox versions handle keyboard events, input events, and button interactions differently. These conditionals exist because Firefox changed its event dispatch behavior across multiple releases. Additionally, the blur/focus commands have a known Chrome bug where events are not received when Chrome is not the focused window.
Usage
Apply this heuristic when tests pass in one browser but fail in another, debugging keyboard input behavior differences, upgrading browser versions in CI, or investigating event-related test flakiness. Browser-specific issues are the second most common cause of cross-browser test failures after timeout issues.
The Insight (Rule of Thumb)
- Action: When a test fails only in Firefox, check if the failure relates to keyboard events, input events, or button clicks. The driver has version-specific workarounds for Firefox < 91, < 98, >= 106, and >= 129.
- Value: Use Firefox >= 135 (minimum supported) to get the most consistent behavior
- Trade-off: Cross-browser consistency requires maintaining awareness of these version-specific code paths
Reasoning
Firefox has undergone significant changes in its event dispatch model across versions. Firefox < 91 handled button keyboard events differently. Firefox < 98 had different input event behavior. Firefox 106 introduced new button element handling. Firefox 129 changed key event dispatch. Each of these changes required conditional paths in the Cypress driver to maintain consistent test behavior. Chrome has a longstanding bug where blur/focus events are not dispatched when Chrome is not the active window — this affects interactive (non-headless) test runs.
Code Evidence
Firefox version conditionals from `packages/driver/src/cy/commands/actions/type.ts:178-181`:
const isFirefoxBefore91 = Cypress.isBrowser('firefox') && Cypress.browserMajorVersion() < 91
const isFirefoxBefore98 = Cypress.isBrowser('firefox') && Cypress.browserMajorVersion() < 98
const isFirefox106OrLater = Cypress.isBrowser('firefox') && Cypress.browserMajorVersion() >= 106
const isFirefox129OrLater = Cypress.isBrowser('firefox') && Cypress.browserMajorVersion() >= 129
Firefox key event workaround from `packages/driver/src/cy/commands/actions/type.ts:377`:
if (Cypress.isBrowser('firefox') && !isFirefox129OrLater) {
// Firefox-specific key event handling
}
Chrome focus bug from `packages/driver/src/cypress/error_messages.ts:597`:
timed_out: {
message: `${cmd('focus')} timed out because your browser did not receive any \`focus\` events. This is a known bug in Chrome when it is not the currently focused window.`,
docsUrl: 'https://on.cypress.io/focus',
}
Firefox minimum version enforcement from `packages/launcher/lib/known-browsers.ts:8-13`:
if (majorVersion < 135) {
return {
isSupported: false,
warningMessage: `Cypress does not support running ${browser.displayName} version ${browser.majorVersion} due to lack of WebDriver BiDi support.`,
}
}