API

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

• render

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:

await render(AppComponent, {

componentProperties: {

counterValue: 10,

send: (value) => { ... }

}

})

componentProviders

A collection of providers needed to render the component via Dependency Injection.

These will be provided at the component level. To inject dependencies at the module level, use providers.

For more info see the Angular docs.

default : []

example:

await render(AppComponent, {

componentProviders: [AppComponentService],

})

declarations

A collection of components, directives and pipes needed to render the component. For example, nested components of the component.

For more info see the Angular docs.

default : []

example:

await render(AppComponent, {

declarations: [CustomerDetailComponent, ButtonComponent],

})

detectChanges

Will call detectChanges when the component is compiled

default : true

example:

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:

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:

await render(AppComponent, {

imports: [AppSharedModule, MaterialModule],

})

providers

A collection of providers needed to render the component via Dependency Injection.

These will be provided at the module level. To inject dependencies at the component level, use componentProviders.

For more info see the Angular docs.

default : []

example:

await render(AppComponent, {

providers: [

CustomersService,

{

provide: MAX_CUSTOMERS_TOKEN,

useValue: 10,

},

],

})

queries

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

default : undefined

example:

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:

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:

await render(AppComponent, {

schemas: [NO_ERRORS_SCHEMA],

})

removeAngularAttributes

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

default : false

example:

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:

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:

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 { debug } = await render(AppComponent)

debug()

rerender

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

const { rerender } = await render(Counter, {

componentProperties: { count: 4 },

})

expect(screen.getByTestId('count-value').textContent).toBe('4')

rerender({ count: 7 })

expect(screen.getByTestId('count-value').textContent).toBe('7')

detectChanges

Trigger a change detection cycle for the component.

For more info see the Angular docs.

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 { fixture } = await render(AppComponent)

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

const { navigate } = await render(AppComponent, {

routes: [...]

})

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

await 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 { getByText, queryByLabelText } = await render(AppComponent)

getByText('Hello world')

queryByLabelText('First name:')