base on Provides a readable API to express expected outcomes of a code example # RSpec Expectations [](https://github.com/rspec/rspec-expectations/actions) [](https://codeclimate.com/github/rspec/rspec-expectations) **This is the old rspec expectations repository, please see the monorepo rspec/rspec for new issues and releases.** RSpec::Expectations lets you express expected outcomes on an object in an example. ```ruby expect(account.balance).to eq(Money.new(37.42, :USD)) ``` ## Install If you want to use rspec-expectations with rspec, just install the rspec gem and RubyGems will also install rspec-expectations for you (along with rspec-core and rspec-mocks): ```shell gem install rspec ``` Want to run against the `main` branch? You'll need to include the dependent RSpec repos as well. Add the following to your `Gemfile`: ```ruby %w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib| gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'main' end ``` If you want to use rspec-expectations with another tool, like Test::Unit, Minitest, or Cucumber, you can install it directly: ```shell gem install rspec-expectations ``` ## Contributing Once you've set up the environment, you'll need to cd into the working directory of whichever repo you want to work in. From there you can run the specs and cucumber features, and make patches. NOTE: You do not need to use rspec-dev to work on a specific RSpec repo. You can treat each RSpec repo as an independent project. - [Build details](BUILD_DETAIL.md) - [Code of Conduct](CODE_OF_CONDUCT.md) - [Detailed contributing guide](CONTRIBUTING.md) - [Development setup guide](DEVELOPMENT.md) ## Basic usage Here's an example using rspec-core: ```ruby RSpec.describe Order do it "sums the prices of the items in its line items" do order = Order.new order.add_entry(LineItem.new(:item => Item.new( :price => Money.new(1.11, :USD) ))) order.add_entry(LineItem.new(:item => Item.new( :price => Money.new(2.22, :USD), :quantity => 2 ))) expect(order.total).to eq(Money.new(5.55, :USD)) end end ``` The `describe` and `it` methods come from rspec-core. The `Order`, `LineItem`, `Item` and `Money` classes would be from _your_ code. The last line of the example expresses an expected outcome. If `order.total == Money.new(5.55, :USD)`, then the example passes. If not, it fails with a message like: ``` expected: #<Money @value=5.55 @currency=:USD> got: #<Money @value=1.11 @currency=:USD> ``` ## Built-in matchers ### Equivalence ```ruby expect(actual).to eq(expected) # passes if actual == expected expect(actual).to eql(expected) # passes if actual.eql?(expected) expect(actual).not_to eql(not_expected) # passes if not(actual.eql?(expected)) ``` Note: The new `expect` syntax no longer supports the `==` matcher. ### Identity ```ruby expect(actual).to be(expected) # passes if actual.equal?(expected) expect(actual).to equal(expected) # passes if actual.equal?(expected) ``` ### Comparisons ```ruby expect(actual).to be > expected expect(actual).to be >= expected expect(actual).to be <= expected expect(actual).to be < expected expect(actual).to be_within(delta).of(expected) ``` ### Regular expressions ```ruby expect(actual).to match(/expression/) ``` Note: The new `expect` syntax no longer supports the `=~` matcher. ### Types/classes ```ruby expect(actual).to be_an_instance_of(expected) # passes if actual.class == expected expect(actual).to be_a(expected) # passes if actual.kind_of?(expected) expect(actual).to be_an(expected) # an alias for be_a expect(actual).to be_a_kind_of(expected) # another alias ``` ### Truthiness ```ruby expect(actual).to be_truthy # passes if actual is truthy (not nil or false) expect(actual).to be true # passes if actual == true expect(actual).to be_falsy # passes if actual is falsy (nil or false) expect(actual).to be false # passes if actual == false expect(actual).to be_nil # passes if actual is nil expect(actual).to_not be_nil # passes if actual is not nil ``` ### Expecting errors ```ruby expect { ... }.to raise_error expect { ... }.to raise_error(ErrorClass) expect { ... }.to raise_error("message") expect { ... }.to raise_error(ErrorClass, "message") ``` ### Expecting throws ```ruby expect { ... }.to throw_symbol expect { ... }.to throw_symbol(:symbol) expect { ... }.to throw_symbol(:symbol, 'value') ``` ### Yielding ```ruby expect { |b| 5.tap(&b) }.to yield_control # passes regardless of yielded args expect { |b| yield_if_true(true, &b) }.to yield_with_no_args # passes only if no args are yielded expect { |b| 5.tap(&b) }.to yield_with_args(5) expect { |b| 5.tap(&b) }.to yield_with_args(Integer) expect { |b| "a string".tap(&b) }.to yield_with_args(/str/) expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3) expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2]) ``` ### Predicate matchers ```ruby expect(actual).to be_xxx # passes if actual.xxx? expect(actual).to have_xxx(:arg) # passes if actual.has_xxx?(:arg) ``` ### Ranges (Ruby >= 1.9 only) ```ruby expect(1..10).to cover(3) ``` ### Collection membership ```ruby # exact order, entire collection expect(actual).to eq(expected) # exact order, partial collection (based on an exact position) expect(actual).to start_with(expected) expect(actual).to end_with(expected) # any order, entire collection expect(actual).to match_array(expected) # You can also express this by passing the expected elements # as individual arguments expect(actual).to contain_exactly(expected_element1, expected_element2) # any order, partial collection expect(actual).to include(expected) ``` #### Examples ```ruby expect([1, 2, 3]).to eq([1, 2, 3]) # Order dependent equality check expect([1, 2, 3]).to include(1) # Exact ordering, partial collection matches expect([1, 2, 3]).to include(2, 3) # expect([1, 2, 3]).to start_with(1) # As above, but from the start of the collection expect([1, 2, 3]).to start_with(1, 2) # expect([1, 2, 3]).to end_with(3) # As above but from the end of the collection expect([1, 2, 3]).to end_with(2, 3) # expect({:a => 'b'}).to include(:a => 'b') # Matching within hashes expect("this string").to include("is str") # Matching within strings expect("this string").to start_with("this") # expect("this string").to end_with("ring") # expect([1, 2, 3]).to contain_exactly(2, 3, 1) # Order independent matches expect([1, 2, 3]).to match_array([3, 2, 1]) # # Order dependent compound matchers expect( [{:a => 'hash'},{:a => 'another'}] ).to match([a_hash_including(:a => 'hash'), a_hash_including(:a => 'another')]) ``` ## `should` syntax In addition to the `expect` syntax, rspec-expectations continues to support the `should` syntax: ```ruby actual.should eq expected actual.should be > 3 [1, 2, 3].should_not include 4 ``` See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/main/Should.md) ## Compound Matcher Expressions You can also create compound matcher expressions using `and` or `or`: ``` ruby expect(alphabet).to start_with("a").and end_with("z") expect(stoplight.color).to eq("red").or eq("green").or eq("yellow") ``` ## Composing Matchers Many of the built-in matchers are designed to take matchers as arguments, to allow you to flexibly specify only the essential aspects of an object or data structure. In addition, all of the built-in matchers have one or more aliases that provide better phrasing for when they are used as arguments to another matcher. ### Examples ```ruby expect { k += 1.05 }.to change { k }.by( a_value_within(0.1).of(1.0) ) expect { s = "barn" }.to change { s } .from( a_string_matching(/foo/) ) .to( a_string_matching(/bar/) ) expect(["barn", 2.45]).to contain_exactly( a_value_within(0.1).of(2.5), a_string_starting_with("bar") ) expect(["barn", "food", 2.45]).to end_with( a_string_matching("foo"), a_value > 2 ) expect(["barn", 2.45]).to include( a_string_starting_with("bar") ) expect(:a => "food", :b => "good").to include(:a => a_string_matching(/foo/)) hash = { :a => { :b => ["foo", 5], :c => { :d => 2.05 } } } expect(hash).to match( :a => { :b => a_collection_containing_exactly( a_string_starting_with("f"), an_instance_of(Integer) ), :c => { :d => (a_value < 3) } } ) expect { |probe| [1, 2, 3].each(&probe) }.to yield_successive_args( a_value < 2, 2, a_value > 2 ) ``` ## Usage outside rspec-core You always need to load `rspec/expectations` even if you only want to use one part of the library: ```ruby require 'rspec/expectations' ``` Then simply include `RSpec::Matchers` in any class: ```ruby class MyClass include RSpec::Matchers def do_something(arg) expect(arg).to be > 0 # do other stuff end end ``` ## Also see * [https://github.com/rspec/rspec](https://github.com/rspec/rspec) * [https://github.com/rspec/rspec-core](https://github.com/rspec/rspec-core) * [https://github.com/rspec/rspec-mocks](https://github.com/rspec/rspec-mocks) * [https://github.com/rspec/rspec-rails](https://github.com/rspec/rspec-rails) ", Assign "at most 3 tags" to the expected json: {"id":"537","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"