Update promise docs #3201

robinpokorny · 2017-03-24T15:55:34Z

Summary

This pull request changes the documentation at several places regarding the recent async testing handling using .resolves and .rejects.

Change wording of .resolves and .rejects API docs.
Use ‘lemon’/‘octopus’ in Expect API docs.
~~Remove old (non-resolves) promise assertions everywhere in docs~~
Add info about .rejects matcher in ‘Testing Asynchronous Code’.
Update comments in Async tutorial and updated example files.

Related PR: #3172, #3068

Test plan

Changes in the docs.

robinpokorny · 2017-04-10T07:02:00Z

@excitement-engineer and @cpojer, could you please look at this and give me some feedback?

codecov-io · 2017-04-10T07:27:56Z

Codecov Report

Merging #3201 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #3201   +/-   ##
=======================================
  Coverage   63.99%   63.99%           
=======================================
  Files         177      177           
  Lines        6574     6574           
  Branches        4        4           
=======================================
  Hits         4207     4207           
  Misses       2365     2365           
  Partials        2        2

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 46214fb...9d428e0. Read the comment docs.

excitement-engineer · 2017-04-10T16:56:21Z

docs/GlobalAPI.md

-});
-```
-
-Even though the call to `test` will return right away, the test doesn't complete until the promise resolves as well.


I think that these examples are really valuable for people using older versions of jest (i.e. Jest 19 and before) because these versions do not include the .resolves yet. So perhaps we should consider keeping this.

Yeah, let's keep this please.

excitement-engineer · 2017-04-10T17:01:22Z

examples/async/__tests__/user-test.js

-    await user.getUserName(2);
-  } catch (object) {
-    expect(object.error).toEqual('User with 2 not found.');
-  }


I would keep these code examples. They are really useful people using older versions of jest.

Perhaps we can add the .rejects and .resolves examples next to the old examples and mention that these keywords may only be used in jest 20+

Yep, let's keep both examples around. I think that is best.

OK, I agree, I haven't taken into account the users of the previous versions.

I went trough it again, and this change only reflects changes already in the docs in the async tutorial https://facebook.github.io/jest/docs/tutorial-async.html

Now the tutorial and sample code differ.

excitement-engineer · 2017-04-10T17:14:50Z

This code fixes some of the issues I described in issue #3273:) Following issue #3250 , I think we need to make sure that that we keep the old examples and docs around for people using jest 19 and below.

cpojer · 2017-04-11T11:26:33Z

@robinpokorny thanks for helping improve the documentation. I agree with @excitement-engineer, let's keep the old examples around. We aren't deprecating the old way of testing for promises, we are only introducing a second way to test promises. We should also make sure to use expect.assertions for any async test – it should become part of the mindset when people write tests :)

cpojer

See comments.

cpojer · 2017-04-19T18:04:18Z

@robinpokorny are you planning on addressing the feedback from my review?

robinpokorny · 2017-04-20T14:45:57Z

@cpojer, Yes, sorry. Will do it today or tomorrow.

robinpokorny · 2017-04-25T10:54:26Z

I will update the ‘Testing Asynchronous Code’ article to include both options and recommends use of expect.assertions. Do you think that every async test should have it?

cpojer · 2017-04-25T10:58:52Z

Yeah, let's add it to every async test to educate people about it :) Whether they'll use it in the end is not our problem then :D We did our best!

cpojer · 2017-04-28T02:09:05Z

Hey @robinpokorny, do you think you can give this another final pass?

robinpokorny · 2017-05-02T10:22:58Z

Uff, @cpojer, finally had the time for the rewrite.

I added expect.assertions everywhere, I hope.

I also made sure that in both the async tutorial and async testing article, we show all four combinations:

promise with .then/.catch and return
promise with async/await
.resolves/.rejects with return
.resolves/.rejects with async/await

cpojer · 2017-05-02T12:56:09Z

Thanks @robinpokorny, this is great :)

* Update docs on promises * Remove promises from `expect.assertions` and `test` * Keep docs for promise return * Update async docs * Update the async tutorial * Nicer headlines in Testing Async code * Update TestingAsyncCode.md * Update TutorialAsync.md

github-actions · 2021-05-13T17:24:48Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

facebook-github-bot added the CLA Signed ✔️ label Mar 24, 2017

robinpokorny force-pushed the update-promise-docs branch 2 times, most recently from 0c991d6 to ec62e18 Compare March 30, 2017 12:34

robinpokorny force-pushed the update-promise-docs branch from ec62e18 to f8224fb Compare April 10, 2017 06:58

excitement-engineer suggested changes Apr 10, 2017

View reviewed changes

cpojer requested changes Apr 11, 2017

View reviewed changes

cpojer mentioned this pull request Apr 11, 2017

Improved async/await docs #3279

Closed

robinpokorny force-pushed the update-promise-docs branch from 2af8089 to 969d1a7 Compare April 25, 2017 10:52

cpojer added this to the Jest 20 milestone Apr 28, 2017

robinpokorny added 3 commits May 2, 2017 10:27

Update docs on promises

5a915cf

Remove promises from expect.assertions and test

a1f7618

Keep docs for promise return

c6abeb2

robinpokorny force-pushed the update-promise-docs branch from 969d1a7 to c6abeb2 Compare May 2, 2017 08:28

robinpokorny added 2 commits May 2, 2017 11:35

Update async docs

e0fd2eb

Update the async tutorial

9694cf7

robinpokorny force-pushed the update-promise-docs branch from 5e5bc75 to 9694cf7 Compare May 2, 2017 10:06

Nicer headlines in Testing Async code

6d26173

cpojer added 2 commits May 2, 2017 13:54

Update TestingAsyncCode.md

bd5d60e

Update TutorialAsync.md

9d428e0

cpojer merged commit 5749d38 into jestjs:master May 2, 2017

cpojer mentioned this pull request May 2, 2017

Inconsistency in the docs and the examples #3273

Closed

robinpokorny deleted the update-promise-docs branch May 2, 2017 12:58

github-actions bot locked as resolved and limited conversation to collaborators May 13, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update promise docs #3201

Update promise docs #3201

robinpokorny commented Mar 24, 2017 •

edited

Loading

robinpokorny commented Apr 10, 2017

codecov-io commented Apr 10, 2017 •

edited

Loading

excitement-engineer Apr 10, 2017

cpojer Apr 11, 2017

excitement-engineer Apr 10, 2017

excitement-engineer Apr 10, 2017

cpojer Apr 11, 2017

robinpokorny Apr 11, 2017

robinpokorny Apr 25, 2017

excitement-engineer commented Apr 10, 2017

cpojer commented Apr 11, 2017

cpojer left a comment

cpojer commented Apr 19, 2017

robinpokorny commented Apr 20, 2017

robinpokorny commented Apr 25, 2017

cpojer commented Apr 25, 2017

cpojer commented Apr 28, 2017

robinpokorny commented May 2, 2017

cpojer commented May 2, 2017

github-actions bot commented May 13, 2021

Update promise docs #3201

Update promise docs #3201

Conversation

robinpokorny commented Mar 24, 2017 • edited Loading

robinpokorny commented Apr 10, 2017

codecov-io commented Apr 10, 2017 • edited Loading

Codecov Report

excitement-engineer Apr 10, 2017

Choose a reason for hiding this comment

cpojer Apr 11, 2017

Choose a reason for hiding this comment

excitement-engineer Apr 10, 2017

Choose a reason for hiding this comment

excitement-engineer Apr 10, 2017

Choose a reason for hiding this comment

cpojer Apr 11, 2017

Choose a reason for hiding this comment

robinpokorny Apr 11, 2017

Choose a reason for hiding this comment

robinpokorny Apr 25, 2017

Choose a reason for hiding this comment

excitement-engineer commented Apr 10, 2017

cpojer commented Apr 11, 2017

cpojer left a comment

Choose a reason for hiding this comment

cpojer commented Apr 19, 2017

robinpokorny commented Apr 20, 2017

robinpokorny commented Apr 25, 2017

cpojer commented Apr 25, 2017

cpojer commented Apr 28, 2017

robinpokorny commented May 2, 2017

cpojer commented May 2, 2017

github-actions bot commented May 13, 2021

robinpokorny commented Mar 24, 2017 •

edited

Loading

codecov-io commented Apr 10, 2017 •

edited

Loading