Migration Dart Checks

Quand utiliser cette compétence

Utilisez cette compétence quand :

Vous migrez des fichiers de test existants de package:matcher vers package:checks.
Un utilisateur demande spécifiquement des "modern checks" ou similaire.

Analyse :
- Utilisez grep pour identifier les fichiers utilisant expect ou package:matcher.
- Passez en revue les matchers personnalisés ; ceux-ci peuvent nécessiter une migration manuelle.
Outils et dépendances :
- Assurez-vous que dev_dependencies inclut checks.
- Exécutez dart pub add --dev checks si manquant.
Découverte :
- Utilisez les Stratégies de découverte ci-dessous pour trouver les candidats.
Remplacement :
- Ajoutez import 'package:checks/checks.dart';.
- Appliquez les Motifs courants ci-dessous.
- Étape finale : Remplacez import 'package:test/test.dart'; par import 'package:test/scaffolding.dart'; UNIQUEMENT après que tous les appels expect soient remplacés. Cela assure une progression incrémentale.
Vérification :
- Assurez-vous que le code s'analyse correctement.
- Assurez-vous que les tests passent.

Pour trouver des candidats à la migration, utilisez les stratégies de recherche suivantes :

Recherchez des fichiers de test qui importent package:test/test.dart ou utilisent expect :

Recherchez des matchers spécifiques qui sont faciles à migrer :

`expect` hérité	`check` moderne
`expect(a, equals(b))`	`check(a).equals(b)`
`expect(a, isTrue)`	`check(a).isTrue()`
`expect(a, isFalse)`	`check(a).isFalse()`
`expect(a, isNull)`	`check(a).isNull()`
`expect(a, isNotNull)`	`check(a).isNotNull()`
`expect(() => fn(), throwsA<T>())`	`check(() => fn()).throws<T>()`
`expect(list, hasLength(n))`	`check(list).length.equals(n)`
`expect(a, closeTo(b, delta))`	`check(a).isA<num>().isCloseTo(b, delta)`
`expect(a, greaterThan(b))`	`check(a).isGreaterThan(b)`
`expect(a, lessThan(b))`	`check(a).isLessThan(b)`
`expect(list, isEmpty)`	`check(list).isEmpty()`
`expect(list, isNotEmpty)`	`check(list).isNotEmpty()`
`expect(list, contains(item))`	`check(list).contains(item)`
`expect(map, equals(otherMap))`	`check(map).deepEquals(otherMap)`
`expect(list, equals(otherList))`	`check(list).deepEquals(otherList)`
`expect(future, completes)`	`await check(future).completes()`
`expect(stream, emitsInOrder(...))`	`await check(stream).withQueue.inOrder(...)`

Vérifier les fonctions async : check(() => asyncFunc()).throws<T>() cause des FAUX POSITIFS car la fermeture retourne une Future, qui est une valeur, donc elle "se termine normalement" (en tant que Future). Utilisation correcte :
```
await check(asyncFunc()).throws<T>();
```
Chaînage sur les retours void : De nombreuses méthodes check async (comme throws) retournent Future<void>. Vous ne pouvez pas les chaîner directement. Utilisez des cascades ou des callbacks. Incorrect :
```
await check(future)
    .throws<Error>()
    .has((e) => e.message, 'message')
    .equals('foo');
```
Correct :
```
await check(future).throws<Error>(
    (it) => it.has((e) => e.message, 'message').equals('foo'));
```

Vérification approfondie avec isA et having :

Hérité :

expect(() => foo(), throwsA(isA<ArgumentError>()
    .having((e) => e.message, 'message', contains('MSG'))));

Moderne :

check(() => foo())
    .throws<ArgumentError>()
    .has((e) => e.message, 'message')
    .contains('MSG');

Extraction de propriété :

Hérité :

expect(obj.prop, equals(value)); // Lors de la vérification de plusieurs propriétés

Moderne :

check(obj)
  ..has((e) => e.prop, 'prop').equals(value)
  ..has((e) => e.other, 'other').equals(otherValue);

Cascades d'une ligne : Puisque les checks retournent souvent void, utilisez des cascades pour plusieurs assertions sur le même sujet.

check(it)..isGreaterThan(10)..isLessThan(20);

Portée : Ne modifiez que les fichiers dans test/ (et pubspec.yaml).
Exactitude : Un test échouant est inacceptable. Si un test échoue après la migration et que vous ne pouvez pas le corriger immédiatement, ANNULEZ ce changement spécifique.
Sécurité des types : package:checks est plus strict sur les types que matcher. Vous devrez peut-être ajouter des casts as T explicites ou des vérifications isA<T>() dans la chaîne.

dart-test-fundamentals : Concepts clés pour structurer les tests, les cycles de vie et la configuration.
dart-matcher-best-practices : Bonnes pratiques pour le package:matcher traditionnel qui est en cours de migration.