カスタムマッチャー

複数のスペック全体で使用するカスタムマッチングコードをプロジェクトがカプセル化したい場合が頻繁にあります。ここでは、Jasmine互換のカスタムマッチャーを作成する方法を示します。

本質的にカスタムマッチャーは、actual値とexpected値を受け取る比較関数です。このファクトリは、理想的にはbeforeEachへの呼び出しでJasmineに渡され、指定のdescribe呼び出し内のすべてのスペックで有効期限が切れるまでスコープ内になり利用可能になります。カスタムマッチャーは、スペック間で削除されます。ファクトリの名前は、expectへの呼び出しの戻り値に公開されたマッチャーの名前になります。

このオブジェクトは、「toBeGoofy」というカスタムマッチャーがあります。

 
const customMatchers = {

マッチャーファクトリ

カスタムマッチャーファクトリは、2つのオブジェクトが等しいかどうかを判定するなどのタスクを実行するためにマッチャーが使用できる一連のユーティリティ関数があるmatchersUtilパラメーターが渡されます（参照ドキュメントについては、MatchersUtilを参照してください）。適切な場所でMatchersUtilを使用すると、カスタムマッチャーはカスタム等価性テスターおよびカスタムオブジェクトフォーマッターと余分な作業なしで動作できます。

Jasmine 3.5以前との互換性のために、2番目のcustomEqualityTestersパラメーターが渡されます。Jasmine 3.6以降に記述されたマッチャーはそれを無視してください。これはJasmine 4では提供されなくなります。

 
    toBeGoofy: function(matchersUtil) {

ファクトリメソッドは、期待値をチェックするために呼び出されるcompare関数があるオブジェクトを返す必要があります。

 
        return {

compareと比較する関数

compare関数は、最初の引数としてexpect()に渡される値（実際）と、2番目の引数としてマッチャー自体に渡される値（存在する場合）を受け取ります。

 
            compare: function(actual, expected) {

toBeGoofyはオプションのexpected引数を受け取るので、渡されない場合はここで定義します。

 
                if (expected === undefined) {
                    expected = '';
                }

結果

compare関数は、マッチャーのブーリアン結果であるpassプロパティがある結果オブジェクトを返す必要があります。passプロパティは、expectationにマッチャーが成功（true）したか失敗したか（false）を伝えます。expectationが.notで呼ばれたり、ネストされたりすると、expectationはこの値を否定してexpectationが満たされているかどうかを判定します。

 
                const result = {
                };

toBeGoofyは実際のhyukプロパティがexpectationに一致するかどうかを確認するためにテストします。

 
                result.pass = matchersUtil.equals(actual.hyuk, 
                    "gawrsh" + expected);

エラーメッセージ

undefinedをそのままにすると、期待値はマッチャーの失敗メッセージを作成しようとします。しかし、返り値にmessageプロパティがある場合、失敗した期待値に使用されます。

 
                if (result.pass) {

マッチャーが成功した場合、負の期待値の場合（expectationが.notで使用される場合）にはカスタムの失敗メッセージが表示されるはずです。

 
                    result.message = "Expected " + actual + 
                        " not to be quite so goofy";
                } else {

マッチャーが失敗した場合、正の期待値の場合にはカスタムの失敗メッセージが表示されるはずです。

 
                    result.message = "Expected " + actual + 
                        " to be goofy, but it was not very goofy";
                }

比較の結果を返します。

 
                return result;
            }
        };
    }
};

カスタムの否定比較

上記の単純なブーリアン反転より否定の比較（notの場合）をより細かく管理する必要がある場合、マッチャーファクトリにcompareの他に別のキーnegativeCompare（.notが使用された場合に呼び出す関数の値）を含めることもできます。この関数/キーはオプションです。

登録と使用

 
describe("Custom matcher: 'toBeGoofy'", function() {

Jasmineにカスタムマッチャーを登録します。渡されたオブジェクトのすべてのプロパティは、カスタムマッチャーとして利用できます（この場合はtoBeGoofyなど）。

 
    beforeEach(function() {
        jasmine.addMatchers(customMatchers);
    });

Jasmineにカスタムマッチャーが登録されると、どの期待値でも利用できます。

 
    it("is available on an expectation", function() {
        expect({
            hyuk: 'gawrsh'
        }).toBeGoofy();
    });

    it("can take an 'expected' parameter", function() {
        expect({
            hyuk: 'gawrsh is fun'
        }).toBeGoofy(' is fun');
    });

    it("can be negated", function() {
        expect({
            hyuk: 'this is fun'
        }).not.toBeGoofy();
    });
});