.within() now throws an error if given more than one subject #4898

BlueWinds · 2022-12-05T19:49:26Z

Related code PR: cypress-io/cypress#24975

This brings the docs in line with the new behavior.

vercel · 2022-12-05T19:49:31Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
cypress-documentation	✅ Ready (Inspect)	Visit Preview	Dec 5, 2022 at 9:51PM (UTC)

marktnoonan · 2022-12-05T20:34:47Z

Already approved but actually how about updating the examples a little bit:

cy.get('.className') is only safe when it happens to yield just one element. Maybe we should use something like contains() that always yields one thing, or add a .first(). And under "Incorrect Usage" we could add an example where multiple things are yielded by the previous command.

emilyrohrbough · 2022-12-05T20:40:29Z

content/_changelogs/12.0.0.md

@@ -11,6 +11,11 @@ _Released MM/DD/YYYY_
 - Cypress now throws an error if commands are invoked from inside a `.should()`
  callback. This previously resulted in unusual and undefined behavior; it is
  now explicitly an error.
+- The `.within()` command now throws an error if given more than one DOM element


@BlueWinds Can you add a migration guide entry on how to resolve this error?

Added migration guide.

content/_changelogs/12.0.0.md

BlueWinds · 2022-12-05T21:10:43Z

cy.get('.className') is only safe when it happens to yield just one element. Maybe we should use something like contains() that always yields one thing, or add a .first(). And under "Incorrect Usage" we could add an example where multiple things are yielded by the previous command.

Updated the usage section.

Correct Usage

cy.get('.list').first().within(($list) => {}) // Yield the first `.list` and scope all commands within it

Incorrect Usage

cy.within(() => {}) // Errors, cannot be chained off 'cy'
cy.getCookies().within(() => {}) // Errors, 'getCookies' does not yield DOM element
cy.get('div').within(($divs) => {}) // Probably errors, because get('div') yields multiple elements

emilyrohrbough · 2022-12-05T21:36:19Z

content/guides/references/migration-guide.md

@@ -310,6 +310,69 @@ cy.get('button')
   .then(res => { ...handle response... })
 ```

+#### `.within()`
+
+[`.within()`](/api/commands/within) now throws an error if it is passed multiple


Suggested change

[`.within()`](/api/commands/within) now throws an error if it is passed multiple

The [`.within()`](/api/commands/within) command now throws an error if it is passed multiple

Applied this change to all the bits in this section (.invoke() and .should() were phrased the same way).

emilyrohrbough · 2022-12-05T21:36:30Z

content/guides/references/migration-guide.md

+[`.within()`](/api/commands/within) now throws an error if it is passed multiple
+elements as the subject. This previously resulted in inconsistent behavior,
+where some commands would use all passed in elements, some would use only the
+first and ignore the rest, and `.screenshot()` would throw an error.


add link to screenshot cmd

emilyrohrbough · 2022-12-05T21:37:30Z

content/guides/references/migration-guide.md

+-  })
+  .as('rows') // Store multiple elements as an alias
+
+cy.get('@rows').contains('foo')


Why wouldn't they limit the contains selector?

Suggested change

+cy.get('@rows').contains('foo')

+ cy.contains('tr', 'foo')

I'll change the example; this works for .contains, but they might be running assertions, performing actions, or doing anything else that can't be used in this way, which was my intent in this example.

(any set of commands using .within() can be written without .within(). It doesn't provide any unique functionality)

emilyrohrbough · 2022-12-05T21:37:53Z

content/guides/references/migration-guide.md

+invoked from inside a `.should()` callback. This previously resulted in unusual
+and undefined behavior. If you wish to execute a series of commands on the
+yielded value, use`.then()` instead.
+
+```diff
+cy.get('button')
+-  .should(($button) => {
+
+    })
+  .then(api => api.makeARequest('http://example.com'))
+   .then(res => { ...handle response... })
+```
+


copy paste?

* .within() now throws error when passed more than one subject. * Add migration guide, update based on reviews

* Remove pages and references to functionality obsoleted by multidomain GA * fix: Explain error thrown when cypress commands in .should() callback (#4755) * fix: Explain error thrown when cypress commands in .should() callback * Improve layout of previous changes and provide second example of how to fix * Update content/api/commands/should.md Co-authored-by: Rachel <rachel@cypress.io> * Apply suggestions from code review Co-authored-by: Zach Bloomquist <git@chary.us> * Run prettier * Run prettier again...? * One more prettier run... :/ Co-authored-by: Rachel <rachel@cypress.io> Co-authored-by: Zach Bloomquist <git@chary.us> * docs: removing Cookies.defaults/preserveOnce (#4779) * docs: remove experimentalSessionAndOrigin (#4807) * Update cookie commands domain option description (#4861) * docs: Queries, Detached DOM, and Retry-Ability (#4835) * First rework of retryability guide * Update each command's Yields section, and all guides, with information about queries vs commands * Add Custom Queries page * Minor formatting tweaks * Review changes * Review updates * Update based on review + last week meetings * More review updates * Fix tests * breaking: drop node 12, 13, 15 and 17 support (#4879) * Add docs for new local/session storage commands (#4876) * feat: update okta login guide for realworld app (#4883) * feat: update okta login guide for realworld app * chore: make changes to okta to have parity with cognito changes * chore: address code review comments * feat: update cognito login guide for realworld app (#4882) * feat: update cognito login guide for realworld app * chore: update guide from comments in code review * properly close alert tag * Update content/guides/end-to-end-testing/amazon-cognito-authentication.md * chore: address comments from code review * fix linting * v12 Migration Guide (#4862) Co-authored-by: Matt Schile <mschile@cypress.io> Co-authored-by: Blue F <blue@everblue.info> Co-authored-by: DEBRIS APRON <debrisapron@gmail.com> Co-authored-by: Ben M <benm@cypress.io> Closes undefined * Small update to cy.origin API docs for v12 * Update auth examples for v12 on custom commands page * 12: update test isolation docs to use true/false instead of on/off (#4890) Co-authored-by: Chris Breiding <chrisbreiding@users.noreply.github.com> Co-authored-by: Matt Henkes <mjhenkes@gmail.com> Co-authored-by: Bill Glesias <bglesias@gmail.com> * docs: add documentation for experimentalOriginDependencies (#4897) * Documentation updates for v12 (#4880) * re-add websecurity, links to websecurity, and trade-offs guides * chore: revamp documentation around web security page * chore: update same-origin tradeoff to be new navigation rules, including our SD chart, to help paint users a clear picture with cy.origin * chore: link to the experimental modify obstructive third party code doc in web security from origin * chore: update Error Messages section to reflect allowing cross origin visiting * update best practices: visiting external sites * remove node 12 from installing cypress section * chore: update key differences to plug session and origin over programmatic login * chore: update with suggestions from code review * add okta/amazon guide links in trade-offs and update workarounds * feat: add cross origin testing guide * update image for command time out with visit * chore: readd legacy errors and add a Note section to explain that this is only for cypress v11 and under * chore: update suggestions from code review * chore: add suggestions from code review * fix: fix okta alert banner (needed a new line) * fix: broken image in error messages * chore: update error header for on link to address cypress-io/cypress-services#5040 (comment) * Update cy.session API docs for v12 (#4851) Co-authored-by: Emily Rohrbough <emilyrohrbough@users.noreply.github.com> Closes #4507 * Remove pages and references to functionality obsoleted by multidomain GA * fix: Explain error thrown when cypress commands in .should() callback (#4755) * fix: Explain error thrown when cypress commands in .should() callback * Improve layout of previous changes and provide second example of how to fix * Update content/api/commands/should.md Co-authored-by: Rachel <rachel@cypress.io> * Apply suggestions from code review Co-authored-by: Zach Bloomquist <git@chary.us> * Run prettier * Run prettier again...? * One more prettier run... :/ Co-authored-by: Rachel <rachel@cypress.io> Co-authored-by: Zach Bloomquist <git@chary.us> * docs: removing Cookies.defaults/preserveOnce (#4779) * docs: remove experimentalSessionAndOrigin (#4807) * Update cookie commands domain option description (#4861) * docs: Queries, Detached DOM, and Retry-Ability (#4835) * First rework of retryability guide * Update each command's Yields section, and all guides, with information about queries vs commands * Add Custom Queries page * Minor formatting tweaks * Review changes * Review updates * Update based on review + last week meetings * More review updates * Fix tests * breaking: drop node 12, 13, 15 and 17 support (#4879) * Add docs for new local/session storage commands (#4876) * feat: update okta login guide for realworld app (#4883) * feat: update okta login guide for realworld app * chore: make changes to okta to have parity with cognito changes * chore: address code review comments * feat: update cognito login guide for realworld app (#4882) * feat: update cognito login guide for realworld app * chore: update guide from comments in code review * properly close alert tag * Update content/guides/end-to-end-testing/amazon-cognito-authentication.md * chore: address comments from code review * fix linting * v12 Migration Guide (#4862) Co-authored-by: Matt Schile <mschile@cypress.io> Co-authored-by: Blue F <blue@everblue.info> Co-authored-by: DEBRIS APRON <debrisapron@gmail.com> Co-authored-by: Ben M <benm@cypress.io> Closes undefined * 12: update test isolation docs to use true/false instead of on/off (#4890) Co-authored-by: Chris Breiding <chrisbreiding@users.noreply.github.com> Co-authored-by: Matt Henkes <mjhenkes@gmail.com> Co-authored-by: Bill Glesias <bglesias@gmail.com> * docs: add documentation for experimentalOriginDependencies (#4897) * Documentation updates for v12 (#4880) * re-add websecurity, links to websecurity, and trade-offs guides * chore: revamp documentation around web security page * chore: update same-origin tradeoff to be new navigation rules, including our SD chart, to help paint users a clear picture with cy.origin * chore: link to the experimental modify obstructive third party code doc in web security from origin * chore: update Error Messages section to reflect allowing cross origin visiting * update best practices: visiting external sites * remove node 12 from installing cypress section * chore: update key differences to plug session and origin over programmatic login * chore: update with suggestions from code review * add okta/amazon guide links in trade-offs and update workarounds * feat: add cross origin testing guide * update image for command time out with visit * chore: readd legacy errors and add a Note section to explain that this is only for cypress v11 and under * chore: update suggestions from code review * chore: add suggestions from code review * fix: fix okta alert banner (needed a new line) * fix: broken image in error messages * chore: update error header for on link to address cypress-io/cypress-services#5040 (comment) * Update auth examples for v12 on custom commands page * Small update to cy.origin API docs for v12 * Update cy.session API docs for v12 (#4851) Co-authored-by: Emily Rohrbough <emilyrohrbough@users.noreply.github.com> Closes #4507 * chore: address docs feedback post merge (#4899) * .within() now throws an error if given more than one subject (#4898) * .within() now throws error when passed more than one subject. * Add migration guide, update based on reviews * Update Logging In section of Testing Your App page (#4885) Co-authored-by: Emily Rohrbough <emilyrohrbough@users.noreply.github.com> Closes #4498 * Update End-to-End Testing -> Auth0 Authentication docs for v12 (#4895) Co-authored-by: Bill Glesias <bglesias@gmail.com> * Cypress.Session Cypress API (#4900) * docs around Cypress.session api * data not date * Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes <mjhenkes@gmail.com> * Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes <mjhenkes@gmail.com> * Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes <mjhenkes@gmail.com> * Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes <mjhenkes@gmail.com> * fix markdown * Update content/api/cypress-api/session.md * Apply suggestions from code review Co-authored-by: Matt Henkes <mjhenkes@gmail.com> * V12 ChangeLog (#4896) Co-authored-by: Matt Schile <mschile@cypress.io> Co-authored-by: Blue F <blue@everblue.info> Co-authored-by: DEBRIS APRON <debrisapron@gmail.com> Co-authored-by: Ben M <benm@cypress.io> Co-authored-by: Ryan Manuel <ryanm@cypress.io> Co-authored-by: Chris Breiding <chrisbreiding@users.noreply.github.com> Co-authored-by: DEBRIS APRON <debrisapron@gmail.com> Co-authored-by: Blue F <blue@everblue.info> Co-authored-by: Rachel <rachel@cypress.io> Co-authored-by: Zach Bloomquist <git@chary.us> Co-authored-by: Matt Schile <mschile@cypress.io> Co-authored-by: Matt Henkes <mjhenkes@gmail.com> Co-authored-by: Chris Breiding <chrisbreiding@users.noreply.github.com> Co-authored-by: Bill Glesias <bglesias@gmail.com> Co-authored-by: Ben M <benm@cypress.io> Co-authored-by: Ryan Manuel <ryanm@cypress.io>

.within() now throws error when passed more than one subject.

1a22349

BlueWinds mentioned this pull request Dec 5, 2022

fix: .within() now throws an error if given more than one subject. cypress-io/cypress#24975

Merged

2 tasks

BlueWinds changed the base branch from master to v12 December 5, 2022 19:49

vercel bot had a problem deploying to Preview December 5, 2022 19:51 Failure

marktnoonan approved these changes Dec 5, 2022

View reviewed changes

emilyrohrbough reviewed Dec 5, 2022

View reviewed changes

content/_changelogs/12.0.0.md Outdated Show resolved Hide resolved

Add migration guide, update based on reviews

ee8a380

vercel bot deployed to Preview December 5, 2022 21:28 View deployment

emilyrohrbough reviewed Dec 5, 2022

View reviewed changes

Review feedback

c6b95d9

vercel bot deployed to Preview December 5, 2022 21:51 View deployment

mjhenkes approved these changes Dec 5, 2022

View reviewed changes

emilyrohrbough approved these changes Dec 5, 2022

View reviewed changes

BlueWinds merged commit 0dcf3a0 into v12 Dec 5, 2022

BlueWinds deleted the pr-24975-one-within-subject branch December 5, 2022 22:21

debrisapron pushed a commit that referenced this pull request Dec 6, 2022

.within() now throws an error if given more than one subject (#4898)

aeaa7c4

* .within() now throws error when passed more than one subject. * Add migration guide, update based on reviews

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.within() now throws an error if given more than one subject #4898

.within() now throws an error if given more than one subject #4898

BlueWinds commented Dec 5, 2022

vercel bot commented Dec 5, 2022 •

edited

marktnoonan commented Dec 5, 2022

emilyrohrbough Dec 5, 2022

BlueWinds Dec 5, 2022

BlueWinds commented Dec 5, 2022

emilyrohrbough Dec 5, 2022

BlueWinds Dec 5, 2022

emilyrohrbough Dec 5, 2022

BlueWinds Dec 5, 2022

emilyrohrbough Dec 5, 2022

BlueWinds Dec 5, 2022

BlueWinds Dec 5, 2022

emilyrohrbough Dec 5, 2022

	[`.within()`](/api/commands/within) now throws an error if it is passed multiple
	The [`.within()`](/api/commands/within) command now throws an error if it is passed multiple

.within() now throws an error if given more than one subject #4898

.within() now throws an error if given more than one subject #4898

Conversation

BlueWinds commented Dec 5, 2022

vercel bot commented Dec 5, 2022 • edited

marktnoonan commented Dec 5, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BlueWinds commented Dec 5, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vercel bot commented Dec 5, 2022 •

edited