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 test 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 de ressources à l'intérieur d'un test).

Concepts clés

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 (p. ex., « Group Description Test Description »).
  • Aide à délimiter l'utilisation de setUp et tearDown.
  • Nommage : Utilisez PascalCase pour les groupes correspondant à un nom de classe (p. ex., group('MyClient', ...)).
  • Évitez les groupes uniques : N'enveloppez pas tous les tests d'un fichier dans un seul appel group si c'est le seul.
    • REMARQUE : NE SUPPRIMEZ PAS les groupes lors d'un nettoyage de code existant que vous n'avez pas créé, sauf si explicitement demandé. Cela peut causer BEAUCOUP de changements dans le DIFF que la plupart des ingénieurs ne voudront pas !

• Nommer les tests test('test name here', :

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

• Placement des paramètres nommés :

  • Pour les appels test et group, placez les paramètres nommés (p. ex., testOn, timeout, skip) immédiatement après la chaîne de description, avant la closure de rappel. Cela améliore la lisibilité en gardant la logique de test à la fin.

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

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

• setUp : S'exécute avant chaque test du group actuel (et des groupes imbriqués).
• tearDown : S'exécute après chaque test du 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.

Bonne pratique :

• Utilisez setUp pour réinitialiser l'état afin d'assurer l'isolation des tests.
• Évitez de partager un é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 le test runner. Les configurations courantes incluent :

Platforms

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

platforms:
  - vm
  - chrome

Tags

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 tags : dart test --tags integration

Timeouts

Définissez des timeouts 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 le test runner.
• 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 associées

dart-test-fundamentals est la compétence fondamentale pour structurer et configurer les tests. Pour écrire des assertions au sein de ces tests, reportez-vous à :

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