Update angular api (#341)

- sort functions alphabetically - add docs for new functions added to the Angular Testing Library

Author: timdeschryver

docs/angular-testing-library/api.md

@@ -24,110 +24,108 @@ async function render<DirectiveType, WrapperType = WrapperComponent>(
 
 ## Component RenderOptions
 
-### `detectChanges`
+### `componentProperties`
 
-Will call `detectChanges` when the component is compiled
+An object to set `@Input` and `@Output` properties of the component.
 
-**default** : `true`
+**default** : `{}`
 
 **example**:
 
 ```typescript
-const component = await render(AppComponent, { detectChanges: false })
+const component = await render(AppComponent, {
+ componentProperties: {
+ counterValue: 10,
+ send: (value) => { ... }
+ }
+})
 ```
 
-### `declarations`
+### `componentProviders`
 
-A collection of providers needed to render the component via Dependency
-Injection, for example, injectable services or tokens.
+A collection of providers to inject dependencies of the component.
 
 For more info see the
-[Angular docs](https://angular.io/api/core/NgModule#providers).
+[Angular docs](https://angular.io/api/core/Directive#providers).
 
 **default** : `[]`
 
 **example**:
 
 ```typescript
 const component = await render(AppComponent, {
- providers: [
- CustomersService,
- {
- provide: MAX_CUSTOMERS_TOKEN,
- useValue: 10,
- },
- ],
+ componentProviders: [AppComponentService],
 })
 ```
 
-### `imports`
+### `declarations`
 
-A collection of imports needed to render the component, for example, shared
-modules. Adds `NoopAnimationsModule` by default if `BrowserAnimationsModule`
-isn't added to the collection
+A collection of providers needed to render the component via Dependency
+Injection, for example, injectable services or tokens.
 
 For more info see the
-[Angular docs](https://angular.io/api/core/NgModule#imports).
+[Angular docs](https://angular.io/api/core/NgModule#providers).
 
-**default** : `[NoopAnimationsModule]`
+**default** : `[]`
 
 **example**:
 
 ```typescript
 const component = await render(AppComponent, {
- imports: [AppSharedModule, MaterialModule],
+ providers: [
+ CustomersService,
+ {
+ provide: MAX_CUSTOMERS_TOKEN,
+ useValue: 10,
+ },
+ ],
 })
 ```
 
-### `schemas`
-
-A collection of schemas needed to render the component. Allowed values are
-`NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`.
+### `detectChanges`
 
-For more info see the
-[Angular docs](https://angular.io/api/core/NgModule#schemas).
+Will call `detectChanges` when the component is compiled
 
-**default** : `[]`
+**default** : `true`
 
 **example**:
 
 ```typescript
-const component = await render(AppComponent, {
- schemas: [NO_ERRORS_SCHEMA],
-})
+const component = await render(AppComponent, { detectChanges: false })
 ```
 
-### `componentProperties`
+### `excludeComponentDeclaration`
 
-An object to set `@Input` and `@Output` properties of the component.
+Exclude the component to be automatically be added as a declaration. This is
+needed when the component is declared in an imported module.
 
-**default** : `{}`
+**default** : `false`
 
 **example**:
 
 ```typescript
 const component = await render(AppComponent, {
- componentProperties: {
- counterValue: 10,
- send: (value) => { ... }
- }
+ imports: [AppModule], // a module that includes AppComponent
+ excludeComponentDeclaration: true,
 })
 ```
 
-### `componentProviders`
+### `imports`
 
-A collection of providers to inject dependencies of the component.
+A collection of imports needed to render the component, for example, shared
+modules. Adds `NoopAnimationsModule` by default if `BrowserAnimationsModule`
+isn't added to the collection
 
 For more info see the
-[Angular docs](https://angular.io/api/core/Directive#providers).
+[Angular docs](https://angular.io/api/core/NgModule#imports).
 
-**default** : `[]`
+**default** : `[NoopAnimationsModule]`
 
 **example**:
 
 ```typescript
 const component = await render(AppComponent, {
- componentProviders: [AppComponentService],
+ imports: [AppSharedModule, MaterialModule],
 })
 ```
 
@@ -146,22 +144,6 @@ const component = await render(AppComponent, {
 })
 ```
 
-### `excludeComponentDeclaration`
-
-Exclude the component to be automatically be added as a declaration. This is
-needed when the component is declared in an imported module.
-
-**default** : `false`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- imports: [AppModule], // a module that includes AppComponent
- excludeComponentDeclaration: true,
-})
-```
-
 ### `routes`
 
 The route configuration to set up the router service via
@@ -189,6 +171,24 @@ const component = await render(AppComponent, {
 })
 ```
 
+### `schemas`
+
+A collection of schemas needed to render the component. Allowed values are
+`NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`.
+
+For more info see the
+[Angular docs](https://angular.io/api/core/NgModule#schemas).
+
+**default** : `[]`
+
+**example**:
+
+```typescript
+const component = await render(AppComponent, {
+ schemas: [NO_ERRORS_SCHEMA],
+})
+```
+
 ## Directive RenderOptions
 
 To test a directive, the render API is a bit different. The API has the same
@@ -224,23 +224,36 @@ const component = await render(SpoilerDirective, {
 
 ## `RenderResult`
 
-### `...queries`
+### `container`
 
-The most important feature of `render` is that the queries from
-[DOM Testing Library](https://testing-library.com/docs/dom-testing-library) are
-automatically returned with their first argument bound to the component under
-test.
+The containing DOM node of your rendered Angular Component. This is a regular
+DOM node, so you can call `container.querySelector` etc. to inspect the
+children.
 
-See [Queries](https://testing-library.com/docs/dom-testing-library/api-queries)
-for a complete list.
+### `debug`
 
-**example**:
+Prints out the component's DOM with syntax highlighting. Accepts an optional
+parameter, to print out a specific DOM node.
 
 ```typescript
 const component = await render(AppComponent)
 
-component.getByText('Hello world')
-component.queryByLabelText('First name:')
+component.debug()
+component.debug(component.getByRole('alert'))
+```
+
+### `rerender`
+
+Re-render the same component with different props.
+Will call `detectChanges` after props has been updated.
+
+```typescript
+const component = await render(Counter, { componentProperties: { count: 4 }})
+
+expect(component.getByTestId('count-value').textContent).toBe('4')
+
+component.rerender({ count: 7 })
+expect(component.getByTestId('count-value').textContent).toBe('7')
 ```
 
 ### `fireEvent.***`
@@ -268,29 +281,23 @@ component.change(component.getByLabelText('Username'), {
 component.click(component.getByText('Login'))
 ```
 
-### `type`
-
-Types a value in an input field with the same interactions as the user would do.
-
-```typescript
-const component = await render(AppComponent)
-
-component.type(component.getByLabelText('Username'), 'Tim')
-component.type(component.getByLabelText('Username'), 'Tim', { delay: 250 })
-```
+### `fixture`
 
-### `selectOptions`
+The Angular `ComponentFixture` of the component.
 
-Select an option(s) from a select field with the same interactions as the user
-would do.
+For more info see the
+[Angular docs](https://angular.io/api/core/testing/ComponentFixture).
 
 ```typescript
 const component = await render(AppComponent)
 
-component.selectOptions(component.getByLabelText('Fruit'), 'Blueberry')
-component.selectOptions(component.getByLabelText('Fruit'), ['Blueberry'. 'Grape'])
+const componentInstance = component.fixture.componentInstance as AppComponent
 ```
 
+> 🚨 If you find yourself using `fixture` to access the component's internal
+> values you should reconsider! This probable means, you're testing
+> implementation details.
+
 ### `navigate`
 
 Accepts a DOM element or a path as parameter. If an element is passed,
@@ -306,37 +313,65 @@ await component.navigate(component.getByLabelText('To details'))
 await component.navigate('details/3')
 ```
 
-### `fixture`
+### `...queries`
 
-The Angular `ComponentFixture` of the component.
+The most important feature of `render` is that the queries from
+[DOM Testing Library](https://testing-library.com/docs/dom-testing-library) are
+automatically returned with their first argument bound to the component under
+test.
 
-For more info see the
-[Angular docs](https://angular.io/api/core/testing/ComponentFixture).
+See [Queries](https://testing-library.com/docs/dom-testing-library/api-queries)
+for a complete list.
+
+**example**:
 
 ```typescript
 const component = await render(AppComponent)
 
-const componentInstance = component.fixture.componentInstance as AppComponent
+component.getByText('Hello world')
+component.queryByLabelText('First name:')
 ```
 
-> 🚨 If you find yourself using `fixture` to access the component's internal
-> values you should reconsider! This probable means, you're testing
-> implementation details.
+### `selectOptions`
 
-### `container`
+Select an option(s) from a select field with the same interactions as the user
+would do.
 
-The containing DOM node of your rendered Angular Component. This is a regular
-DOM node, so you can call `container.querySelector` etc. to inspect the
-children.
+```typescript
+const component = await render(AppComponent)
 
-### `debug`
+component.selectOptions(component.getByLabelText('Fruit'), 'Blueberry')
+component.selectOptions(component.getByLabelText('Fruit'), ['Blueberry'. 'Grape'])
+```
 
-Prints out the component's DOM with syntax highlighting. Accepts an optional
-parameter, to print out a specific DOM node.
+### `type`
+
+Types a value in an input field with the same interactions as the user would do.
 
 ```typescript
 const component = await render(AppComponent)
 
-component.debug()
-component.debug(component.getByRole('alert'))
+component.type(component.getByLabelText('Username'), 'Tim')
+component.type(component.getByLabelText('Username'), 'Tim', { delay: 250 })
 ```
+
+### `waitForDomChange`
+
+Wait for the DOM to change.
+For more info see the [DOM Testing Library docs](https://testing-library.com/docs/dom-testing-library/api-async#waitfordomchange).
+
+This function will also call `detectChanges` repeatably to update the DOM, is helpful to test async functionality.
+
+### `waitForElement`
+
+Wait for DOM elements to appear, disappear, or change.
+For more info see the [DOM Testing Library docs](https://testing-library.com/docs/dom-testing-library/api-async#waitforelement).
+
+This function will also call `detectChanges` repeatably to update the DOM, is helpful to test async functionality.
+
+### `waitForElementToBeRemoved`
+
+Wait for the removal of element(s) from the DOM.
+For more info see the [DOM Testing Library docs](https://testing-library.com/docs/dom-testing-library/api-async#waitforelementtoberemoved).
+
+This function will also call `detectChanges` repeatably to update the DOM, is helpful to test async functionality.