feat: Create public `Cypress.ensure` API for use with custom queries #24697

BlueWinds · 2022-11-15T19:29:50Z

User facing changelog

Creates and adds types to Cypress.ensure API, which can be useful for creating custom queries. This new API is based off the previously undocumented cy.ensure* methods, which are now removed.

In addition, adds public types to cy.now(), which is again useful for custom queries.

Additional details

All the methods on Cypress.ensure are pre-existing, and were already on cy. This PR updates the arguments slightly for consistency, moves many of them to Cypress, and and adds publicly-facing types. Those that didn't end up on Cypress.ensure are split up around the codebase near where they're used.

These are referenced in the Custom Query documentation, which is "why this, why now." cypress-io/cypress-documentation#4835

Steps to test

Type tests have been added. All these commands are also used internally.

How has the user experience changed?

No change to the user experience for the vast majority of users. Plugin authors will have to do less TS juggling to get things to work.

PR Tasks

Have tests been added/updated?
[n/a] Has the original issue (or this PR, if no issue exists) been tagged with a release in ZenHub? (user-facing changes only)
Has a PR for user-facing changes been opened in cypress-documentation? Queries, Detached DOM, and Retry-Ability cypress-documentation#4835
Have API changes been updated in the type definitions?

cypress-bot · 2022-11-15T19:29:53Z

Thanks for taking the time to open a PR!

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.
Become familiar with the Code Review Checklist for guidelines on coding standards and what needs to be done before a PR can be merged.

BlueWinds · 2022-11-15T19:32:27Z

cli/types/cypress.d.ts

@@ -1163,6 +1163,15 @@ declare namespace Cypress {
     */
    end(): Chainable<null>

+    ensureElement(subject: any, commandName: string): void


any => void is correct here, even for ensureAttached, which really only makes sense with DOM elements: you can pass in any subject, and these functions either do nothing and return nothing, or they throw an error.

BlueWinds · 2022-11-15T19:37:28Z

cli/types/cypress.d.ts

+     *
+     * @see https://on.cypress.io/custom-queries
+     */
+    now(name: string, ...args: any[]): Promise<any> | ((subject: any) => any)


I tried to be more specific, with name, args and the return type mapping to ChainableMethods, but typescript ended up caught in a recursion, since now is one of those ChainableMethods.

What we really need to do is go through and separate out "things on cy (like now, off, on, once)" from "commands that can be chained (like click, get, scrollTo)", but that would involve a larger refactor of the types than I want to undertake in this PR.

BlueWinds · 2022-11-15T19:40:02Z

packages/driver/src/cy/commands/misc.ts

@@ -14,15 +14,15 @@ export default (Commands, Cypress, cy, state) => {
  Commands.add('end', () => null)
  Commands.add('noop', (arg) => arg)

-  Commands.addQuery('log', (msg, ...args) => {
+  Commands.add('log', (msg, ...args) => {


As per discussion in the docs PR, .log() should be a command and not a query.

Generally speaking, things that yield null don't make sense as queries, I just got overzealous and converted a few too many commands. :P

I wasn't even looking for this change here. 👍🏻

BlueWinds · 2022-11-15T19:41:37Z

packages/driver/src/cy/ensures.ts

-  const validateType = (subject, type, cmd = state('current')) => {
-    const name = cmd.get('name')
-
+  const validateType = (subject, type, name) => {


I changed all of these to accept name, so that the signatures of the various "ensures" functions match with each other. Name is the only property we read off of command anyway. For a while I thought I needed the full command, but that ended up refactored away at some point, and just never got around to reverting the signatures.

The name / command arguments are new in Cy12, so we can be completely certain no one outside the monorepo is using them.

BlueWinds · 2022-11-15T19:45:26Z

packages/driver/src/cypress/error_messages.ts

@@ -853,11 +853,11 @@ export default {
    },
    invalid_new_query: {
      message: '`Cypress.Commands.addQuery()` is used to create new queries, but `{{name}}` is an existing Cypress command or query, or is reserved internally by Cypress.\n\n If you want to override an existing command or query, use `Cypress.Commands.overrideQuery()` instead.',
-      docsUrl: 'https://on.cypress.io/custom-commands',
+      docsUrl: 'https://on.cypress.io/custom-queries',


This is a new on link, for the new page I'm adding in the docs PR. I'll open a services PR to add it shortly.

cypress · 2022-11-15T21:14:37Z

Test summary

21635 • 0 • 1716 • 0 • 3

Run details


Project	cypress
Status	Passed
Commit	`c31e4a4`
Started	Nov 28, 2022 4:27 PM
Ended	Nov 28, 2022 4:45 PM
Duration	17:31 💡
OS	Linux Debian -
Browser	Multiple

View run in Cypress Dashboard ➡️

Flakiness

	specs_list_latest_runs.cy.ts	1
1	App/Cloud Integration - Latest runs and Average duration > when no runs are recorded > shows placeholders for all visible specs
	project-setup.cy.ts	1
1	... > can setup e2e testing for a project selecting JS
	cypress-origin-communicator.cy.ts	1
1	Cypress In Cypress Origin Communicator > cy.origin passivity with app interactions > passes upon test reload mid test execution

This comment has been generated by cypress-bot as a result of this project's GitHub integration settings. You can manage this integration in this project's settings in the Cypress Dashboard

BlueWinds · 2022-11-21T21:38:46Z

packages/driver/cypress/e2e/commands/actions/check.cy.js

@@ -323,24 +323,27 @@ describe('src/cy/commands/actions/check', () => {
    })

    it('can set options.waitForAnimations', () => {
-      cy.stub(cy, 'ensureElementIsNotAnimating').throws(new Error('animating!'))


Because I moved ensureElementIsNotAnimating to $actionability, which is not public-facing, it's no longer trivial to stub. I've moved these tests to use an actual jQuery animation, and watch the count of command retries - this treats Cypress more as a 'black box', rather than peering inside at exactly how animation is determined.

BlueWinds · 2022-11-21T21:40:39Z

packages/driver/cypress/e2e/commands/actions/click.cy.js

@@ -3339,21 +3303,6 @@ describe('src/cy/commands/actions/click', () => {
        })
      })

-      // TODO: remove this after 4.0 when {multiple:true} is no longer default


TODO from Cypress 4.0, referencing a long-closed issue. TODO done.

Basically, {multiple: true} used to be the default, so it was hidden in the console logs; in Cy >=4.0.0, this is no longer the case, so there's no default value to hide.

BlueWinds · 2022-11-21T21:42:48Z

packages/driver/src/cypress/cy.ts

@@ -121,6 +120,14 @@ const setTopOnError = function (Cypress, cy: $Cy) {
  top.__alreadySetErrorHandlers__ = true
 }

+const ensureRunnable = (cy, cmd) => {


ensureRunnable is only used in this one file, so I moved it here to be close to where it's used.

BlueWinds · 2022-11-21T21:43:58Z

packages/driver/src/cy/actionability.ts

@@ -53,9 +54,127 @@ const getPositionFromArguments = function (positionOrX, y, options) {
  return { options, position, x, y }
 }

+const ensureElDoesNotHaveCSS = ($el, cssProperty, cssValue, name: string, onFail) => {


Several methods from ensures.ts are only used here, and don't really make sense to expose for people to use in queries. I've moved them into this file.

…ts-improvements

cli/types/cypress.d.ts

packages/driver/src/cy/assertions.ts

packages/driver/src/cypress/ensure.ts

emilyrohrbough · 2022-11-22T18:33:53Z

packages/driver/src/cypress/ensure.ts

+}
+
+const isNotDisabled = (subject, name: string, onFail) => {
+  if (subject.prop('disabled')) {


with exposing these publicly, any risk someone will pass a non-jquery element to isNotDisabled?

Hm. Interesting thing to think about. The intended usage would be something like

Cypress.ensure.isElement(subject, 'myQuery') Cypress.ensure.isNotDisabled(subject, 'myQuery')

If they don't ensure that it is an element first, and it's not an element, as it stands it would probably throw a pretty non-helpful error like "can't read property prop of null" or something.

If we added an implicit isElement() check to the top of each of these functions, that would provide more helpful error messages - but then we'd be running duplicate code for pretty much every cypress command.

I'm inclined to leave it as-is, but open to other thoughts.

maybe we be a bit more guarded in our check? if the original conditions are not met, ignore it?

if (subject.prop && _.isFunction(subject.prop) && subject.prop('disabled') {

though ignoring it sort of assumes it's true when it might be invalid? but oh well

cli/types/cypress.d.ts

packages/driver/src/cypress/ensure.ts

packages/driver/src/cy/actionability.ts

emilyrohrbough · 2022-11-22T18:55:06Z

packages/driver/src/cy/commands/querying/querying.ts

@@ -375,7 +375,7 @@ export default (Commands, Cypress, cy, state) => {
    })

    return (subject) => {
-      cy.ensureSubjectByType(subject, 'element', this)
+      Cypress.ensure.isType(subject, 'element', 'shadow', cy)


honestly love how these read these updates! Nice job.

…ts-improvements

cli/types/cypress.d.ts

Co-authored-by: Emily Rohrbough <emilyrohrbough@users.noreply.github.com>

chrisbreiding

In regards to documentation, will Cypress.ensure get its own page like Cypress.dom or just the mentions on the custom-queries page?

BlueWinds · 2022-11-28T20:44:17Z

In regards to documentation, will Cypress.ensure get its own page like Cypress.dom or just the mentions on the custom-queries page?

I was planning to leave it with just the mentions on custom-queries for now. Adding a page documenting it more explicitly can be a post-release task.

fix: Improve TypeScript support for custom queries

5251e63

Typo fix

24d80c4

BlueWinds commented Nov 15, 2022

View reviewed changes

BlueWinds mentioned this pull request Nov 15, 2022

Queries, Detached DOM, and Retry-Ability cypress-io/cypress-documentation#4835

Merged

Fix TS more

0478234

Move 'ensures' off of cy and onto Cypress

6eebcf2

BlueWinds changed the title ~~fix: Improve TypeScript support for custom queries~~ feat: Add public TypeScript support for custom queries Nov 21, 2022

BlueWinds commented Nov 21, 2022

View reviewed changes

BlueWinds added 2 commits November 21, 2022 13:59

Type fixes

1e6fb5f

One missed replacement

17fe50a

BlueWinds force-pushed the issue-7306-ts-improvements branch from 0d674d0 to 17fe50a Compare November 22, 2022 16:27

BlueWinds added 4 commits November 22, 2022 08:43

Merge remote-tracking branch 'origin/release/12.0.0' into issue-7306-…

35f2d3b

…ts-improvements

Test fixes

623d0d3

Properly pass in to ensureRunnable

0087983

Add .eslintignores to quiet down warnings

0e11247

BlueWinds changed the title ~~feat: Add public TypeScript support for custom queries~~ feat: Create public Cypress.ensure API for use with custom queries Nov 22, 2022

BlueWinds marked this pull request as ready for review November 22, 2022 18:19