Expand clarification of cy.wrap() when used with Promises

[jennifer-shehane]

Truthfully #1808 originally addressed this, but the examples were not obvious enough (needs to be specified in the assertions and could probably use a less complicated example as noted in #2664)

• close Makes wrap(promise) more prominent #2664
• close Document "wrap(promise)" use case #1322

[TheJoeSchr]

👍

I still find it mighty important to mention this behavior at the top of the documentation. otherwise it will still be overlooked. once I know I needed wrap to wait for promises I didn't have a problem implenting it.

[jennifer-shehane]

There's an entire section on Promises.

Highlighting one use case of a command at the top of the API documents would quickly get out of hand if everyone requested their specific use case be highlighted more importantly. There's multiple reasons to use wrap, so I don't see why this use case should require more highlighting than the others.

[TheJoeSchr]

Because, if you see it with beginners eye, the naming of the method .wrap makes the other uses cases quite obvious (like wrapping a object so it can be used with other cy. methods).

That's clear from the name, but many would have never thought (like seen in the linked issues thread) about using it to wait for a promise and then use it's result already wrapped.

I think it just cost me and several others dozen of hours, because whenever as a newbie you see .wrap somewhere linked, you click on it, you read the page header, think "duh, it's for wrapping 'dumb' objects" and never bother to scroll down to the examplez.

Because why would you think about that there is some "hidden" additional feature, which is pretty important if you work with promises, you need to learn about via an example, if there is no indication given at the top, that it can be used for other uses than just make object .cy aware.

Highlighting one use case of a command at the top of the API documents would quickly get out of hand if everyone requested their specific use case be highlighted more importantly.
I don't think there is a need to bring other precedent in it. It's just an outlier of a not so obvious named method.

And since a lot of use cases of cypress need promises/async workflow, I think it's pretty important for newcomers to get a grip on this feature of .wrap.

All in all it made my first encounter with using cypress for something more than the obvious quite frustrating and I think this simple fix could help other newcomers a lot.

[bahmutov]

I don't think we should call it "retry" since we are NOT going to re-execute the promise, it is impossible. I think we can say "will automatically wait until the promise resolves".

We should also note that if the promise is rejected, cy.wrap will fail the test

[bahmutov]

I think at the top we could mention it @jennifer-shehane

Yield the object passed into `.wrap()`. If the object is a Promise, yield its resolved value.

Also I noticed at the bottom we are not including the following links

• https://example.cypress.io/commands/misc#wrap (we got to deploy new Kitchensink, since we already have anchors there, see https://github.com/cypress-io/cypress-example-kitchensink/blob/master/app/commands/misc.html#L179)
• https://github.com/cypress-io/cypress-example-recipes/tree/master/examples/unit-testing__application-code has several cy.wrap examples

[jennifer-shehane]

Updated based off of @bahmutov feedback - did not link to example recipes since that has not been deployed. Will go back to update inter-links after that's deployed on API pages.

[TheJoeSchr]

🙌