docs: add FAQ section about how flushPromises work (closes testing-library#11) (testing-library#15)

* Add FAQ section about how flushPromises work

* Some subtle changes

Author: gnapse

packages/react-testing-library/README.md

@@ -345,6 +345,27 @@ That's not to say that there's never a use case for doing those things, so they
 should be possible to accomplish, just not the default and natural way to test
 react components.
 
+**How does `flushPromises` work and why would I need it?**
+
+As mentioned [before](#flushpromises), `flushPromises` uses
+[`setImmediate`][set-immediate] to schedule resolving a promise after any pending
+tasks in
+[the message queue](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop)
+are processed. This includes any promises fired before in your test.
+
+If there are promise callbacks already in JavaScript's message queue pending to be
+processed at the time `flushPromises` is called, then these will be processed before
+the promise returned by `flushPromises` is resolved. So when you
+`await flushPromises()` the code immediately after it is guaranteed to occur after
+all the side effects of your async requests have ocurred. This includes any data
+your test components might have requested.
+
+This is useful for instance, if your components perform any data requests and update
+their state with the results when the request is resolved. It's important to note
+that this is only effective if you've mocked out your async requests to resolve
+immediately (like the `axios` mock we have in the examples). It will not `await`
+for promises that are not already resolved by the time you attempt to flush them.
+
 ## Other Solutions
 
 In preparing this project,
@@ -421,3 +442,4 @@ MIT
 [twitter-badge]: https://img.shields.io/twitter/url/https/github.com/kentcdodds/react-testing-library.svg?style=social
 [emojis]: https://github.com/kentcdodds/all-contributors#emoji-key
 [all-contributors]: https://github.com/kentcdodds/all-contributors
+[set-immediate]: https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate