Fondamentaux des tests Dart

Quand utiliser cette compétence

Utilisez cette compétence quand :

• Vous écrivez de nouveaux fichiers de test.
• Vous structurez des suites de tests avec group.
• Vous configurez l'exécution des tests via dart_test.yaml.
• Vous comprenez les méthodes du cycle de vie des tests.

Découverte

Pour trouver des candidats à l'amélioration de la structure des tests :

Nettoyage avec try-finally

Recherchez les tests qui utilisent try-finally pour le nettoyage au lieu de addTearDown :

• Regex : \bfinally\s*\{ (Vérifiez si cela est utilisé pour le nettoyage des ressources à l'intérieur d'un test).

Concepts fondamentaux

1. Structure des tests (test et group)

• test : L'unité fondamentale des tests.

  test('description', () {
    // assertions
  });

• group : Utilisé pour organiser les tests en blocs logiques.

  • Les groupes peuvent être imbriqués.
  • Les descriptions sont concaténées (par ex., « Group Description Test Description »).
  • Aide à délimiter la portée des appels setUp et tearDown.
  • Nommage : Utilisez PascalCase pour les groupes qui correspondent à un nom de classe (par ex., group('MyClient', ...)).
  • Évitez les groupes uniques : N'enveloppez pas tous les tests d'un fichier dans un seul appel group s'il est le seul.
    • REMARQUE : NE PAS supprimer les groupes lors d'un nettoyage sur du code existant que vous n'avez pas créé, sauf si cela vous est explicitement demandé. Cela peut causer BEAUCOUP de churn dans le DIFF que la plupart des développeurs ne souhaitent pas !

• Nommage des tests test('test name here', :

  • Évitez les préfixes « test » redondants. Utilisez group à la place.
  • Incluez le comportement attendu ou le résultat dans la description (par ex., 'throws StateError' ou 'adds API key to URL').
  • Les descriptions doivent bien se lire lorsqu'elles sont concaténées avec leur nom de groupe.

• Placement des paramètres nommés :

  • Pour les appels test et group, placez les paramètres nommés (par ex., testOn, timeout, skip) immédiatement après la chaîne de description, avant la fermeture du callback. Cela améliore la lisibilité en gardant la logique du test en dernier.

    test('description', testOn: 'vm', () {
      // assertions
    });

2. Méthodes du cycle de vie (setUp, tearDown)

• setUp : S'exécute avant chaque test dans le group actuel (et les groupes imbriqués).
• tearDown : S'exécute après chaque test dans le group actuel.
• setUpAll : S'exécute une fois avant tout test du groupe.
• tearDownAll : S'exécute une fois après tous les tests du groupe.

Meilleure pratique :

• Utilisez setUp pour réinitialiser l'état afin d'assurer l'isolement des tests.
• Évitez de partager l'état mutable entre les tests sans le réinitialiser.

3. Nettoyage des ressources

• Pour nettoyer les ressources créées À L'INTÉRIEUR du corps du test, envisagez d'utiliser addTearDown au lieu d'un bloc try-finally.

À éviter :

test('can create and delete a file', () {
  final file = File('temp.txt');
  try {
    file.writeAsStringSync('hello');
    expect(file.readAsStringSync(), 'hello');
  } finally {
    if (file.existsSync()) file.deleteSync();
  }
});

À préférer :

test('can create and delete a file', () {
  final file = File('temp.txt');
  // Register teardown immediately after resource creation intent
  addTearDown(() {
    if (file.existsSync()) file.deleteSync();
  });

  file.writeAsStringSync('hello');
  expect(file.readAsStringSync(), 'hello');
});

4. Configuration (dart_test.yaml)

Le fichier dart_test.yaml configure l'exécuteur de tests. Les configurations courantes incluent :

Plateformes

Définissez où les tests s'exécutent (vm, chrome, node).

platforms:
  - vm
  - chrome

Balises

Catégorisez les tests pour exécuter des sous-ensembles spécifiques.

tags:
  integration:
    timeout: 2x

Utilisation dans le code :

@Tags(['integration'])
import 'package:test/test.dart';

Exécution des balises : dart test --tags integration

Délais d'expiration

Définissez les délais d'expiration par défaut pour les tests.

timeouts:
  2x # Double the default timeout

5. Nommage des fichiers

• Les fichiers de test doivent se terminer par _test.dart pour être détectés par l'exécuteur de tests.
• Placez les tests dans le répertoire test/.

Commandes courantes

• dart test : Exécutez tous les tests.
• dart test test/path/to/file_test.dart : Exécutez un fichier spécifique.
• dart test --name "substring" : Exécutez les tests correspondant à une description.

Compétences connexes

dart-test-fundamentals est la compétence principale pour structurer et configurer les tests. Pour écrire les assertions au sein de ces tests, consultez :

• dart-matcher-best-practices : Utilisez cela si le projet s'en tient au traditionnel package:matcher (appels expect).
• dart-checks-migration : Utilisez cela si le projet migre vers le moderne package:checks (appels check).