Aller au contenu principal

API

[Traduction Bêta Non Officielle]

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Angular Testing Library réexporte tous les éléments de DOM Testing Library ainsi que la méthode render.

Les réexportations suivantes ont été adaptées pour une utilisation simplifiée avec Angular :

  • Les événements de fireEvent déclenchent automatiquement un cycle de détection des changements après l'émission de l'événement

  • Les requêtes findBy déclenchent automatiquement un cycle de détection des changements avant l'appel de la fonction

  • Les fonctions waitFor déclenchent automatiquement un cycle de détection des changements avant d'invoquer la fonction de rappel

render​

Avec Angular Testing Library, le composant peut être rendu de deux manières : via son type ou avec un template.

Par défaut, render importe également le NoopAnimationsModule.

Type​

Pour rendre un composant, vous devez passer son type à la méthode render. Pour les composants n'utilisant pas d'autres parties de votre application (comme des modules de design ou des services), le rendu peut être aussi simple que dans l'exemple suivant.

await render(AppComponent)

template​

Au lieu de passer le type du composant comme premier argument, vous pouvez également fournir un template. Cette pratique est nécessaire pour rendre des directives, mais peut aussi s'appliquer aux composants, et peut même s'avérer plus utile. Le type de la directive (ou du composant) doit alors être ajouté aux imports (ou aux declarations pour les composants non autonomes).

exemple avec une directive :

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

exemple avec un composant :

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

Options de rendu des composants​

inputs​

Un objet pour définir les propriétés @Input ou input() du composant.

valeur par défaut : {}

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

on​

Un objet contenant des fonctions de rappel pour s'abonner aux EventEmitters et Observables du composant.

valeur par défaut : {}

// 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​

Un tableau de liaisons à appliquer au composant via l'API native de liaisons d'Angular. Cette approche offre un moyen plus direct de lier les entrées et sorties comparé aux options inputs et on. L'API de liaisons utilise les fonctions inputBinding, outputBinding et twoWayBinding de @angular/core.

Par défaut : []

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)),
  ],
})

Utilisation des signaux pour des mises à jour réactives :

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')

Gestion des sorties :

const submitHandler = jest.fn()

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

declarations​

Un ensemble de composants, directives et pipes nécessaires au rendu du composant. Par exemple, les composants imbriqués.

Pour plus d'informations, consultez la documentation Angular.

Par défaut : []

exemple:

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

deferBlockBehavior​

Définit le comportement des blocs différés.

Pour plus d'informations, consultez la documentation Angular.

valeur par défaut : undefined (utilise DeferBlockBehavior.Manual, ce qui diffère du comportement Angular par défaut DeferBlockBehavior.Playthrough)

exemple:

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

deferBlockStates​

Définit l'état initial des blocs différés dans un composant.

Pour plus d'informations, consultez la documentation Angular.

valeur par défaut : undefined (utilise le comportement Angular par défaut : DeferBlockState.Placeholder)

exemple:

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

componentProviders​

Collection de fournisseurs nécessaires au rendu du composant via l'injection de dépendances.

Ils seront fournis au niveau du composant. Pour injecter des dépendances au niveau du module, utilisez providers.

Pour plus d'informations, consultez la documentation Angular.

Par défaut : []

exemple:

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

componentImports​

Collection d'imports pour remplacer les imports d'un composant autonome.

Par défaut : undefined

exemple:

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

childComponentOverrides​

Collection de fournisseurs spécifiques à des composants enfants à remplacer.

Par défaut : undefined

exemple:

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

detectChangesOnRender​

Invoque detectChanges après le rendu du composant.

Par défaut : true

exemple:

await render(AppComponent, {detectChangesOnRender: false})

autoDetectChanges​

Détecte automatiquement les changements comme le ferait un composant en fonctionnement réel. Par exemple, déclenche un cycle de détection des changements après un événement.

Par défaut : true

exemple:

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

excludeComponentDeclaration​

Exclut le composant de la déclaration automatique. Nécessaire lorsque le composant est déclaré dans un module importé, par exemple avec les SCAM.

Par défaut : false

exemple:

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

imports​

Collection d'imports nécessaires au rendu du composant (ex: modules partagés). Ajoute NoopAnimationsModule par défaut si BrowserAnimationsModule n'est pas inclus.

Pour plus d'informations, consultez la documentation Angular.

Par défaut : [NoopAnimationsModule]

exemple:

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

providers​

Collection de fournisseurs nécessaires au rendu du composant via l'injection de dépendances.

Ils seront fournis au niveau du module. Pour injecter des dépendances au niveau du composant, utilisez componentProviders.

Pour plus d'informations, consultez la documentation Angular.

Par défaut : []

exemple:

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

queries​

Requêtes à lier. Remplace l'ensemble par défaut de DOM Testing Library sauf fusion.

Par défaut : undefined

exemple:

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

routes​

La configuration de route pour paramétrer le service de routeur via RouterTestingModule.withRoutes. Pour plus d'informations, consultez la documentation sur les routes Angular.

Par défaut : []

exemple:

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

schemas​

Collection de schémas nécessaires au rendu du composant. Valeurs autorisées : NO_ERRORS_SCHEMA et CUSTOM_ELEMENTS_SCHEMA.

Pour plus d'informations, consultez la documentation Angular.

Par défaut : []

exemple:

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

removeAngularAttributes​

Supprime les attributs Angular (ng-version et root-id) du fixture.

Par défaut : false

exemple:

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

componentInputs (obsolète)​

Objet pour définir les propriétés @Input du composant. Utilise setInput pour définir la propriété. Lance une erreur si la propriété du composant n'est pas annotée avec l'attribut @Input.

valeur par défaut : {}

exemple:

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

componentOutputs (obsolète)​

Un objet pour définir les propriétés @Output du composant.

valeur par défaut : {}

exemple:

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

componentProperties (obsolète)​

Un objet pour définir les propriétés @Input et @Output du composant. Ne permet pas un contrôle aussi précis que inputs et on.

valeur par défaut : {}

exemple:

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

RenderResult​

container​

Le nœud DOM contenant votre composant Angular rendu. Il s'agit d'un nœud DOM standard, vous pouvez donc utiliser container.querySelector etc. pour inspecter les éléments enfants.

debug​

Affiche le DOM du composant avec coloration syntaxique. Accepte un paramètre optionnel pour afficher un nœud DOM spécifique.

const {debug} = await render(AppComponent)

debug()

rerender​

Modifie les propriétés d'entrée de l'instance existante du composant en suivant le cycle de vie Angular (i.e. ngOnChanges est appelé). Les propriétés non définies sont réinitialisées.

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()

Avec partialUpdate, seules les nouvelles propriétés fournies seront mises à jour. Les autres propriétés d'entrée non fournies ne seront pas réinitialisées.

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​

Déclenche un cycle de détection de changement pour le composant.

Pour plus d'informations, consultez la documentation Angular.

debugElement​

Le DebugElement Angular du composant.

Pour plus d'informations, consultez la documentation Angular.

fixture​

Le ComponentFixture Angular du composant.

Pour plus d'informations, consultez la documentation Angular.

const {fixture} = await render(AppComponent)

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

🚨 Si vous utilisez fixture pour accéder aux valeurs internes du composant, reconsidérez votre approche ! Cela signifie probablement que vous testez des détails d'implémentation.

Accepte un élément DOM ou un chemin comme paramètre. Si un élément est passé, navigate accédera à la valeur href de l'élément. Si un chemin est passé, navigate accédera directement au chemin.

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

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

...queries​

La fonctionnalité principale de render est que les requêtes de la DOM Testing Library sont automatiquement retournées avec leur premier argument lié au composant testé.

Voir Requêtes pour une liste complète.

exemple:

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

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

renderDeferBlock​

Pour tester les vues différées, vous pouvez utiliser renderDeferBlock. renderDeferBlock définit l'état différé souhaité pour un bloc spécifique. L'état initial par défaut est Placeholder, mais vous pouvez aussi définir l'état initial lors du rendu du composant.

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

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

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