Skip to content

api.mdx

Latest commit

 

History

History
403 lines (280 loc) · 9.32 KB

api.mdx

File metadata and controls

403 lines (280 loc) · 9.32 KB
id api
title API
sidebar_label API

Angular Testing Library re-exports everything from DOM Testing Library as well as these methods:

Some of the DOM Testing Library re-exports are patched to work easier with Angular:

  • The events on fireEvent automatically invoke a change detection cycle after the event has been fired
  • The findBy queries automatically invoke a change detection cycle before the query is invoked function
  • The waitFor functions automatically invoke a change detection cycle before invoking the callback function

render

async function render<ComponentType>(
  component: Type<ComponentType>,
  renderOptions?: RenderComponentOptions<ComponentType>
): Promise<RenderResult<ComponentType, ComponentType>>
async function render<DirectiveType, WrapperType = WrapperComponent>(
  component: Type<DirectiveType>,
  renderOptions?: RenderDirectiveOptions<DirectiveType, WrapperType>
): Promise<RenderResult<DirectiveType, WrapperType>>

Component RenderOptions

componentProperties

An object to set @Input and @Output properties of the component.

default : {}

example:

const component = await render(AppComponent, {
  componentProperties: {
    counterValue: 10,
    send: (value) => { ... }
  }
})

componentProviders

A collection of providers to inject dependencies of the component.

For more info see the Angular docs.

default : []

example:

const component = await render(AppComponent, {
  componentProviders: [AppComponentService],
})

declarations

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.

default : []

example:

const component = await render(AppComponent, {
  providers: [
    CustomersService,
    {
      provide: MAX_CUSTOMERS_TOKEN,
      useValue: 10,
    },
  ],
})

detectChanges

Will call detectChanges when the component is compiled

default : true

example:

const component = await render(AppComponent, { detectChanges: false })

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:

const component = await render(AppComponent, {
  imports: [AppModule], // a module that includes AppComponent
  excludeComponentDeclaration: true,
})

imports

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.

default : [NoopAnimationsModule]

example:

const component = await render(AppComponent, {
  imports: [AppSharedModule, MaterialModule],
})

queries

Queries to bind. Overrides the default set from DOM Testing Library unless merged.

default : undefined

example:

const component = await render(AppComponent, {
  queries: { ...queries, ...customQueries },
})

routes

The route configuration to set up the router service via RouterTestingModule.withRoutes. For more info see the Angular Routes docs.

default : []

example:

const component = await render(AppComponent, {
  declarations: [ChildComponent],
  routes: [
    {
      path: '',
      children: [
        {
          path: 'child/:id',
          component: ChildComponent,
        },
      ],
    },
  ],
})

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.

default : []

example:

const component = await render(AppComponent, {
  schemas: [NO_ERRORS_SCHEMA],
})

removeAngularAttributes

Removes the Angular attributes (ng-version, and root-id) from the fixture.

default : false

example:

const component = await render(AppComponent, {
  removeAngularAttributes: true,
})

Directive RenderOptions

To test a directive, the render API is a bit different. The API has the same options as the Component RenderOptions, but has more options:

template

The template to render the directive.

example:

const component = await render(SpoilerDirective, {
  template: `<div spoiler message='SPOILER'></div>`,
})

wrapper

An Angular component to wrap the directive in.

default: WrapperComponent , an empty component that strips the ng-version attribute.

example:

const component = await render(SpoilerDirective, {
  template: `<div spoiler message='SPOILER'></div>`
  wrapper: CustomWrapperComponent
})

RenderResult

container

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.

debug

Prints out the component's DOM with syntax highlighting. Accepts an optional parameter, to print out a specific DOM node.

const component = await render(AppComponent)

component.debug()
component.debug(component.getByRole('alert'))

rerender

Re-render the same component with different props. Will call detectChanges after props has been updated.

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.***

The fireEvents re-exported from DOM Testing Library that are automatically bound to the Angular Component. This to ensure that the Angular change detection has been run by invoking detectChanges after an event has been fired.

See Firing Events for a complete list.

example:

const component = await render(AppComponent)

component.change(component.getByLabelText('Username'), {
  target: {
    value: 'Tim',
  },
})
component.click(component.getByText('Login'))

debugElement

The Angular DebugElement of the component.

For more info see the Angular docs.

fixture

The Angular ComponentFixture of the component.

For more info see the Angular docs.

const component = await render(AppComponent)

const componentInstance = component.fixture.componentInstance as AppComponent

:::danger 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, navigate will navigate to the href value of the element. If a path is passed, navigate will navigate to the path.

const component = await render(AppComponent, {
  routes: [...]
})

await component.navigate(component.getByLabelText('To details'))
await component.navigate('details/3')

...queries

The most important feature of render is that the queries from DOM Testing Library are automatically returned with their first argument bound to the component under test.

See Queries for a complete list.

example:

const component = await render(AppComponent)

component.getByText('Hello world')
component.queryByLabelText('First name:')

selectOptions

Select an option(s) from a select field with the same interactions as the user would do.

const component = await render(AppComponent)

component.selectOptions(component.getByLabelText('Fruit'), 'Blueberry')
component.selectOptions(component.getByLabelText('Fruit'), ['Blueberry'. 'Grape'])

type

Types a value in an input field with the same interactions as the user would do.

const component = await render(AppComponent)

component.type(component.getByLabelText('Username'), 'Tim')
component.type(component.getByLabelText('Username'), 'Tim', { delay: 250 })

waitFor

When in need to wait for any period of time you can use waitFor, to wait for your expectations to pass. For more info see the DOM Testing Library docs.

This function will also call detectChanges repeatably to update the DOM, which is helpful to test async functionalities.

waitForElementToBeRemoved

Wait for the removal of element(s) from the DOM. For more info see the DOM Testing Library docs.

This function will also call detectChanges repeatably to update the DOM, which is helpful to test async functionalities.