以前Pesterの機能をハックしてカスタムアサーションを行うエントリを書きましたが、Pester 4.0.5より正式にカスタムアサーションを追加する方法が提供されました。
本エントリではその方法を紹介します。
Pesterでカスタムアサーションを行う
これまでは、
- Pester[動詞]
- Pester[動詞]FailureMessage
- NotPester[動詞]FailureMessage
という名称の3つの関数を用意してやればPesterが内部的に独自の動詞として認識してくれました。
Peseter 4.0.5からは新たにAdd-AssertionOperatorという関数が追加され、任意の関数を1つ用意すれば独自の動詞として使用することができる様になりました。
カスタムアサーション例
Gistに前回の例を正式な方法で移植したものを上げました。
前回の関数をそのまま移植している部分があるので若干ごちゃごちゃしていますが、とりあえずはBeHashという関数に注目してください。
カスタムアサーションを行う関数の仕様
カスタムアサーションを行う関数の名称は任意で良くなりました。
今回はBeHashという名前にしています。
ただし、引数は最低限以下の様にする必要があります。
- ActualValue : テスト対象となる値
- ExpectedValue : (オプション)期待値
- Nagate : -Notと併用される場合は$true、そうでない場合は$falseが指定される
検証していませんが、内部的にはパラメーター名で識別している様なので引数の順序はバラバラでも大丈夫そうです。
また-ExpectedValueは無くても問題ありません。
そして-Nagateパラメーターは
Should -Not -BeHash @{ Name = "田中"; Salary = 300 }
の様に-Notと動詞が併用されるときに$trueが渡されるパラメーターとなります。
先の例にある様にこのパラメーターによって検証結果の成否を反転してやる必要が出てきます。
ちなみに、本エントリでは詳細に触れませんが、この3つ以外に引数を追加すると独自パラメーターとして使える様です。
次に、関数の戻り値は以下のプロパティを持つPSCustomObject*1にする必要があります。
- Succeeded : テストが成功した時は$true、失敗した時は$false
- FailureMessage : テスト失敗時のエラーメッセージ
先の例にある様に-Nagateパラメーターによってエラーメッセージを切り替えてやるのがパターンの様です。
(この例では最終的に同じメッセージになるのですが、Pesterの内部実装を見るときちんとメッセージを分けてやっています)
Add-AssertionOperatorの使い方
新たに作った関数をAdd-AssertionOperatorに渡すことで独自の動詞として登録し、カスタムアサーションを行うことができる様になります。
Add-AssertionOperatorは以下の引数を取ります。
- Name : Shouldで使われる動詞の名前。
BeHashを指定するとShould -BeHashと宣言することが可能 - Test : カスタムアサーションを行う関数
- Alias : (オプション)動詞のエイリアス。[string[]]型で複数指定可能
- SupportsArrayInput : (Switch)配列入力をサポートするか否か
使用例として先の例から利用個所を抜粋しておきます。
# 使用例 Add-AssertionOperator -Name BeHash -Test $function:BeHash -Alias 'Hash'
参考資料
とりあえずこんな感じです。
Pester 4.0では/Functions/Assertionsディレクトリにある標準の動詞もAdd-AssertionOperatorを使う様に実装が書き換えられています。
これらの実装を読むのがカスタムアサーションを行う際の一番の参考資料になるでしょう。
*1:実装上はNew-Object PSObjectとしています
