Migration Pester Should -* → Should-*

Convertir les assertions Pester v5 classiques (Should -Be, espace puis paramètre) vers les nouvelles assertions Pester v6 Should-* (Should-Be, tiret, pas d'espace).

Statut : expérimental / aperçu. Vérifié contre Pester 6.0.0-rc2. Le style classique Should -Be fonctionne toujours en v6, donc migrez progressivement et gardez la suite verte.

Skill compagnon. Ce skill couvre le passage optionnel aux nouveaux opérateurs Should-*. Pour mettre à niveau une suite entre les versions majeures de Pester (v3→v4→v5→v6 — le runtime, les mocks et la config), utilisez le skill séparé pester-migration. En v6 le style classique Should -Be continue de fonctionner, donc adopter Should-* est indépendant de tout changement de version.

Quand l'utiliser

• Moderniser une suite Pester vers les assertions v6 Should-*.
• Un utilisateur demande de migrer / convertir / réécrire les appels Should -....
• Vous voulez des messages d'erreur plus clairs et type-aware des nouvelles assertions.

À savoir avant de commencer

• Les deux syntaxes fonctionnent côte à côte en Pester v6. La migration est optionnelle et peut être faite un test (ou un fichier) à la fois. Rien ne casse si vous laissez du code classique.
• Nécessite Pester v6+. Les commandes Should-* n'existent pas en v5.
• La négation est une commande séparée, pas un switch -Not : Should -Not -Be → Should-NotBe. Il n'y a pas de paramètre -Not sur les nouvelles assertions.
• La valeur actuelle vient toujours du pipeline ($x | Should-Be 1) ou de -Actual (Should-Be -Actual $x -Expected 1). -Because se transmet inchangé.
• La plupart des renommages sont mécaniques, mais plusieurs ont des changements de comportement que vous devez vérifier manuellement — voir Pièges.

Procédure

Étape 1 — Trouver les assertions classiques

Recherchez dans la cible la syntaxe classique séparée par des espaces (l'indicateur est Should -, ou Should suivi de -Not) :

Should -          # n'importe quel opérateur classique
Should -Not -     # opérateur classique nié
Assert-MockCalled # également supprimé en v6 -> Should-Invoke

Limitez la portée aux fichiers de test PowerShell (*.Tests.ps1, *.ps1).

Étape 2 — Appliquer le mapping

Conversions les plus utilisées (liste complète dans references/assertion-map.md) :

Étape 3 — Vérifier les pièges comportementaux (NE PAS sauter)

Ceux-ci ne se traduisent pas par un simple renommage. Lisez chacun avant de convertir :

1. Sensibilité à la casse. Le classique Should -Be est insensible à la casse sur les chaînes ; il en va de même pour Should-Be. Mais le classique Should -BeExactly (sensible à la casse) n'a pas d'équivalent simple — utilisez Should-BeString -CaseSensitive. (Should-Be n'est jamais sensible à la casse.) Le même motif s'applique à BeLikeExactly → Should-BeLikeString -CaseSensitive et MatchExactly → Should-MatchString -CaseSensitive.
2. Truthy vs. true. Le classique Should -BeTrue / -BeFalse accepte toute valeur truthy / falsy (1, 'x', 0, '', $null, @()). Le nouveau Should-BeTrue / Should-BeFalse est strict (exactement $true / $false). Pour préserver l'ancien comportement laxiste utilisez Should-BeTruthy / Should-BeFalsy. N'utilisez les versions strictes que quand la valeur est vraiment un booléen.
3. BeNullOrEmpty n'a pas d'équivalent unique. Choisissez selon l'intention : $null → Should-BeNull; chaîne vide → Should-BeEmptyString; collection vide → Should-BeCollection -Count 0; large « falsy » → Should-BeFalsy. La négation Should -Not -BeNullOrEmpty se divise de manière similaire en Should-NotBeNull / Should-NotBeEmptyString / Should-NotBeWhiteSpaceString.
4. Collections. Le classique Should -Be compare aussi les tableaux ; le nouveau Should-Be est une assertion de valeur et erreur si -Expected est une collection (« You provided a collection to the -Expected parameter »). Utilisez Should-BeCollection pour comparer les tableaux. Should -Contain (appartenance d'un seul élément) → Should-ContainCollection. La nouvelle commande prend aussi une collection d'éléments attendus et vérifie qu'ils sont tous présents, dans le bon ordre (1, 2, 3 | Should-ContainCollection @(1, 2)). Pour l'égalité exacte, utilisez plutôt Should-BeCollection.
5. Dépliage du pipeline. Le pipeline déplie l'entrée : une assertion de valeur voit @(1) comme 1 et @() comme $null, et une collection typée ([int[]]) est recollectée comme [object[]]. Quand la valeur exacte ou le type de collection concret importe (par ex. Should-HaveType), passez-la avec -Actual plutôt que par pipe.
6. *Pas d'équivalent `Should-.**Should -Existet la familleShould -FileContentMatch* n'ont pas de nouveau pendant. Soit gardez l'assertion classique, soit réécrivez avec PowerShell :Test-Path $p | Should-BeTrue,(Get-Content $p -Raw) | Should-MatchString 're'`.
7. Direction de Should -BeIn. Pas de Should-BeIn. Inversez les opérandes : $value | Should -BeIn $collection → $collection | Should-ContainCollection $value (notez l'échange actual/expected), ou gardez la forme classique.

Étape 4 — Vérifier

Exécutez la suite et confirmez qu'elle est toujours verte — les messages nouveaux diffèrent, mais les passages doivent rester des passages :

Invoke-Pester -Path ./tests

Si une assertion convertie échoue nouvellement, re-vérifiez les pièges ci-dessus (le plus souvent #2 truthy/falsy, #3 null-or-empty, ou #4 collections).

Étape 5 — (Optionnel) Enforcer le nouveau style

Une fois qu'une suite est entièrement migrée, désactivez la syntaxe classique pour qu'elle ne puisse pas réapparaître :

$config = New-PesterConfiguration
$config.Should.DisableV5 = $true

Avec ce paramètre, tout Should -Be restant lance une erreur et pointe vers la forme Should-Be.

Output

Récapitulez ce qui a changé : fichiers touchés, nombre d'assertions converties, assertions classiques intentionnellement laissées (par ex. Should -Exist), et conversions qui nécessitent une décision humaine (truthy/falsy, null-or-empty, sémantique des collections).

Référence

• references/assertion-map.md — tableau complet opérateur par opérateur avec exemples avant/après et contournements.
• Référence de commande en direct : https://pester.dev/docs/commands/Should-Be (remplacez Should-Be par n'importe quel nom Should-*) pour les paramètres exacts et les exemples.
• Concepts : https://pester.dev/docs/assertions/should-command (assertions de valeur vs. de collection, pipeline vs. -Actual).
• Guide de mise à niveau v5→v6 : https://pester.dev/docs/migrations/v5-to-v6.