wait and waitForValueToChange async utils

[mpeyper]

What:

Added additional async utils:

• wait(callback)
• waitForValueToChange(selector)

Resolves #173

Why:

These additional utils privide similar to the wait and waitForElement/waitForElementToBeRemoved from the dom-testing-library async utils.

This compliments the waitForNextUpdate utility we already provide that shares similarities to the waitForDomChange utility.

How:

Theses utilities are layers on top of waitForNextUpdate, running their relevant checks on each rerender of the test component.

I chose to be constsent with dom-testing-library by not pushing any values into the callbacks, but rather allow/expect the existing APIs to be used within them, this means testing for a value to change looks like:

test('should wait for value to change', async () => {
  const { result, waitForValueToChange } = renderHook(() => useSomeHook())

  await waitForValueToChange(() => result.current.someValue === 'expected value')

  // perform assertions
}

instead of

test('should wait for value to change', async () => {
  const { waitForValueToChange } = renderHook(() => useSomeHook())

  await waitForValueToChange((currentResult) => currentResult.someValue === 'expected value')

  // perform assertions
}

or something similar.

I anticipate this to cause some confusion when people first start using it so I have tried to call it out explicitly in the API reference docs. I have not made any changes to the usage docs yet as I want to get a feeling on what people are struggling with and how best to describe the intent and usage before making those changes.

I'm not super sold on the name of waitForValueToChange and may change it, so if you have any suggestions, I'd love to hear them.

I'm also thinking about refactoring the implementation to have wait as the underlying utility instead of waitForNextUpdate by proving a () => {} callback to wait. I think this might make more conceptual sense to anyone else coming in and trying to understand how these all fir together.

Checklist:

• Documentation updated
• Tests
• Ready to be merged
  

[codecov]

Codecov Report

Merging #200 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff          @@
##           master   #200   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files           3      4    +1     
  Lines          56     95   +39     
  Branches        5     15   +10     
=====================================
+ Hits           56     95   +39

Impacted Files	Coverage Δ
src/pure.js	100% <ø> (ø)	⬆️
src/asyncUtils.js	100% <100%> (ø)

---

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 6cb2832...66a49f7. Read the comment docs.

[mpeyper]

I'm also thinking about refactoring the implementation to have wait as the underlying utility

I had a stab at this and it was actually way more complicated than I expected to flip the waitForNextUpdate and wait relationship around due to how when the render listeners resolve. This could probably be overcome with an overhaul of that system, but I chose not to do that at this time.

I did manage to refactor waitForValueToChange to use wait under the hood indead of duplicating much of the logic. This introduced a new option into the mix, suppressErrors, which is true by default for wait but false by default for waitForValueToChange. I'm considering not surfacing this as an API option as I feel like it's starting to diverge a bit from the intended goal of providing dom-testing-library inspired utilites, which basically offer a timeout and an interval (which doesn't apply to us as we use the next render as the trigger to retest the conditions) option, but I'm not sure yet.

I've also been thinking about the name waitForValueToChange and I'm wondering if waitForNextValue is perhaps a bit better? It's consistent with the waitForNextUpdate naming and a bit more concise to type, but I'm not sure it's as descriptive about what it's waiting for. I dunno. Happy to hear thoughts on this.

[mpeyper]

I've dragged my heels on this long enough on this. I've decided to take the names as they are now and we can always change them if better suggestions come along or if people don't understand them.