Pester 6でPowerShellモジュールをテストする手順と失敗の読み方

1箱に6個入る例で、6個なら1箱、7個なら2箱、0個なら入力エラーと確認するPesterの練習図

PowerShellの関数を直したあと、入力が少し変わっても正しい結果になるか、毎回手で確かめるのは手間がかかります。PesterはPowerShellのテストを実行する道具です。入力と期待する結果を組にして保存すると、複数の条件を一度に確認できます。

1箱に6個入る例で、6個なら1箱、7個なら2箱、0個なら入力エラーになることを確かめます。7個のテストを一時的に失敗させ、表示された値を読み、関数を元へ戻して再実行します。

準備するのはWindows PowerShell 5.1、テキストエディター、配布元のPowerShell Galleryに接続できる環境です。一時フォルダーへの書き込みと練習用スクリプトの実行が許可された端末で試します。掲載例はPester 6.2.0で確認しました。PowerShell 7系、ほかのOS、テストを自動実行する環境での動作は未確認です。

先に結論

  • Pester 6.2.0を一時フォルダーへ保存し、署名者とファイルを照合します。読み込み後は、実際に使うコマンドの版と読み込み元を確認します。
  • 関数を書く .psm1 と、テストを書く .Tests.ps1 を同じフォルダーに保存します。
  • 失敗したテスト名、期待値、実際の値を読み、関数を元へ戻したあとに3件すべての成功を確かめます。

準備確認 PowerShellの版とPSGalleryを調べる

Windowsのスタートメニューで「Windows PowerShell」を検索して開き、下の4行を入力します。最初に表示される版番号の先頭が 5.1 なら、掲載例と同じWindows PowerShellの系統です。準備コマンドを実行するのは、この画面です。

PowerShellGetはPowerShell用の部品を入手・管理するコマンドのまとまりです。掲載例の検証環境はWindows PowerShell 5.1とPowerShellGet 1.0.0.1です。

コードの縦棒(|)は、左の処理結果を右へ渡す記号です。ここではコマンドの情報を渡し、名前と版など表示する項目を絞ります。

Windows PowerShellの版と準備状況を確認

$PSVersionTable.PSVersion.ToString()
$saveModule = Get-Command -Name Save-Module -Module PowerShellGet -ErrorAction Stop
$saveModule | Select-Object Name, Version
Get-PSRepository -Name PSGallery -ErrorAction Stop | Select-Object Name

2行目と3行目は、保存に使う Save-Module の名前と、そのコマンドを提供するPowerShellGetの版を表示します。4行目は、公式配布元の登録名 PSGallery があるか調べます。保存先で使う取得元は手順1で確認します。

最初の版表示が5.1で始まり、Save-Moduleの版が1.0.0.1で、PSGalleryが表示されたら、検証と同じ条件で手順1へ進めます。5.1でない場合はスタートメニューから「Windows PowerShell」を探し直します。

Save-Moduleの版が異なる環境は未検証です。同じ手順で試す場合はそこで止め、表示された版を控えて、検証と同じ版を利用できる練習環境があるか確認します。Save-ModuleやPSGalleryが見つからない場合も、端末の管理者へ確認してください。

実行ポリシーは、端末がスクリプトを実行する条件の一つです。「スクリプトの実行が無効」「デジタル署名されていない」などのエラーで止まったら、そこで中止します。設定はそのままにして、端末の管理者へ実行できる練習環境を確認してください。

1. 公式の取得先を確認してPesterを保存する

保存先として末尾に表示される練習フォルダーのパスを控えます。

準備確認と同じWindows PowerShellの画面で、次のコードを先頭から最後の中括弧まで貼り付けます。スマートフォンではコード欄の内側を横へ動かすと、長い行の末尾を読めます。

最初にPSGalleryの登録先を確認します。通信方式がHTTPS、ホスト名が www.powershellgallery.com、パスが /api/v2 など、公式の取得先と一致する場合に進みます。一致しない場合はメッセージを表示して取得を中止します。

公式配布先を照合して一時フォルダーに保存

$repo = Get-PSRepository -Name PSGallery -ErrorAction Stop
$feed = [uri]$repo.SourceLocation
if ($feed.IsAbsoluteUri -and $feed.Scheme -eq 'https' -and
    $feed.Host -eq 'www.powershellgallery.com' -and
    $feed.IsDefaultPort -and $feed.AbsolutePath.TrimEnd('/') -eq '/api/v2' -and
    !$feed.UserInfo -and !$feed.Query -and !$feed.Fragment) {
    $lab = Join-Path $env:TEMP ('pester-box-' + [guid]::NewGuid())
    New-Item -ItemType Directory -Path $lab -ErrorAction Stop | Out-Null
    Set-Location -LiteralPath $lab -ErrorAction Stop
    Save-Module -Name Pester -RequiredVersion 6.2.0 -Repository PSGallery -Path $lab -ErrorAction Stop
    (Get-Location).Path
} else {
    throw 'PSGalleryの登録先が公式配布先と一致しません。'
}

公式の取得先と一致した場合だけ、利用者の一時ファイル置き場を示す $env:TEMP に練習フォルダーを作り、Save-Module で指定の版を保存します。$lab はフォルダーのパスを覚えておく変数です。最後に表示されたパスを控えます。この手順ではPesterのファイルを保存します。読み込みは同じ画面で手順2の照合を通ってから行います。

最初の保存で NuGet の導入確認が出た場合は、配布物の取得に使う追加部品の案内です。検証した端末ではNuGetが導入済みで、初回導入の操作は実機では試していません。端末の管理者が導入と配布元を確認して許可した場合に進めます。判断がつかない場合は同意せず、許可の確認後にこの手順を先頭からやり直します。

登録先の不一致や保存エラーが出たら、画面のメッセージを確認します。登録やネットワークが端末で管理されている場合は管理者へ確認し、公式の取得先から保存できてから次へ進みます。

2. 署名と17ファイルを照合し、使うコマンドを確かめる

Pester.psd1 は読み込みに使う設定ファイルです。署名者はこのファイルに電子署名を付けた発行元です。証明書の指紋は署名者の証明書を識別する値で、ここでは公式配布物で確認した値と比べます。

次に、本体を含む17ファイルそれぞれのSHA256を求めます。SHA256は、内容の違いを見つけるための照合値を作る方法です。コードはファイルの名前順に、モジュール内の位置とその値を1行ずつ並べます。行の一覧からもう一度SHA256を求め、17件という数と一覧全体の値を照合します。

署名・署名者・ファイルのいずれかが違えば、Pesterを読み込む前にエラーが出て止まります。

アンパサンド(&)は後ろに指定した処理を実行する記号です。ここでは & { … } で中括弧内の照合と読み込みをまとめて実行します。同じPowerShellの画面で最後の行まで実行します。長い行の末尾はコード欄の内側を横に動かすと読めます。

照合を通ったPesterの版と読み込み元を表示

$pesterForBoxTest = $null
$pesterForBoxTest = & {
    $dir = Join-Path $lab 'Pester/6.2.0'
    $manifest = Join-Path $dir 'Pester.psd1'
    $sig = Get-AuthenticodeSignature -LiteralPath $manifest -ErrorAction Stop
    $expectedSigner = '147C2FD397677DC76DD198E83E7D9D234AA59D1A'
    if ($sig.Status -ne 'Valid' -or $sig.SignerCertificate.Thumbprint -ne $expectedSigner) {
        throw 'Pesterの署名または署名者が確認できません。'
    }
    $names = [string[]]@(Get-ChildItem -LiteralPath $dir -File -Recurse -Force -ErrorAction Stop |
        ForEach-Object { $_.FullName.Substring($dir.Length + 1) } |
        Where-Object { $_ -ne 'PSGetModuleInfo.xml' })
    [Array]::Sort($names, [StringComparer]::Ordinal)
    $rows = foreach ($name in $names) {
        $file = Join-Path $dir $name
        $hash = (Get-FileHash -LiteralPath $file -Algorithm SHA256 -ErrorAction Stop).Hash
        $name.Replace('\', '/') + ' ' + $hash
    }
    $bytes = [Text.Encoding]::UTF8.GetBytes($rows -join [char]10)
    $stream = [IO.MemoryStream]::new($bytes)
    try { $actual = (Get-FileHash -InputStream $stream -Algorithm SHA256 -ErrorAction Stop).Hash }
    finally { $stream.Dispose() }
    $expected = 'CEBB3A99DD47493384635C72C4A5E1771470DB0B87B186C22437AFCD53038D5E'
    if ($names.Count -ne 17 -or $actual -ne $expected) {
        throw 'Pester 6.2.0のファイル一覧または内容が一致しません。'
    }
    $loaded = Import-Module -Name $manifest -Global -PassThru -ErrorAction Stop
    $expectedPath = Join-Path $dir 'Pester.psm1'
    $command = $loaded.ExportedCommands['Invoke-Pester']
    if (!$command -or $command.Version -ne [version]'6.2.0' -or
        $command.Module.Path -ne $expectedPath) {
        throw 'Invoke-Pesterの版または読み込み元が一致しません。'
    }
    $command
}
$pesterForBoxTest | Select-Object Name, Version, @{Name = 'Path'; Expression = { $_.Module.Path }}

掲載の指紋とファイルの照合値は、公式配布元のPester 6.2.0で確認しました。PowerShellGetが取得時に作る記録 PSGetModuleInfo.xml は配布された17ファイルの集計から外します。

署名やファイルの照合で止まったら手順1へ戻り、新しい練習フォルダーに6.2.0を保存して手順2をもう一度実行します。再び一致しなければ練習を中止し、エラーと配布元を管理者に確認してください。

ファイルの照合を通ると Import-Module がPesterを読み込みます。-Global はこの画面で使えるようにする指定で、-PassThru は読み込んだモジュールの情報を返します。その情報からテストを実行する Invoke-Pester を選び、版と読み込み元が一致したコマンドだけを $pesterForBoxTest に入れます。

表示が Invoke-Pester、6.2.0、控えた練習フォルダー内の Pester/6.2.0/Pester.psm1 になったら成功です。版や位置が違うというエラーが出たら手順5へ進まず、保存先と版を確認します。初回は手順3へ進み、手順7から来た場合は手順7に戻って練習ファイルを確認します。

3. 箱数を計算する関数をファイルに保存する

エディターで、手順1で控えたフォルダーに BoxCount.psm1 を作ります。.psm1 は、関数などをまとめて読み込めるPowerShellのモジュール用ファイルです。掲載コードをすべて保存し、末尾が .psm1 であることを確かめます。.psm1.txt になると、次の手順のテストは指定した名前でファイルを見つけられません。

BoxCount.psm1

function Get-BoxCount {
    param(
        [Parameter(Mandatory)]
        [ValidateRange(1, 100)]
        [int]$ItemCount
    )
    [int][Math]::Ceiling($ItemCount / 6)
}

Export-ModuleMember -Function Get-BoxCount

-ItemCount は関数に荷物の個数を渡す指定です。Mandatory は個数の入力を必須にし、int は整数を表します。ValidateRange は1〜100を受け入れる範囲として指定するため、0個を渡すと計算前にエラーになります。

Ceiling は小数部分を切り上げます。6個なら6を6で割って1箱です。7個なら割り切れないので、次の整数の2箱になります。末尾の Export-ModuleMember は、モジュールを読み込んだ側から Get-BoxCount を呼び出せるようにする指定です。

4. 6個・7個・0個のテストを同じ場所へ保存する

エディターで BoxCount.psm1 と同じフォルダーに BoxCount.Tests.ps1 を作り、掲載コードを最後の行まで保存します。.Tests.ps1 はPesterのテストファイルに使う名前の末尾です。

今回はテスト名に日本語があるため、保存時に文字コード「UTF-8 with BOM」を選びます。BOMはファイルの先頭に付く目印で、Windows PowerShell 5.1はこれを使ってUTF-8として読み取れます。

Visual Studio Codeを使う場合は、テストファイルを開き、画面右下の文字コードの表示を選びます。「Save with Encoding(エンコード付きで保存)」から「UTF-8 with BOM」を選びます。ファイル名の末尾と、右下の表示を確認してからPowerShellへ戻ります。

BoxCount.Tests.ps1

BeforeAll {
    $moduleFile = Join-Path $PSScriptRoot 'BoxCount.psm1'
    Import-Module -Name $moduleFile -Force -ErrorAction Stop
}

Describe 'Get-BoxCount' {
    It '6個は1箱に収まる' {
        Get-BoxCount -ItemCount 6 | Should-Be -Expected 1
    }
    It '7個は2箱必要' {
        Get-BoxCount -ItemCount 7 | Should-Be -Expected 2
    }
    It '0個は入力エラーになる' {
        $expectedError = 'ParameterArgumentValidationError,Get-BoxCount'
        { Get-BoxCount -ItemCount 0 } | Should-Throw -FullyQualifiedErrorId $expectedError
    }
}

このファイルの BeforeAll は、Pesterがテストを見つけたあと、3件のテストに入る前に1回だけモジュールを読み込みます。$PSScriptRoot はテストファイルのあるフォルダーを指します。Join-Path で隣の BoxCount.psm1 のパスを組み立て、Import-Module の -Force で保存し直した内容を読み込みます。

Describe はテストのまとまりを作り、It はテスト1件を表します。縦棒は左の処理結果を右へ渡す記号です。6個と7個のテストでは、Should-Be が関数の戻り値と -Expected で指定した期待値を比べます。

0個のテストでは、Should-Throw が中括弧に囲まれた処理を実行します。-FullyQualifiedErrorId は確認するエラーの識別子を指定します。入力範囲の検証で、指定どおりのエラーが起きれば、このテストは成功です。

5. テストを実行して成功3件を確認する

手順2と同じPowerShellの画面を使います。まず Join-Path で、控えた練習フォルダーの $lab と、自分で手順4に保存した BoxCount.Tests.ps1 の名前をつなぎます。

Test-Path で確認するのはその場所のファイルです。-LiteralPath は指定したパスをそのまま調べ、-PathType Leaf はファイルかどうかを確認します。見つからない場合はここで止まります。

ファイルがあれば & で照合済みの $pesterForBoxTest を実行します。-Path に練習用ファイルのパスを渡すため、別のフォルダーに移動しても対象は変わりません。-Output Detailed はテストごとの表示を指定します。

控えた練習フォルダーのテストファイルを実行

if (!$pesterForBoxTest) {
    throw '手順2でPesterを読み込み、版と読み込み元を確認してください。'
}
$testFile = Join-Path $lab 'BoxCount.Tests.ps1'
if (!(Test-Path -LiteralPath $testFile -PathType Leaf)) {
    throw '練習フォルダーにBoxCount.Tests.ps1が見つかりません。'
}
$result = & $pesterForBoxTest -Path $testFile -Output Detailed -PassThru
$result | Select-Object TotalCount, PassedCount, FailedCount, Result

実行結果

TotalCount PassedCount FailedCount Result
---------- ----------- ----------- ------
         3           3           0 Passed

詳細表示の [+] は成功、[-] は失敗です。-PassThru を付けた実行結果は $result に入ります。Select-Object は結果のうち総件数・成功数・失敗数・全体結果を表示します。初回の表示は TotalCount が3、PassedCount が3、FailedCount が0、Result が Passed です。

手順2の確認を求めるエラーが出た場合は先に読み込みをやり直します。テストが見つからない場合は、控えた練習フォルダーに BoxCount.Tests.ps1 があるか確認します。BeforeAll で止まった場合は同じ場所に BoxCount.psm1 があるか確かめます。

6. 7個のテストを失敗させてから元に戻す

失敗の詳細では、まずテスト名を見てから、期待値と実際の値を読みます。

練習用の関数で、一時的に端数の扱いを変えて失敗時の表示を確認します。6個は割り切れるため結果が1箱のままです。7個は端数が出るため結果が変わります。0個は計算に入る前に入力エラーになります。

手順の下の表で、最初の実行、切り捨てで1件失敗した実行、元へ戻した実行を比べます。

  1. エディターで BoxCount.psm1 を開き、切り上げを行う Ceiling を、切り捨てを行う Floor に変えて保存します。
  2. 手順5のコードをもう一度実行します。「7個は2箱必要」の詳細に「Expected [int] 2, but got [int] 1.」と出ます。期待していた整数は2、実際に返った整数は1です。
  3. テストの期待値は2のままにして、BoxCount.psm1 の Floor を Ceiling へ戻して保存します。手順5のコードを再実行し、集計を確認します。
BoxCount.psm1の状態 総件数 成功 失敗 全体結果
最初の切り上げ(Ceiling) 3 3 0 Passed
一時的な切り捨て(Floor) 3 2 1 Failed
切り上げに復元 3 3 0 Passed

3回とも総件数は3です。最後に成功3件、失敗0件、全体結果が Passed と表示されれば、復元を確認できています。

練習を終えたらPowerShellの画面を閉じます。作成したファイルが不要なら、控えたパスをエクスプローラーで開き、練習用に作ったフォルダーだけを片づけられます。

7. PowerShellの画面を閉じたあとに再開する

Pesterを保存した後で画面を閉じた場合は、新しいWindows PowerShellを開きます。下のコードの1行目にある C:\pester-box-example を、手順1で控えたフォルダーのパスに置き換えます。パスに一重引用符が含まれる場合は、その箇所を一重引用符2つで入力します。

控えたパスに置き換えて新しい画面で実行

$lab = 'C:\pester-box-example'
Set-Location -LiteralPath $lab -ErrorAction Stop

1行目は練習フォルダーを変数に入れ、2行目でそのフォルダーへ移動します。続けて手順2のコードを先頭から最後まで実行し、署名者とファイル一式を照合してからPesterを読み込みます。

Invoke-Pester の版が 6.2.0 で、読み込み元が控えた練習フォルダー内だと確認できたら、エクスプローラーで練習フォルダーを開きます。BoxCount.psm1 または BoxCount.Tests.ps1 がまだなければ、手順3と4で作ってから手順5へ進みます。両方あれば手順5を実行できます。

Pesterの保存が途中で止まっていた場合は、画面のエラーを確認してから手順1へ戻ります。新しいフォルダーを作ったら、手順2の照合を通してから手順3と4で練習用ファイルをそろえます。