Ir para o conteúdo principal

API

[Tradução Beta Não Oficial]

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

A Angular Testing Library reexporta tudo da DOM Testing Library junto com o método render.

As seguintes reexportações são adaptadas para facilitar o uso com Angular:

  • Os eventos no fireEvent automaticamente disparam um ciclo de detecção de mudanças após o evento ser executado

  • As queries findBy automaticamente disparam um ciclo de detecção de mudanças antes da função de query ser invocada

  • As funções waitFor automaticamente disparam um ciclo de detecção de mudanças antes de invocar a função callback

render​

Com a Angular Testing Library, o componente pode ser renderizado de duas formas: via tipo do componente ou com um template.

Por padrão, render também importa o NoopAnimationsModule.

Type​

Para renderizar um componente, você precisa passar seu tipo para o método render. Para componentes que não usam outras partes da aplicação (como módulos de design ou serviços), a renderização pode ser simples como no exemplo:

await render(AppComponent)

template​

Em vez de passar o tipo do componente como primeiro argumento, você pode fornecer um template. Essa abordagem é obrigatória para renderizar diretivas mas também pode ser aplicada a componentes, sendo até mais útil. O tipo da diretiva (ou componente) deve então ser adicionado aos imports (ou declarations para componentes não standalone).

exemplo com diretiva:

await render('<div appSpoiler></div>', {
  declarations: [SpoilerDirective],
})

exemplo com componente:

await render(
  '<app-component [value]="47" [otherValue]="anotherValue" (sendValue)="sendValue($event)"></app-component>',
  {
    declarations: [AppComponent],
    componentProperties: {
      anotherValue: 'valueOfAnotherProperty',
      sendValue: jest.fn(),
    },
  },
)
export async function render<ComponentType>(
  component: Type<ComponentType>,
  renderOptions?: RenderComponentOptions<ComponentType>,
): Promise<RenderResult<ComponentType, ComponentType>>
export async function render<WrapperType = WrapperComponent>(
  template: string,
  renderOptions?: RenderTemplateOptions<WrapperType>,
): Promise<RenderResult<WrapperType>>

Component RenderOptions​

inputs​

Um objeto para definir propriedades @Input ou input() do componente.

padrão : {}

await render(AppComponent, {
  inputs: {
    counterValue: 10,
    // explicitly define aliases using `aliasedInput`
    ...aliasedInput('someAlias', 'someValue'),
  },
})

on​

Um objeto com callbacks para inscrever-se em EventEmitters e Observables do componente.

padrão : {}

// using a manual callback
const sendValue = (value) => { ... }
await render(AppComponent, {
  on: {
    send: (value) => sendValue(value),
  }
})

// using a (jest) spy
const sendValueSpy = jest.fn()

await render(AppComponent, {
  on: {
    send: sendValueSpy
  }
})

bindings​

Um array de bindings para aplicar ao componente usando a API nativa de bindings do Angular. Essa abordagem oferece uma forma mais direta de vincular inputs e outputs comparada às opções inputs e on. A API de bindings utiliza as funções inputBinding, outputBinding e twoWayBinding do @angular/core.

padrão: []

import { inputBinding, outputBinding, twoWayBinding, signal } from '@angular/core'

await render(AppComponent, {
  bindings: [
    // Bind a static input value
    inputBinding('greeting', () => 'Hello'),
    
    // Bind a signal as an input
    inputBinding('age', () => 25),
    
    // Two-way binding with a signal
    twoWayBinding('name', signal('John')),
    
    // Output binding with a callback
    outputBinding('submitValue', (event) => console.log(event)),
  ],
})

Usando signals para atualizações reativas:

const greetingSignal = signal('Good day')
const nameSignal = signal('David')
const ageSignal = signal(35)

const { fixture } = await render(AppComponent, {
  bindings: [
    inputBinding('greeting', greetingSignal),
    inputBinding('age', ageSignal),
    twoWayBinding('name', nameSignal),
  ],
})

// Update signals externally
greetingSignal.set('Good evening')

Tratando outputs:

const submitHandler = jest.fn()

await render(AppComponent, {
  bindings: [
    outputBinding('submit', submitHandler),
  ],
})

declarations​

Coleção de componentes, diretivas e pipes necessários para renderizar o componente, como componentes aninhados.

Para mais informações, consulte a documentação do Angular.

padrão: []

exemplo:

await render(AppComponent, {
  declarations: [CustomerDetailComponent, ButtonComponent],
})

deferBlockBehavior​

Define o comportamento dos blocos defer.

Para mais informações, consulte a documentação do Angular

padrão : undefined (usa DeferBlockBehavior.Manual, que difere do padrão do Angular DeferBlockBehavior.Playthrough)

exemplo:

await render(AppComponent, {
  deferBlockBehavior: DeferBlockBehavior.Playthrough,
})

deferBlockStates​

Define o estado inicial de blocos deferíveis em um componente.

Para mais informações, consulte a documentação do Angular

padrão : undefined (usa o padrão do Angular, DeferBlockState.Placeholder)

exemplo:

await render(FixtureComponent, {
  deferBlockStates: DeferBlockState.Loading,
})

componentProviders​

Coleção de providers necessários para renderizar o componente via Injeção de Dependência.

Estes serão fornecidos no nível do componente. Para injetar dependências no nível do módulo, use providers.

Para mais informações, consulte a documentação do Angular.

padrão: []

exemplo:

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

componentImports​

Coleção de imports para sobrescrever os imports de um componente standalone.

padrão: undefined

exemplo:

await render(AppComponent, {
  componentImports: [MockChildComponent],
})

childComponentOverrides​

Coleção de providers especificados de componentes filhos para sobrescrever.

padrão: undefined

exemplo:

await render(AppComponent, {
  childComponentOverrides: [
    {
      component: ChildOfAppComponent,
      providers: [{provide: ChildService, useValue: {hello: 'world'}}],
    },
  ],
})

detectChangesOnRender​

Invoca detectChanges após o componente ser renderizado.

padrão: true

exemplo:

await render(AppComponent, {detectChangesOnRender: false})

autoDetectChanges​

Detecta automaticamente mudanças como um componente em execução "real" faria, por exemplo, executando um ciclo de detecção de mudanças quando um evento ocorre.

padrão: true

exemplo:

await render(AppComponent, {
  autoDetectChanges: false,
})

excludeComponentDeclaration​

Exclui o componente para que não seja automaticamente adicionado como declaração. Necessário quando o componente é declarado em um módulo importado, como em SCAMs.

padrão: false

exemplo:

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

imports​

Coleção de imports necessários para renderizar o componente, como módulos compartilhados. Adiciona NoopAnimationsModule por padrão se BrowserAnimationsModule não estiver na coleção.

Para mais informações, consulte a documentação do Angular.

padrão: [NoopAnimationsModule]

exemplo:

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

providers​

Coleção de providers necessários para renderizar o componente via Injeção de Dependência.

Serão fornecidos no nível do módulo. Para injetar dependências no nível do componente, use componentProviders.

Para mais informações, consulte a documentação do Angular.

padrão: []

exemplo:

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

queries​

Consultas (queries) para vincular. Substitui o conjunto padrão da DOM Testing Library, a menos que mesclado.

padrão: undefined

exemplo:

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

routes​

Configuração de rotas para configurar o serviço de roteamento via RouterTestingModule.withRoutes. Para mais informações, consulte a documentação de Rotas do Angular.

padrão: []

exemplo:

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

schemas​

Coleção de schemas necessários para renderizar o componente. Valores permitidos: NO_ERRORS_SCHEMA e CUSTOM_ELEMENTS_SCHEMA.

Para mais informações, consulte a documentação do Angular.

padrão: []

exemplo:

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

removeAngularAttributes​

Remove atributos do Angular (ng-version e root-id) do fixture.

padrão: false

exemplo:

await render(AppComponent, {
  removeAngularAttributes: true,
})

componentInputs (descontinuado)​

Um objeto para definir propriedades @Input do componente. Utiliza setInput para atribuir o valor da propriedade de entrada. Lança um erro se a propriedade do componente não estiver anotada com o atributo @Input.

padrão : {}

exemplo:

await render(AppComponent, {
  componentInputs: {
    counterValue: 10,
  },
})

componentOutputs (obsoleto)​

Um objeto para definir propriedades @Output do componente.

padrão : {}

exemplo:

await render(AppComponent, {
  componentOutputs: {
    clicked: (value) => { ... }
  }
})

componentProperties (obsoleto)​

Um objeto para definir propriedades @Input e @Output do componente. Não oferece o mesmo controle refinado que inputs e on.

padrão : {}

exemplo:

await render(AppComponent, {
  componentProperties: {
    // an input
    counterValue: 10,
    // an output
    send: (value) => { ... }
    // a public property
    name: 'Tim'
  }
})

RenderResult​

container​

O nó DOM que contém seu Componente Angular renderizado. É um nó DOM comum, permitindo chamar container.querySelector etc. para inspecionar os elementos filhos.

debug​

Exibe o DOM do componente com destaque de sintaxe. Aceita um parâmetro opcional para exibir um nó DOM específico.

const {debug} = await render(AppComponent)

debug()

rerender​

Altera as propriedades de entrada da instância existente do componente seguindo o ciclo de vida de componentes Angular (ou seja, ngOnChanges é chamado). Propriedades de entrada não definidas são limpas.

const {rerender} = await render(Counter, {
  inputs: {count: 4, name: 'Sarah'},
})

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

await rerender({
  inputs: {count: 7}
})

// count is updated to 7
expect(screen.getByTestId('count-value').textContent).toBe('7')
// name is undefined because it's not provided in rerender
expect(screen.getByTestId('name-value').textContent).toBeUndefined()

Usando partialUpdate, apenas as propriedades recém-fornecidas serão atualizadas. Outras propriedades de entrada não fornecidas não serão limpas.

const {rerender} = await render(Counter, {
  inputs: {count: 4, name: 'Sarah'},
})

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

await rerender({inputs: {count: 7}, partialUpdate: true})

// count is updated to 7
expect(screen.getByTestId('count-value').textContent).toBe('7')
// name is still rendered as "Sarah" because of the partial update
expect(screen.getByTestId('name-value').textContent).toBe('Sarah')

detectChanges​

Dispara um ciclo de detecção de alterações para o componente.

Para mais informações, consulte a documentação Angular.

debugElement​

O DebugElement Angular do componente.

Para mais informações, consulte a documentação Angular.

fixture​

O ComponentFixture Angular do componente.

Para mais informações, consulte a documentação Angular.

const {fixture} = await render(AppComponent)

// componentInstance is typed as AppComponent
const componentInstance = fixture.componentInstance

🚨 Se você se pegar usando fixture para acessar valores internos do componente, reconsidere! Isso provavelmente significa que você está testando detalhes de implementação.

Aceita um elemento DOM ou um caminho como parâmetro. Se um elemento for passado, navigate navegará para o valor href do elemento. Se um caminho for passado, navigate navegará para esse caminho.

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

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

...queries​

A funcionalidade mais importante do render é que as queries do DOM Testing Library são automaticamente retornadas com seu primeiro argumento vinculado ao componente sendo testado.

Veja Queries para a lista completa.

exemplo:

const {getByText, queryByLabelText} = await render(AppComponent)

screen.getByRole('heading', {
  name: /api/i,
})
queryByLabelText(/First name/i')

renderDeferBlock​

Para testar visualizações diferíveis, você pode usar renderDeferBlock. renderDeferBlock define o estado diferível desejado para um bloco específico. O valor padrão de uma visualização diferível é Placeholder, mas você também pode definir o estado inicial durante a renderização do componente.

const {renderDeferBlock} = await render(FixtureComponent, {
  deferBlockStates: DeferBlockState.Loading,
})

expect(screen.getByText(/loading/i)).toBeInTheDocument()

await renderDeferBlock(DeferBlockState.Complete)
expect(screen.getByText(/completed/i)).toBeInTheDocument()