Aller au contenu principal

Débogage

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

Journalisation automatique​

Lorsque des appels get ou find échouent dans vos tests, l'état actuel du container (DOM) est affiché dans la console. Par exemple :

// <div>Hello world</div>
getByText(container, 'Goodbye world') // will fail by throwing error

Le test ci-dessus échouera, mais il affichera l'état du DOM testé, ce qui vous permettra de voir :

Unable to find an element with the text: Goodbye world. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.
Here is the state of your container:
<div>
  <div>
    Hello world
  </div>
</div>

Remarque : Comme le DOM peut devenir très volumineux, vous pouvez limiter le contenu imprimé via la variable d'environnement DEBUG_PRINT_LIMIT. La valeur par défaut est 7000. Vous verrez ... dans la console lorsque le contenu DOM est tronqué, soit à cause de votre limite personnalisée soit à cause de la limite par défaut. Pour augmenter cette limite lors de l'exécution des tests :

DEBUG_PRINT_LIMIT=10000 npm test

Cette solution fonctionne sur macOS/Linux. Pour Windows, une autre approche est nécessaire. Pour une solution multiplateforme, consultez cross-env.

Remarque : La sortie du DOM est colorisée par défaut dans un environnement Node. Cependant, vous pourriez vouloir désactiver les couleurs, par exemple lorsque la sortie est enregistrée dans un fichier journal. Utilisez la variable d'environnement COLORS pour forcer manuellement la colorisation :

COLORS=false npm test

Cette solution fonctionne sur macOS/Linux. Pour Windows, une autre approche est nécessaire. Pour une solution multiplateforme, consultez cross-env.

prettyDOM​

Basée sur pretty-format, cette fonction utilitaire permet d'imprimer une représentation lisible de l'arborescence DOM d'un nœud. Elle s'avère particulièrement utile lors du débogage de tests.

Définition :

interface Options extends prettyFormat.OptionsReceived {
  filterNode?: (node: Node) => boolean
}

function prettyDOM(
  node: HTMLElement,
  maxLength?: number,
  options?: Options,
): string

Elle prend en paramètre le nœud racine à afficher, un paramètre optionnel supplémentaire pour limiter la taille de la chaîne résultante (lorsqu'elle devient trop volumineuse). Un dernier paramètre permet de configurer le formatage. En plus des options listées, vous pouvez également transmettre les options de pretty-format.

Par défaut, les nœuds <style />, <script /> et les commentaires sont ignorés. Configurez ce comportement avec une fonction filterNode personnalisée qui renvoie true pour les nœuds à inclure.

Utilisée avec console.log pour imprimer temporairement des arborescences DOM pendant les tests :

import {prettyDOM} from '@testing-library/dom'

const div = document.createElement('div')
div.innerHTML = '<div><h1>Hello World</h1></div>'
console.log(prettyDOM(div))
// <div>
//   <h1>Hello World</h1>
// </div>

Cette fonction alimente également la sortie de débogage automatique décrite précédemment.

screen.debug()​

Par commodité, screen expose une méthode debug. C'est un raccourci pour console.log(prettyDOM()). Elle permet de déboguer le document, un élément unique ou un tableau d'éléments.

import {screen} from '@testing-library/dom'

document.body.innerHTML = `
  <button>test</button>
  <span>multi-test</span>
  <div>multi-test</div>
`

// debug document
screen.debug()
// debug single element
screen.debug(screen.getByText('test'))
// debug multiple elements
screen.debug(screen.getAllByText('multi-test'))

screen.logTestingPlaygroundURL()​

Pour déboguer avec testing-playground, screen expose cette méthode pratique qui journalise et renvoie une URL pouvant être ouverte dans un navigateur.

import {screen} from '@testing-library/dom'

document.body.innerHTML = `
  <button>test</button>
  <span>multi-test</span>
  <div>multi-test</div>
`

// log entire document to testing-playground
screen.logTestingPlaygroundURL()
// log a single element
screen.logTestingPlaygroundURL(screen.getByText('test'))

logRoles​

Cette fonction utilitaire imprime tous les rôles ARIA implicites dans une arborescence DOM, chaque rôle listant les nœuds correspondants. Utile pour identifier comment interroger le DOM avec getByRole.

import {logRoles} from '@testing-library/dom'

const nav = document.createElement('nav')
nav.innerHTML = `
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>`

logRoles(nav)

Résultat :

navigation:
<nav />
--------------------------------------------------
list:
<ul />
--------------------------------------------------
listitem:
<li />
<li />
--------------------------------------------------