Docs: Unclear that `MockedProvider` short circuits after finding the first query match

[Kangaroux]

https://www.apollographql.com/docs/react/development-testing/testing#the-mockedprovider-component

New to Apollo and started working on an existing codebase.

I assumed that mocks were applied in order as if they were queries, but actually it's just "whatever mock matches the request first". It ignores any further matches.

This caused some headaches when dealing with tests. We have a default mock object that most tests use. Based on the docs I assumed I could include the default mock and then a follow up with the changes I wanted. But the changes aren't applied because the default is the first match.

[jerelmiller]

Hey @Kangaroux 👋

I assumed that mocks were applied in order as if they were queries, but actually it's just "whatever mock matches the request first"

Could you clarify what you mean here? Are you saying that you would expect it to just use the first mock in the array, then the next, etc. regardless of the configured query and variables in the mock?

The "whatever mock matches the request first" is partially right, but the most important part is highlighted in the documentation you linked:

Your test must execute an operation that exactly matches a mock's shape and variables to receive the associated mocked response.

So yes it will match the first mock it can in the array, but it does so by checking against the configured query and variables defined in the request object. This allows you to test components that might execute multiple queries (such as when a component renders another component that executes queries) and ensure each query gets the appropriate response. If it just matched top-to-bottom, you risk getting data that isn't associated with the query at all.

As the reusing mocks section suggestions, each mock is only used once and then discarded. This enables you to test refetch flows where you might want to return different data on a 2nd or 3rd fetch. If you prefer to reuse the same result, you can set the maxUsageCount in the mock to reuse it the configured amount before the mock is discarded.

Based on the docs I assumed I could include the default mock and then a follow up with the changes I wanted.

Is there a section of the docs that make you think this? I'd be happy to adjust the documentation to make it more clear that it matches from first to last in the array (its essentially an array.find in the code).