Merge pull request #55 from alexkrolick/pr/find-by

docs: add `findBy` query type docs.

Author: alexkrolick

docs/api-queries.md

@@ -26,9 +26,26 @@ present.
 
 ### queryAllBy
 
-`queryAllBy*`queries return an array of all matching nodes for a query, and
+`queryAllBy*` queries return an array of all matching nodes for a query, and
 return an empty array (`[]`) if no elements match.
 
+### findBy
+
+`findBy*` queries return a promise which resolves when an element is found which
+matches the given query. The promise is rejected if no element is found after
+a default timeout of `4500`ms.
+
+> Note, this is a simple combination of `getBy*` queries and
+> [`waitForElement`](/docs/api-async#waitforelement). The `findBy*` queries
+> accept the `waitForElement` options as the last argument. (i.e.
+> `findByText(container, 'text', queryOptions, waitForElementOptions)`)
+
+### findAllBy
+
+`findAllBy*` queries return a promise which resolves to an array of elements when
+any elements are found which match the given query. The promise is rejected if no
+elements are found after a default timeout of `4500`ms.
+
 ## Options
 
 The argument to a query can be a _string_, _regular expression_, or _function_.
@@ -41,6 +58,7 @@ See [TextMatch](#textmatch) for documentation on what can be passed to a query.
 ### `ByLabelText`
 
 > getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText
+> findByLabelText, findAllByLabelText
 
 ```typescript
 getByLabelText(
@@ -128,7 +146,7 @@ const inputNode = getByLabelText(container, 'username', {
 ### `ByPlaceholderText`
 
 > getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText,
-> queryAllByPlaceholderText
+> queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText
 
 ```typescript
 getByPlaceholderText(
@@ -182,7 +200,7 @@ cy.getByPlaceholderText('Username').should('exist')
 
 ### `ByText`
 
-> getByText, queryByText, getAllByText, queryAllByText
+> getByText, queryByText, getAllByText, queryAllByText, findByText, findAllByText
 
 ```typescript
 getByText(
@@ -253,7 +271,8 @@ If you'd rather disable this behavior, set `ignore` to `false`.
 
 ### `ByAltText`
 
-> getByAltText, queryByAltText, getAllByAltText, queryAllByAltText
+> getByAltText, queryByAltText, getAllByAltText, queryAllByAltText, findByAltText,
+> findAllByAltText
 
 ```typescript
 getByAltText(
@@ -308,7 +327,8 @@ cy.getByAltText(/incredibles.*png$/i).should('exist')
 
 ### `ByTitle`
 
-> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle
+> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle, findByTitle,
+> findAllByTitle
 
 ```typescript
 getByTitle(
@@ -366,7 +386,7 @@ cy.getByTitle('Close').should('exist')
 ### `ByDisplayValue`
 
 > getByDisplayValue, queryByDisplayValue, getAllByDisplayValue,
-> queryAllByDisplayValue
+> queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue
 
 ```typescript
 getByDisplayValue(
@@ -501,7 +521,8 @@ cy.getByDisplayName('Alaska').should('exist')
 
 ### `ByRole`
 
-> getByRole, queryByRole, getAllByRole, queryAllByRole
+> getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole,
+> findAllByRole
 
 ```typescript
 getByRole(
@@ -550,7 +571,8 @@ cy.getByRole('dialog').should('exist')
 
 ### `ByTestId`
 
-> getByTestId, queryByTestId, getAllByTestId, queryAllByTestId
+> getByTestId, queryByTestId, getAllByTestId, queryAllByTestId, findByTestId,
+> findAllByTestId
 
 ```typescript
 getByTestId(