fix: Properly type Cypress and Chai globals as properties of the global object

[rewento]

Minor modifications to CLI types so that Cypress and Chai globals are correctly declared not only to be in the global scope but also to be in properties of globalThis, which they are. The change allows composers to reference them through the global object (e.g., 'globalThis.cy.mount', 'globalThis.expect', 'window.assert'). The current typing prohibits this by incorrectly declaring that the objects in question are held in local variables of the global scope rather than in properties of the global object.

• Closes Issue 27539

Additional details

• Why was this change necessary?
  This small change accommodates a coding style convention that demands that values in properties of the global object be accessed via the globalThis property of that object to enhance clarity regarding the origin of the values as globals as opposed to values defined in and imported from modules.
• What is affected by this change?
  The change has no impact on the TypeScript compiler's acceptance of code that uses Cypress globals without that convention, which is the majority of such code.
• Any implementation details to explain?
  Resolving the issue entailed swapping the use of const for var in type declarations in cli/types/cypress-expect.d.ts and cli/types/cypress-global-vars.d.ts.

Steps to test

Ensure that typical code that leverages Cypress like this is still is accepted by the TypeScript compiler:

const browserVersion = window.Cypress.browser.version;
window.cy.mount(AppComponent);
window.assert("foo" !== "bar", "foo is not bar");
window.expect(true).not.to.be.false;

Then confirm that the TypeScript compiler also issues no errors regarding code that follows the aforementioned convention like the following:

const browserVersion = window.Cypress.browser.version;
window.cy.mount(AppComponent);
window.assert("foo" !== "bar", "foo is not bar");
window.expect(true).not.to.be.false;

const browserVersion = globalThis.Cypress.browser.version;
globalThis.cy.mount(AppComponent);
globalThis.assert("foo" !== "bar", "foo is not bar");
globalThis.expect(true).not.to.be.false;

How has the user experience changed?

Before:

After:

PR Tasks

• [na] Have tests been added/updated?
• [no] Has a PR for user-facing changes been opened in cypress-documentation? (Little to no value in drawing attention in the documentation to the fact that globalThis.cy and window.cy now work just as well as cy in TypeScript code.)
• [yes] Have API changes been updated in the type definitions?

[CLAassistant]

All committers have signed the CLA.

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[cypress]

35 flaky tests on run #50391 ↗︎

0

28021

1355

0

35

Details:

Merge branch 'release/13.0.0' into update-cypress-request-version
Project: cypress	Commit: 27f9b3b7d9
Status: Passed	Duration: 23:08 💡
Started: Aug 24, 2023 2:41 PM	Ended: Aug 24, 2023 3:04 PM

  specs_list_latest_runs.cy.ts • 1 flaky test • app-e2e

View Output Video

Test		Artifacts
App/Cloud Integration - Latest runs and Average duration > when no runs are recorded > shows placeholders for all visible specs		Output Screenshots Video

  cypress-origin-communicator.cy.ts • 1 flaky test • app-e2e

View Output Video

Test		Artifacts
Cypress In Cypress Origin Communicator > cy.origin passivity with app interactions > passes upon test reload mid test execution		Output Screenshots Video

  e2e/origin/basic_login.cy.ts • 1 flaky test • 5x-driver-electron

View Output Video

Test		Artifacts
basic login > visit primary first > logs in with idp redirect		Output Video

  e2e/origin/commands/unsupported_commands.cy.ts • 1 flaky test • 5x-driver-electron

View Output Video

Test		Artifacts
cy.origin unsupported commands > cy.origin() is not yet supported		Output Video

  e2e/origin/commands/misc.cy.ts • 1 flaky test • 5x-driver-electron

View Output Video

Test		Artifacts
cy.origin misc > .end()		Output Video

The first 5 flaky specs are shown, see all 23 specs in Cypress Cloud.

_{This comment has been generated by cypress-bot as a result of this project's GitHub integration settings.}

[chrisbreiding]

Thanks for the contribution! Could you add tests for this in cypress-tests.ts? Adding the following should suffice:

namespace CypressGlobalsTests {
  Cypress
  cy
  expect
  assert

  window.Cypress
  window.cy
  window.expect
  window.assert

  globalThis.Cypress
  globalThis.cy
  globalThis.expect
  globalThis.assert
}

[rewento]

@chrisbreiding

I'll soon push a commit on to the source branch of this PR that adds the code you provided in your comment to the cypress-test.ts file verbatim.

However, the JavaScript compiled from that added test code would execute with no runtime error with or without the Cypress and Chai globals type changes introduced in this PR. That being said, the TypeScript compiler would refuse to compile cypress-tests.ts in the first place without those type adjustments.

So is that a good enough addition to the tests? That the added test logic, while incapable of triggering a runtime error under any circumstances, would outright prevent the compilation (and thus execution) of the test code itself without the Cypress and Chai globals type changes in question?

[chrisbreiding]

So is that a good enough addition to the tests? That the added test logic, while incapable of triggering a runtime error under any circumstances, would outright prevent the compilation (and thus execution) of the test code itself without the Cypress and Chai globals type changes in question?

Yes, we have a CI job that runs the TypeScript compiler on that file, so it stands as a test for the TypeScript types. Since it fails without these type additions, it's a perfectly good test that they're doing what we expect them to do. Thanks for adding them!

[cypress-bot]

Released in 13.0.0.

This comment thread has been locked. If you are still experiencing this issue after upgrading to
Cypress v13.0.0, please open a new issue.