feat: addQuery Remaining Queries

[BlueWinds]

• Closes Update remaining queries to use _addQuery() #23902

User facing changelog

• If cy.getCookie() fails to find a cookie, you can no longer traverse the non-existent cookie's properties (eg, with .its('value)). If you expect a cookie not to exist, assert that directly, eg: cy.getCookie('foo1').should('not.exist')
• .invoke() no longer waits for promises to resolve. If you wish to await a promise, use cy.then() instead.

This PR updates the following commands to be queries:

.debug()
.document()
.end()
.focused()
.hash()
.its()
.invoke()
.location()
.log()
.pause()
.url()
.title()
.window()

All traversals are also updated (traversals are grouped together because they share code):

.children()
.closest()
.eq()
.filter()
.find()
.first()
.last()
.next()
.nextAll()
.nextUntil()
.not()
.parent()
.parents()
.parentsUntil()
.prev()
.prevAll()
.prevUntil()
.siblings()

Error messages when selectors fail, and when commands receive invalid subjects, have also been improved; see below for screenshots.

Additional details

Steps to test

it('passes', () => {
  cy.$$('body').prepend('<div id="foo"><button>foo</button></div>')

  setTimeout(() => {
    cy.$$('#foo').replaceWith('<span id="foo"><a class="active">bar</a></span>')
  }, 1000)

  cy.get('#foo').children().should('have.class', 'active')
})

This test passes on this branch, and fails on develop or issue-7306.

How has the user experience changed?

Traversal failure

When queries initially succeed but later fail (because the DOM has updated), the error message now shows the whole query that led up to the failure, rather than just the element it failed on.

Old:

Timed out retrying after 500ms: Expected to find element: children, but never found it. Queried from element: <span#foo>

New:

Timed out retrying after 500ms: Expected to find element: children, but never found it. Queried from:

cy.get(body).find(#foo)

Subject validation

In addition to fixing some Detached DOM errors (but not all of them!), several error messages have been updated or added.

When a command receives an invalid subject, it now lists all valid subject types, rather than only the first plus the mysterious phrase "all X subject validations failed".

Old:

cy.scrollTo() failed because it requires a DOM element.
...
All 2 subject validations failed on this subject.

New:

cy.scrollTo() failed because it requires a DOM element or window.
...

Accessing properties

When using .its() or .invoke() to access nested properties, error messages now contain the full path the user requested. This more closely matches the error message to what the user wrote in their test.

Old:

Timed out retrying after 100ms: cy.invoke() errored because the property: bar returned a string value instead of a function. cy.invoke() can only be used on properties that return callable functions.

cy.invoke() waited for the specified property bar to return a function, but it never did.

New:

Timed out retrying after 100ms: cy.invoke() errored because the property: foo.bar returned a string value instead of a function. cy.invoke() can only be used on properties that return callable functions.

cy.invoke() waited for the specified property foo.bar to return a function, but it never did.

Failed assertions following traversals

When a failed assertion follows a traversal, we now use "subject" as a placeholder to indicate that we never actually reached the assertion.

Old:

[find] #wrapper
[contains] Newer
[assert] expected :cy-contains('Newer'), [type='submit'][value~='Newer'] to have class updated

Timed out retrying after 4000ms: Expected to find content: 'Newer' within the element: <div#wrapper> but never did.

New:

[find] #wrapper
[contains] Newer
[assert] expected subject to have class updated

Timed out retrying after 4000ms: Expected to find content: 'Newer' within the element: <div#wrapper> but never did.

AssertionError
Timed out retrying after 4000ms: Expected to find content: 'Newer' within the element: <div#wrapper> but never did.

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? .invoke() no longer awaits promises in 11.x cypress-documentation#4785
• Have API changes been updated in the type definitions?

[cypress-bot]

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.

[cypress]

---

Test summary

4051 • 0 • 1094 • 0 • 1

---

Run details

Project	cypress
Status	Passed
Commit	7cb9377
Started	Oct 17, 2022 6:03 PM
Ended	Oct 17, 2022 6:18 PM
Duration	15:30 💡
OS	Linux Debian - 11.4
Browser	WebKit 16

View run in Cypress Dashboard ➡️

---

Flakiness

	cypress/e2e/commands/xhr.cy.js		1
1	src/cy/commands/xhr > abort > aborts xhrs currently in flight

---

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]

In the intervening years since this TODO was left, we've refined and better defined exactly what retries and what doesn't.

.then() will never retry, and should not, so removing the commented out tests.

[BlueWinds]

.invoke is fundamentally too flexible. Consider the following invoke commands, all valid.

// Valid
.invoke('method', 'arg1')
.invoke({log: false}, 'method', 'arg1')

// Invalid
.invoke(false, 'method', 'arg1')
.invoke(false, 'arg1')

The invalid cases both have the signature [bool, string]. Is this an invalid options argument, or an invalid path argument? The function signature of .invoke() is too versatile / vague to know for sure.

The new implementation throws a slightly different error, because it's simpler / has fewer conditionals and switch statements than the original. I think it's just as valid of an error.

[BlueWinds]

.invoke() now always includes With Arguments, even if it's an empty array. I strongly prefer consistency in my values over special cases (eg, omit when it's empty).

[BlueWinds]

Behavior change: .invoke() now always puts the actual subject as the Subject in its console logs. The subject was this.obj, the property retrieved is .math.sum. IMO this is more consistent and intuitive.

[BlueWinds]

Behavior change: .invoke() now logs the full path when we tried to fetch it and failed. This makes it easier to debug and more consistent with the rest of Cypress' API design.

I think the fact it didn't used to work this way is more a quirk of implementation than any sort of thought-out-feature.

[BlueWinds]

This is one of the ways .invoke / .its are intertwined: .invoke() creates a log with a different message, then calls .its(). .its() then pulls out that log message and keeps it up to date.

Ugly.

[BlueWinds]

Moved 'element' to the front, so that the new error messages say "expects a DOM element, window or document" - putting the most common / likely value first.

[BlueWinds]

Nice example of how a query can have the same functionality, but be a lot shorter because we don't have to re-write the retry logic inside each one. Was very pleased with how the changes to this file panned out.

[BlueWinds]

This test is a victim of the breaking change to .invoke(): It no longer accepts asynchronous functions (like Cypress.automation).

[BlueWinds]

Just added an extra logging line that was helpful to me understanding how this system test worked.

[flotwig]

The "behavior changes" you've mentioned make sense to me 👍

[flotwig]

If this is intentionally commented out, there should be a comment explaining why.

[BlueWinds]

Not intentional; Fixed in latest commit.

[flotwig]

Is this .its bug recorded anywhere? Even if there's no issue for it, I think it's worth mentioning in the changelog. We're probably not the only folks with tests relying on this quirk.

[flotwig]

In that case, do you think it'd be cleaner to change type to a boolean flag? log.isParent?

[chrisbreiding]

Looks great! It's awesome all these commands will now be resilient to detached dom elements. I really like the error message improvements too.

Should this have an accompanying docs PR for the invoke changes?

[BlueWinds]

Added a new test string change, and matching test: Failed assertions following traversals. See that section of the PR description for an image of the change.

Going through PR feedback now.

[BlueWinds]

Looks great! It's awesome all these commands will now be resilient to detached dom elements. I really like the error message improvements too.

Should this have an accompanying docs PR for the invoke changes?

There definitely should be an accompanying docs PR; I've just been putting updating the docs off for a bit until we finish going through the product review phase for queries, so I can go through the docs page by page and update everything that needs updating all at once.

With that said, the invoke changes specifically are straightforward, so I'll start a detached DOM docs branch today.

[BlueWinds]

Matching docs PR: cypress-io/cypress-documentation#4785

[emilyrohrbough]

I'd be nice if getSubjectFromChain would handle checking for undefined.

[BlueWinds]

Yeah, I've been thinking the same thing.

I'm going to do it in the next PR rather than here - I already have some changes queued to the subject API, so rolling it in there makes sense.