Migration Pester

Expérimental / aperçu. Les conseils v5→v6 suivent Pester 6 alors qu'il est en release candidate et peuvent changer ; vérifiez par rapport aux notes de version actuelles. v3→v4 et v4→v5 couvrent les versions stables.

Pester est le framework de test pour PowerShell. Les fichiers de test se terminent par *.Tests.ps1 et utilisent des blocs Describe / Context / It avec des assertions Should. Cette skill met à niveau une suite de tests existante d'une version majeure à la suivante et la rend à nouveau verte.

Modèle mental : chaque saut majeur a un caractère différent. v3→v4 est surtout un renommage de syntaxe. v4→v5 est un changement de runtime fondamental (la division Discovery/Run) et c'est le difficile. v5→v6 est largement rétrocompatible — quelques éléments précédemment dépréciés lèvent maintenant une erreur. Migrez un majeur à la fois ; ne sautez jamais une version.

Des guides détaillés et basés sur les symptômes se trouvent dans references/ — chargez celui (ou ceux) correspondant au saut que vous faites.

Références

Source canonique : les guides de migration officiels sur https://pester.dev/docs/migrations/ — cette skill les reflète. En cas de doute, préférez le site web.

Étape 0 — Déterminez où vous êtes et où vous allez

Trouvez la ou les version(s) installée(s) et la version pour laquelle les tests ont été écrits. Elles peuvent être différentes.

# Version(s) installée(s) de Pester sur cette machine
Get-Module Pester -ListAvailable | Select-Object Name, Version, Path

# Version actuellement importée dans la session
(Get-Module Pester).Version

Déterminez la version source à partir du code de test avec ces heuristiques :

Installez la version cible quand vous êtes prêt :

# Dernière v5 stable — épinglez le majeur pour que ceci continue d'installer v5 même après la GA de v6
Install-Module Pester -MaximumVersion 5.99.99 -Force

# Pester 6 (actuellement en release candidate — nécessite -AllowPrerelease)
Install-Module Pester -AllowPrerelease -Force

Sur Windows PowerShell 5.1 l'OS fournit une Pester 3 signée Microsoft intégrée que PowerShellGet ne peut pas remplacer par une Pester plus récente avec une signature différente — ajoutez -SkipPublisherCheck pour installer côte à côte. Pas nécessaire sur PowerShell 7+. Voir https://pester.dev/docs/introduction/installation.

Flux de travail de migration

Exécutez cette boucle pour chaque saut majeur. Ne sautez pas deux majeurs à la fois — allez v4→v5, puis v5→v6.

1. Baseline. Exécutez d'abord la suite sur la version actuelle et notez les résultats réussis/échoués. Vous avez besoin d'un point de départ connu (bon ou mauvais) pour que vous puissiez distinguer les régressions de migration des défaillances préexistantes.

   # Invoke-Pester nu fonctionne sur tous les majeurs ; les paramètres exacts diffèrent
   # (v3/v4 : -Script/-OutputFile ; v5+/v6 : -Path/-Output).
   Invoke-Pester

2. Lisez la référence pour ce saut (table ci-dessus) pour connaître la portée complète avant de modifier.
3. Modifiez fichier par fichier. Appliquez les changements mécaniques (voir les antisèches par saut ci-dessous et dans la référence). Gardez les changements petits et révisables — un fichier ou une préoccupation à la fois.
4. Changez de version avec Install-Module (Étape 0), puis réimportez : Remove-Module Pester; Import-Module Pester (ou démarrez une session fraîche).
5. Exécutez et corrigez. Réexécutez avec -Output Detailed ; utilisez -Output Diagnostic (v4→v5) ou lisez les messages d'erreur explicites v6 pour localiser les problèmes. Associez chaque défaillance aux tables symptôme → correction dans la référence.
6. Vert, diff, commit. Réexécutez jusqu'à ce que le résultat corresponde à la baseline (ou mieux). Examinez la diff, puis committez. Migrer en petits commits rend les régressions triviales à bissecter.

Ce qui change réellement (portée par saut)

Antisèches rapides

v4 → v5 (corrections les plus courantes)

# 1. Déplacez l'importation de fichier dans BeforeAll, utilisez $PSScriptRoot (PAS $MyInvocation.MyCommand.Path)
# AVANT
$here = Split-Path -Parent $MyInvocation.MyCommand.Path
. "$here\Get-Thing.ps1"
# APRÈS
BeforeAll { . $PSScriptRoot/Get-Thing.ps1 }

# 2. Tout code qui DÉCOUVRE/génère les tests doit être dans BeforeDiscovery
BeforeDiscovery { $cases = Get-Content $PSScriptRoot/cases.json | ConvertFrom-Json }

# 3. Should -Throw correspond avec des wildcards -like, pas .Contains
{ throw 'a long message' } | Should -Throw '*long*'

# 4. Params hérités Invoke-Pester → New-PesterConfiguration (voir référence pour la carte complète)

Détails complets, règles de scoping et table paramètre→configuration : references/v4-to-v5.md.

v5 → v6 (corrections les plus courantes)

# 1. Assertions de mock : verbes supprimés — renommez (ancien -> nouveau) :
#    Assert-MockCalled     -> Should -Invoke
#    Assert-VerifiableMock -> Should -InvokeVerifiable
Should -Invoke Get-Thing -Times 1 -Exactly
Should -InvokeVerifiable

# 2. Ajoutez un mock par défaut — les appels non appariés ne font plus fonctionner la vraie commande
Mock Get-Thing { 'default' }
Mock Get-Thing -ParameterFilter { $Name -eq 'a' } -MockWith { 'a' }

# 3. -ForEach vide/$null lève maintenant une erreur ; autorisez-le seulement si le vide est attendu
Describe 'Optional' -ForEach $cases -AllowNullOrEmptyForEach { }

# 4. Combinez les blocs BeforeAll/BeforeEach/AfterAll/AfterEach dupliqués dans le même bloc en un seul

Liste complète des changements cassants avec symptômes et corrections : references/v5-to-v6.md.

Règles de sécurité

• Les tests sont la spécification. La migration ne doit pas changer ce qu'un test affirme — seulement la façon dont la suite est structurée et invoquée. Si un test commence à réussir/échouer différemment pour une raison autre qu'un changement cassant documenté, enquêtez avant d'accepter.
• Les scripts de migration automatisés produisent de faux positifs. Les scripts communautaires (liés dans les références) aident à la syntaxe Should et au dot-sourcing, mais examinez toujours la diff et réexécutez la suite après. Ne modifiez et committez jamais en masse sans vérifier.
• Faites attention à l'encodage de fichier lors de scriptage de remplacements sur *.Tests.ps1 — conservez l'encodage d'origine (UTF-8 vs ASCII) pour ne pas massacrer les noms de tests non-ASCII.
• Travaillez sur une branche, committez par fichier/préoccupation. Les petits commits gardent git bisect utile si un test migré devient rouge plus tard.