Merge branch 'master' into patch-1

Author: afontcu

.all-contributorsrc

@@ -4,6 +4,10 @@ title: Examples
 sidebar_label: Examples
 ---
 
+> Read
+> [Good testing practices with 🦔 Angular Testing Library](https://timdeschryver.dev/posts/good-testing-practices-with-angular-testing-library)
+> for a guided example
+
 counter.component.ts
 
 ```typescript
@@ -31,26 +35,26 @@ export class CounterComponent {
 counter.component.spec.ts
 
 ```typescript
-import { render } from '@testing-library/angular'
-import CounterComponent from './counter.component.ts'
+import { render, screen, fireEvent } from '@testing-library/angular'
+import { CounterComponent } from './counter.component.ts'
 
 describe('Counter', () => {
   test('should render counter', async () => {
-    const { getByText } = await render(CounterComponent, {
+    await render(CounterComponent, {
       componentProperties: { counter: 5 },
     })
 
-    expect(getByText('Current Count: 5'))
+    expect(screen.getByText('Current Count: 5'))
   })
 
   test('should increment the counter on click', async () => {
-    const { getByText, click } = await render(CounterComponent, {
+    await render(CounterComponent, {
       componentProperties: { counter: 5 },
     })
 
-    click(getByText('+'))
+    fireEvent.click(screen.getByText('+'))
 
-    expect(getByText('Current Count: 6'))
+    expect(screen.getByText('Current Count: 6'))
   })
 })
 ```

README.md

@@ -22,6 +22,15 @@ Add this line to your project's `cypress/support/commands.js`:
 import '@testing-library/cypress/add-commands';
 ```
 
+You can now use all of `DOM Testing Library`'s `findBy`, `findAllBy`, `queryBy`
+and `queryAllBy` commands off the global `cy` object.
+[See the `DOM Testing Library` docs for reference](https://testing-library.com/docs/dom-testing-library/api-queries).
+
+> Note: the `get*` queries are not supported because for reasonable Cypress tests you
+> need retryability and `find*` queries already support that. `query*` queries are no longer
+> necessary since v5 and will be removed in v6. `find*` fully support built-in Cypress
+> assertions (removes the only use-case for `query*`).
+
 ## With TypeScript
 
 Typings are defined in `@types/testing-library__cypress` at [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress),
@@ -35,40 +44,30 @@ and should be added as follows in `tsconfig.json`:
 }
 ```
 
-You can now use all of `DOM Testing Library`'s `getBy`, `getAllBy`, `queryBy`
-and `queryAllBy` commands.
-[See `DOM Testing Library` API for reference](dom-testing-library/api-queries.md)
+You can find [all Library definitions here](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress/index.d.ts).
 
 ## Examples
 
-You can find [all library definitions here](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress/index.d.ts).
-
-To show some simple examples (from [https://github.com/testing-library/cypress-testing-library/tree/master/cypress/integration](https://github.com/testing-library/cypress-testing-library/tree/master/cypress/integration)):
+To show some simple examples (from
+[cypress/integration/query.spec.js](https://github.com/testing-library/cypress-testing-library/blob/master/cypress/integration/query.spec.js) or [cypress/integration/find.spec.js](https://github.com/testing-library/cypress-testing-library/blob/master/cypress/integration/find.spec.js)):
 
 ```javascript
-cy.findAllByText(/^Button Text \d$/)
-  .should('have.length', 2)
-  .click({ multiple: true })
-  .should('contain', 'Button Clicked')
-cy.queryByText('Button Text 1')
-  .click()
-  .should('contain', 'Button Clicked')
-cy.queryByText('Non-existing Button Text', { timeout: 100 }).should('not.exist')
-cy.queryByLabelText('Label 1')
-  .click()
-  .type('Hello Input Labelled By Id')
-cy.get('#nested').within(() => {
-  cy.queryByText('Button Text 2').click()
-})
-cy.get('#nested').then(subject => {
-  cy.queryByText(/^Button Text/, { container: subject }).click()
+cy.findByRole('button', {name: /Jackie Chan/i}).click()
+cy.findByRole('button', {name: /Button Text/i}).should('exist')
+cy.findByRole('button', {name: /Non-existing Button Text/i}).should('not.exist')
+cy.findByLabelText(/Label text/i, {timeout: 7000}).should('exist')
+
+// findAllByText _inside_ a form element
+cy.get('form').findByText('button', {name: /Button Text/i}).should('exist')
+cy.findByRole('dialog').within(() => {
+  cy.findByRole('button', {name: /confirm/i})
 })
 ```
 
 `Cypress Testing Library` supports both jQuery elements and DOM nodes. This is
 necessary because Cypress uses jQuery elements, while `DOM Testing Library`
 expects DOM nodes. When you pass a jQuery element as `container`, it will get
 the first DOM node from the collection and use that as the `container` parameter
-for the DOM Testing Library functions.
+for the `DOM Testing Library` functions.
 
 [gh]: https://github.com/testing-library/cypress-testing-library