RSpec 3の新機能: コンポーザブルマッチャー
Myron Marston » New in RSpec 3: Composable Matchersの訳です。
あかんところあったらTwitterで@nilp_までお願いします
RSpec 3の、最も大きな新機能が3.0.0.beta2で公開されました: コンポーザブルマッチャ(組み合わせ可能なマッチャー)です。 これにより強力で壊れづらい検証を書けるようになり、新たな可能性が開けました。
例
RSpec 2.xでは、私はこのようなコードを度々書いてきました。
class BackgroundWorker attr_reader :queue def initialize @queue = [] end def enqueue(job_data) queue << job_data.merge(:enqueued_at => Time.now) end end
describe BackgroundWorker do it 'puts enqueued jobs onto the queue in order' do worker = BackgroundWorker.new worker.enqueue(:klass => "Class1", :id => 37) worker.enqueue(:klass => "Class2", :id => 42) expect(worker.queue.size).to eq(2) expect(worker.queue[0]).to include(:klass => "Class1", :id => 37) expect(worker.queue[1]).to include(:klass => "Class2", :id => 42) end end
RSpec 3では、コンポーザブルマッチャーを使うと、マッチャーを引数として(あるいは、データ構造の中にネストさせて)、他のマッチャーに渡すことができ、これにより次のようにシンプルにspecを書けるようになります
describe BackgroundWorker do it 'puts enqueued jobs onto the queue in order' do worker = BackgroundWorker.new worker.enqueue(:klass => "Class1", :id => 37) worker.enqueue(:klass => "Class2", :id => 42) expect(worker.queue).to match [ a_hash_including(:klass => "Class1", :id => 37), a_hash_including(:klass => "Class2", :id => 42) ] end end
我々は次のようなケースでも、失敗時のメッセージの読みやすさを保つため、inspect
の結果ではなく、与えられたマッチャーのdescription
を使うようにしました。
例えば、もし我々がqueue <<
の行をコメントアウトして、このspecでテストしている実装を壊してしまったとき、specは次のように失敗します:
1) BackgroundWorker puts enqueued jobs onto the queue in order Failure/Error: expect(worker.queue).to match [ expected [] to match [(a hash including {:klass => "Class1", :id => 37}), (a hash including {:klass => "Class2", :id => 42})] Diff: @@ -1,3 +1,2 @@ -[(a hash including {:klass => "Class1", :id => 37}), - (a hash including {:klass => "Class2", :id => 42})] +[] # ./spec/background_worker_spec.rb:19:in `block (2 levels) in <top (required)>'
マッチャーエイリアス
もう気づいたかもしれませんが、上記の例ではa_hash_including
をinclude
の代わりに使っていました。
RSpec 3は、同じようなエイリアスをすべてのビルトインマッチャーに与えており、それにより文章としての読みやすさと、よりよい失敗時のメッセージが提供されます。 例えば、この検証と、失敗時のメッセージを比べてみましょう:
x = "a" expect { }.to change { x }.from start_with("a")
expected result to have changed from start with "a", but did not change
x = "a" expect { }.to change { x }.from a_string_starting_with("a")
expected result to have changed from a string starting with "a", but did not change
a_string_starting_with
はstart_with
にくらべより冗長な一方、失敗時のメッセージは本当に読み下しやすく、「日本語でおk」とならずにすみます。
我々は1つあるいはもっと多くのエイリアスをすべてのRSpecのビルトインマッチャーに与えました。
我々は、一環した表現を使うように努めているので(だいたいは "a [オブジェクトの型] [動詞]ing"のかたち)、どんなエイリアスがあるか推測するのは楽です。
このあといくつも例を出すので、あなたはそれを見ることができますし、RSpec 3のドキュメントにはすべてのリストを載せる予定です。
また、(RSpecのビルトインマッチャーであるかカスタムマッチャーであるかにかかわらず)自分自身で手軽にエイリアスを定義できるpublicなAPIがあります。
これはrspec-expectations
の中で、start_with
のエイリアスのa_string_with
を提供するためのコードです:
RSpec::Matchers.alias_matcher :a_string_starting_with, :start_with
Compound Matcher Expressions(マッチャー合成式)
Eloy Espinacoは、新機能として、マッチャーを組み合わせるための別の手段を提供するのに貢献しました: and
とor
によるマッチャーの合成です。
例えば、あなたはこうやって書かずに:
expect(alphabet).to start_with("a") expect(alphabet).to end_with("z")
2つのマッチャーを組み合わせて1つのマッチャーにすることが出来ます。
expect(alphabet).to start_with("a").and end_with("z")
もちろん、or
でも同じことができます。あまり一般的ではないかもしれませんが、これは、正しい値のリストを表現するのにすごく便利です(例えば、検証したい値がはっきりしない場合)
expect(stoplight.color).to eq("red").or eq("green").or eq("yellow")
私は、これは特に、Jim Weirichのrspec-givenを使ってInvariantsを表現するのに便利なんじゃないかと考えています。 もちろん、マッチャー合成式を、引数として他のマッチャーに渡すことも出来ます:
expect(["food", "drink"]).to include( a_string_starting_with("f").and ending_with("d") )
注: この例の、ending_with
はend_with
マッチャーのエイリアスです
どのマッチャーが、マッチャー引数をサポートしてる?
RSpec 3では、我々は引数としてマッチャーを受け取れるよう、たくさんのマッチャーを更新しました、しかしすべてというわけではありません。
おおむね、わたしたちが納得できるようなものはすべて更新しました。 マッチャー引数をサポートしないマッチャーの1つに、マッチャー引数をうけつけることが出来ないことが明確なものがあります。
例えば、eq
マッチャーは、actual == expected
の場合にのみ真になります。
そのため、eq
がマッチャー引数をサポートすることはできません。
私は、マッチャー引数をサポートするすべてのビルトインマッチャーのリストを作りました↓
change
change
マッチャーのby
メソッドは、マッチャー引数を受け取れます。
k = 0 expect { k += 1.05 }.to change { k }.by( a_value_within(0.1).of(1.0) )
同様にfrom
とto
にもマッチャー引数を渡すことができます
s = "food" expect { s = "barn" }.to change { s }. from( a_string_matching(/foo/) ). to( a_string_matching(/bar/) )
contain_exactly
contain_exactly
は、match_array
の新しいエイリアスです。
match_array
よりも少し意味が明確です(いま、match
でも同じように配列にマッチすることができます、しかしmatch
の方は順番を気にする必要があります、一方match_array
では気にする必要はありません)
また、配列の要素をそれぞれ、個別の引数として渡すことができます。match_array
のように、1つの配列に詰め込むことを強いらません。
expect(["barn", 2.45]).to contain_exactly( a_value_within(0.1).of(2.5), a_string_starting_with("bar") ) # ...which is the same as: expect(["barn", 2.45]).to match_array([ a_value_within(0.1).of(2.5), a_string_starting_with("bar") ])
include
include
では、コレクションの要素、ハッシュのキー、ハッシュの中のkey/valueペアのサブセットに対するマッチが出来ます。
expect(["barn", 2.45]).to include( a_string_starting_with("bar") ) expect(12 => "twelve", 3 => "three").to include( a_value_between(10, 15) ) expect(:a => "food", :b => "good").to include( :a => a_string_matching(/foo/) )
match
文字列と正規表現、文字列と文字列のマッチに付け加えて、今ではarray/hashのデータ構造に対してもうまく動きます、好きなだけネストしまくっていてもです。 マッチャーは、ネストのどの階層でも使うことができます。
hash = { :a => { :b => ["foo", 5], :c => { :d => 2.05 } } } expect(hash).to match( :a => { :b => a_collection_containing_exactly( an_instance_of(Fixnum), a_string_starting_with("f") ), :c => { :d => (a_value < 3) } } )
raise_error
raise_error
が、例外クラスに対するマッチャーか、例外のメッセージに対するマッチャー、あるいはその両方を受け付けるようになりました。
start_with and end_with
これをみれば一目瞭然:
expect(["barn", "food", 2.45]).to start_with( a_string_matching("bar"), a_string_matching("foo") ) expect(["barn", "food", 2.45]).to end_with( a_string_matching("foo"), a_value < 3 )
throw_symbol
Symbol以外の他の引数に対してマッチするマッチャーをthrow_symbol
に渡せます:
expect { throw :pi, Math::PI }.to throw_symbol(:pi, a_value_within(0.01).of(3.14))
yield_with_args と yield_successive_args
これらのマッチャー(yield_with_args
/yield_successive_args
)の、yield
に渡された引数を明示するのに、マッチャーを使うことができます:
expect { |probe| "food".tap(&probe) }.to yield_with_args( a_string_starting_with("f") ) expect { |probe| [1, 2, 3].each(&probe) }.to yield_successive_args( a_value < 2, 2, a_value > 2 )
まとめ
これは、RSpec 3の新機能の1つです。 私はこの機能に一番わくわくしました、あなたにもこの興奮が伝わるといいなぁと思っています。 この記事が、あなたが必要なことだけを書けばそれ以外のことを書かなくてよくなる(壊れやすいテストを書くのを避ける)手助けになればいいなあと思います。