breaking: disallow setting viewportHeight/viewportWidth via Cypress.config() during test execution

[jennifer-shehane]

• Closes Don't allow setting viewportHeight and viewportWidth via Cypress.config during test execution #31592

Additional details

viewportWidth and viewportHeight could previously be mutated at run-time via Cypress.config(). This was confusing and error-prone:

• The change applied to the next test rather than the current one (config overrides set at run-time leak into the following test).
• The update was not shared with Cypress Cloud, so it was not reflected in Test Replay.

This change makes viewportWidth/viewportHeight no longer settable via Cypress.config() during test execution. They remain settable via the supported alternatives:

• cy.viewport()
• suite-/test-level config overrides — describe/context/it (e.g. it('...', { viewportWidth: 800 }, () => { ... }))

Implementation:

• Added a new overrideLevel value, suiteOrTest, to @packages/config. It permits suite- and test-level config overrides but rejects run-time mutation via Cypress.config(). viewportWidth/viewportHeight now use this level (they were previously any).
• validateOverridableAtRunTime now receives the current override context ('suite' / 'test' / undefined for run-time) instead of a single isSuiteLevelOverride boolean, so it can distinguish an it-level override from a run-time Cypress.config() call.
• Added a dedicated, actionable error message (config.cypress_config_api.suite_or_test_only) that explains the reasoning and points users to cy.viewport() or describe/it overrides.
• Cross-origin config syncing applies its diff via Cypress.config() at run-time, so suiteOrTest values are now omitted from that sync. Viewport is already propagated to spec bridges via state (not config), so this is a no-op for behavior and avoids a false positive in cy.origin().
• Added a 16.0.0 changelog entry.

Steps to test

1. In a test, call Cypress.config('viewportWidth', 200) (or viewportHeight) inside the test body — Cypress should fail the test with an error explaining it cannot be overridden during test execution.
2. Confirm the supported alternatives still work:
   • cy.viewport(400, 300) resizes the viewport.
   • it('...', { viewportWidth: 400, viewportHeight: 300 }, () => { ... }) applies the viewport for that test.
   • describe('...', { viewportWidth: 400 }, () => { ... }) applies the viewport for the suite.
3. Confirm reading config is unaffected: Cypress.config('viewportWidth') still returns the current value.

How has the user experience changed?

Calling Cypress.config('viewportWidth', <n>) / Cypress.config('viewportHeight', <n>) during a test now throws:

Cypress.config() cannot override viewportWidth during test execution because it would affect the next test rather than the current one and is not reflected in Test Replay. Set viewportWidth in the test configuration of a describe/context or it block, or use cy.viewport() instead.

There is no visual change; the difference is the new error and the steering toward cy.viewport() / test config overrides.

PR Tasks

• Is there an associated issue with maintainer approval for PR submission? — Don't allow setting viewportHeight and viewportWidth via Cypress.config during test execution #31592 (opened by a maintainer, labeled type: breaking change)
• Have tests been added/updated? — unit tests in @packages/config and driver e2e/validation specs
• [na] Has a PR for user-facing changes been opened in cypress-documentation?
• [na] Have API changes been updated in the type definitions? — viewportWidth/viewportHeight remain valid in TestConfigOverrides (still allowed in describe/it); the restriction is enforced at run-time validation, so no type-definition change is required.

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Note

Medium Risk
Breaking behavior for tests that resized the viewport via Cypress.config() during execution; config override plumbing changed but scope is limited to viewport and validation context.

Overview
Breaking change: viewportWidth and viewportHeight can no longer be set with Cypress.config() while a test is running. Suite- and test-level overrides (describe/it config) and cy.viewport() are unchanged.

Config validation gains a suiteOrTest override level (allowed in Mocha overrides, rejected at run-time) and replaces the boolean isSuiteOverride with CurrentOverrideLevel (suite | test | runtime | undefined) so run-time Cypress.config() calls are distinguished from it-level overrides. Viewport options move from any to suiteOrTest.

The driver surfaces a new suite_or_test_only error (with optional cy.viewport() hints for viewport keys). Cross-origin config sync drops suiteOrTest keys from diffs applied via Cypress.config() at run-time so cy.origin() does not hit false positives.

Changelog documents the breaking behavior for 16.0.0; unit and e2e tests cover validation and failure messages.

^{Reviewed by Cursor Bugbot for commit 2ec276d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cypress]

cypress    Run #72298

Run Properties:   Passed #72298  •  2ec276dbba: Merge branch 'release/16.0.0' into claude/release-16-0-0-change-8396sx

Project	cypress
Branch Review	claude/release-16-0-0-change-8396sx
Run status	Passed #72298
Run duration	08m 04s
Commit	2ec276dbba: Merge branch 'release/16.0.0' into claude/release-16-0-0-change-8396sx
Committer	Jennifer Shehane
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	0
Pending	5
Skipped	0
Passing	0
View all changes introduced in this branch ↗︎

---

Warning

No Report: Something went wrong and we could not generate a report for the Application Quality products.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fc89400. Configure here.}