{"id":13463366,"url":"https://github.com/rspec/rspec-mocks","last_synced_at":"2025-07-27T02:31:44.212Z","repository":{"id":602761,"uuid":"238983","full_name":"rspec/rspec-mocks","owner":"rspec","description":"RSpec's 'test double' framework, with support for stubbing and mocking","archived":true,"fork":false,"pushed_at":"2024-11-30T10:37:10.000Z","size":7511,"stargazers_count":1156,"open_issues_count":0,"forks_count":356,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-07-14T23:11:01.538Z","etag":null,"topics":["rspec","ruby"],"latest_commit_sha":null,"homepage":"https://rspec.info","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rspec.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["JonRowe","benoittgt"],"open_collective":"rspec"}},"created_at":"2009-06-29T15:56:06.000Z","updated_at":"2025-06-07T17:13:47.000Z","dependencies_parsed_at":"2024-02-04T11:41:00.200Z","dependency_job_id":"71dd080e-ce3b-405b-a254-dacb775d73cc","html_url":"https://github.com/rspec/rspec-mocks","commit_stats":{"total_commits":2218,"total_committers":190,"mean_commits":"11.673684210526316","dds":0.7042380522993688,"last_synced_commit":"3caa9ac841e146d618421f870077c0ad684e6cad"},"previous_names":[],"tags_count":145,"template":false,"template_full_name":null,"purl":"pkg:github/rspec/rspec-mocks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-mocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-mocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-mocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-mocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rspec","download_url":"https://codeload.github.com/rspec/rspec-mocks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-mocks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265460802,"owners_count":23769658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rspec","ruby"],"created_at":"2024-07-31T13:00:52.085Z","updated_at":"2025-07-27T02:31:44.148Z","avatar_url":"https://github.com/rspec.png","language":"Ruby","readme":"# RSpec Mocks [![Build Status](https://github.com/rspec/rspec-mocks/workflows/RSpec%20CI/badge.svg)](https://github.com/rspec/rspec-mocks/actions) [![Code Climate](https://codeclimate.com/github/rspec/rspec-mocks.svg)](https://codeclimate.com/github/rspec/rspec-mocks)\nrspec-mocks is a test-double framework for rspec with support for method stubs,\nfakes, and message expectations on generated test-doubles and real objects\nalike.\n\n**This is the old rspec mocks repository, please see the monorepo rspec/rspec for new issues and releases.**\n\n## Install\n\n    gem install rspec       # for rspec-core, rspec-expectations, rspec-mocks\n    gem install rspec-mocks # for rspec-mocks only\n\nWant to run against the `main` branch? You'll need to include the dependent\nRSpec repos as well. Add the following to your `Gemfile`:\n\n```ruby\n%w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|\n  gem lib, :git =\u003e \"https://github.com/rspec/#{lib}.git\", :branch =\u003e 'main'\nend\n```\n## Contributing\n\nOnce you've set up the environment, you'll need to cd into the working\ndirectory of whichever repo you want to work in. From there you can run the\nspecs and cucumber features, and make patches.\n\nNOTE: You do not need to use rspec-dev to work on a specific RSpec repo. You\ncan treat each RSpec repo as an independent project.\n\nFor information about contributing to RSpec, please refer to the following markdown files:\n* [Build details](BUILD_DETAIL.md)\n* [Code of Conduct](CODE_OF_CONDUCT.md)\n* [Detailed contributing guide](CONTRIBUTING.md)\n* [Development setup guide](DEVELOPMENT.md)\n\n## Test Doubles\n\nA test double is an object that stands in for another object in your system\nduring a code example. Use the `double` method, passing in an optional identifier, to create one:\n\n```ruby\nbook = double(\"book\")\n```\n\nMost of the time you will want some confidence that your doubles resemble an\nexisting object in your system. Verifying doubles are provided for this\npurpose. If the existing object is available, they will prevent you from adding\nstubs and expectations for methods that do not exist or that have an invalid\nnumber of parameters.\n\n```ruby\nbook = instance_double(\"Book\", :pages =\u003e 250)\n```\n\nVerifying doubles have some clever tricks to enable you to both test in\nisolation without your dependencies loaded while still being able to validate\nthem against real objects. More detail is available in [their\ndocumentation](https://github.com/rspec/rspec-mocks/blob/main/features/verifying_doubles).\n\nVerifying doubles can also accept custom identifiers, just like double(), e.g.:\n\n```ruby\nbooks = []\nbooks \u003c\u003c instance_double(\"Book\", :rspec_book, :pages =\u003e 250)\nbooks \u003c\u003c instance_double(\"Book\", \"(Untitled)\", :pages =\u003e 5000)\n\nputs books.inspect # with names, it's clearer which were actually added\n```\n\n## Method Stubs\n\nA method stub is an implementation that returns a pre-determined value.  Method\nstubs can be declared on test doubles or real objects using the same syntax.\nrspec-mocks supports 3 forms for declaring method stubs:\n\n```ruby\nallow(book).to receive(:title) { \"The RSpec Book\" }\nallow(book).to receive(:title).and_return(\"The RSpec Book\")\nallow(book).to receive_messages(\n    :title =\u003e \"The RSpec Book\",\n    :subtitle =\u003e \"Behaviour-Driven Development with RSpec, Cucumber, and Friends\")\n```\n\nYou can also use this shortcut, which creates a test double and declares a\nmethod stub in one statement:\n\n```ruby\nbook = double(\"book\", :title =\u003e \"The RSpec Book\")\n```\n\nThe first argument is a name, which is used for documentation and appears in\nfailure messages. If you don't care about the name, you can leave it out,\nmaking the combined instantiation/stub declaration very terse:\n\n```ruby\ndouble(:foo =\u003e 'bar')\n```\n\nThis is particularly nice when providing a list of test doubles to a method\nthat iterates through them:\n\n```ruby\norder.calculate_total_price(double(:price =\u003e 1.99), double(:price =\u003e 2.99))\n```\n\n### Stubbing a chain of methods\n\nYou can use `receive_message_chain` in place of `receive` to stub a chain of messages:\n\n```ruby\nallow(double).to receive_message_chain(\"foo.bar\") { :baz }\nallow(double).to receive_message_chain(:foo, :bar =\u003e :baz)\nallow(double).to receive_message_chain(:foo, :bar) { :baz }\n\n# Given any of the above forms:\ndouble.foo.bar # =\u003e :baz\n```\n\nChains can be arbitrarily long, which makes it quite painless to violate the Law of Demeter in violent ways, so you should consider any use of `receive_message_chain` a code smell. Even though not all code smells indicate real problems (think fluent interfaces), `receive_message_chain` still results in brittle examples. For example, if you write `allow(foo).to receive_message_chain(:bar, :baz =\u003e 37)` in a spec and then the implementation calls `foo.baz.bar`, the stub will not work.\n\n## Consecutive return values\n\nWhen a stub might be invoked more than once, you can provide additional\narguments to `and_return`.  The invocations cycle through the list. The last\nvalue is returned for any subsequent invocations:\n\n```ruby\nallow(die).to receive(:roll).and_return(1, 2, 3)\ndie.roll # =\u003e 1\ndie.roll # =\u003e 2\ndie.roll # =\u003e 3\ndie.roll # =\u003e 3\ndie.roll # =\u003e 3\n```\n\nTo return an array in a single invocation, declare an array:\n\n```ruby\nallow(team).to receive(:players).and_return([double(:name =\u003e \"David\")])\n```\n\n## Message Expectations\n\nA message expectation is an expectation that the test double will receive a\nmessage some time before the example ends. If the message is received, the\nexpectation is satisfied. If not, the example fails.\n\n```ruby\nvalidator = double(\"validator\")\nexpect(validator).to receive(:validate) { \"02134\" }\nzipcode = Zipcode.new(\"02134\", validator)\nzipcode.valid?\n```\n\n## Test Spies\n\nVerifies the given object received the expected message during the course of\nthe test. For a message to be verified, the given object must be setup to spy\non it, either by having it explicitly stubbed or by being a null object double\n(e.g. `double(...).as_null_object`). Convenience methods are provided to easily\ncreate null object doubles for this purpose:\n\n```ruby\nspy(\"invitation\") # =\u003e same as `double(\"invitation\").as_null_object`\ninstance_spy(\"Invitation\") # =\u003e same as `instance_double(\"Invitation\").as_null_object`\nclass_spy(\"Invitation\") # =\u003e same as `class_double(\"Invitation\").as_null_object`\nobject_spy(\"Invitation\") # =\u003e same as `object_double(\"Invitation\").as_null_object`\n```\n\nVerifying messages received in this way implements the Test Spy pattern.\n\n```ruby\ninvitation = spy('invitation')\n\nuser.accept_invitation(invitation)\n\nexpect(invitation).to have_received(:accept)\n\n# You can also use other common message expectations. For example:\nexpect(invitation).to have_received(:accept).with(mailer)\nexpect(invitation).to have_received(:accept).twice\nexpect(invitation).to_not have_received(:accept).with(mailer)\n\n# One can specify a return value on the spy the same way one would a double.\ninvitation = spy('invitation', :accept =\u003e true)\nexpect(invitation).to have_received(:accept).with(mailer)\nexpect(invitation.accept).to eq(true)\n```\n\nNote that `have_received(...).with(...)` is unable to work properly when\npassed arguments are mutated after the spy records the received message.\nFor example, this does not work properly:\n\n```ruby\ngreeter = spy(\"greeter\")\n\nmessage = \"Hello\"\ngreeter.greet_with(message)\nmessage \u003c\u003c \", World\"\n\nexpect(greeter).to have_received(:greet_with).with(\"Hello\")\n```\n\n## Nomenclature\n\n### Mock Objects and Test Stubs\n\nThe names Mock Object and Test Stub suggest specialized Test Doubles.  i.e.\na Test Stub is a Test Double that only supports method stubs, and a Mock\nObject is a Test Double that supports message expectations and method\nstubs.\n\nThere is a lot of overlapping nomenclature here, and there are many\nvariations of these patterns (fakes, spies, etc). Keep in mind that most of\nthe time we're talking about method-level concepts that are variations of\nmethod stubs and message expectations, and we're applying to them to _one_\ngeneric kind of object: a Test Double.\n\n### Test-Specific Extension\n\na.k.a. Partial Double, a Test-Specific Extension is an extension of a\nreal object in a system that is instrumented with test-double like\nbehaviour in the context of a test. This technique is very common in Ruby\nbecause we often see class objects acting as global namespaces for methods.\nFor example, in Rails:\n\n```ruby\nperson = double(\"person\")\nallow(Person).to receive(:find) { person }\n```\n\nIn this case we're instrumenting Person to return the person object we've\ndefined whenever it receives the `find` message. We can also set a message\nexpectation so that the example fails if `find` is not called:\n\n```ruby\nperson = double(\"person\")\nexpect(Person).to receive(:find) { person }\n```\n\nRSpec replaces the method we're stubbing or mocking with its own\ntest-double-like method. At the end of the example, RSpec verifies any message\nexpectations, and then restores the original methods.\n\n## Expecting Arguments\n\n```ruby\nexpect(double).to receive(:msg).with(*args)\nexpect(double).to_not receive(:msg).with(*args)\n```\n\nYou can set multiple expectations for the same message if you need to:\n\n```ruby\nexpect(double).to receive(:msg).with(\"A\", 1, 3)\nexpect(double).to receive(:msg).with(\"B\", 2, 4)\n```\n\n## Argument Matchers\n\nArguments that are passed to `with` are compared with actual arguments\nreceived using ===. In cases in which you want to specify things about the\narguments rather than the arguments themselves, you can use any of the\nmatchers that ship with rspec-expectations. They don't all make syntactic\nsense (they were primarily designed for use with RSpec::Expectations), but\nyou are free to create your own custom RSpec::Matchers.\n\nrspec-mocks also adds some keyword Symbols that you can use to\nspecify certain kinds of arguments:\n\n```ruby\nexpect(double).to receive(:msg).with(no_args)\nexpect(double).to receive(:msg).with(any_args)\nexpect(double).to receive(:msg).with(1, any_args) # any args acts like an arg splat and can go anywhere\nexpect(double).to receive(:msg).with(1, kind_of(Numeric), \"b\") #2nd argument can be any kind of Numeric\nexpect(double).to receive(:msg).with(1, boolean(), \"b\") #2nd argument can be true or false\nexpect(double).to receive(:msg).with(1, /abc/, \"b\") #2nd argument can be any String matching the submitted Regexp\nexpect(double).to receive(:msg).with(1, anything(), \"b\") #2nd argument can be anything at all\nexpect(double).to receive(:msg).with(1, duck_type(:abs, :div), \"b\") #2nd argument can be object that responds to #abs and #div\nexpect(double).to receive(:msg).with(hash_including(:a =\u003e 5)) # first arg is a hash with a: 5 as one of the key-values\nexpect(double).to receive(:msg).with(array_including(5)) # first arg is an array with 5 as one of the key-values\nexpect(double).to receive(:msg).with(hash_excluding(:a =\u003e 5)) # first arg is a hash without a: 5 as one of the key-values\nexpect(double).to receive(:msg).with(start_with('a')) # any matcher, custom or from rspec-expectations\nexpect(double).to receive(:msg).with(satisfy { |data| data.dig(:a, :b, :c) == 5 }) # assert anything you want\n```\n\n## Receive Counts\n\n```ruby\nexpect(double).to receive(:msg).once\nexpect(double).to receive(:msg).twice\nexpect(double).to receive(:msg).exactly(n).time\nexpect(double).to receive(:msg).exactly(n).times\nexpect(double).to receive(:msg).at_least(:once)\nexpect(double).to receive(:msg).at_least(:twice)\nexpect(double).to receive(:msg).at_least(n).time\nexpect(double).to receive(:msg).at_least(n).times\nexpect(double).to receive(:msg).at_most(:once)\nexpect(double).to receive(:msg).at_most(:twice)\nexpect(double).to receive(:msg).at_most(n).time\nexpect(double).to receive(:msg).at_most(n).times\n```\n\n## Ordering\n\n```ruby\nexpect(double).to receive(:msg).ordered\nexpect(double).to receive(:other_msg).ordered\n  # This will fail if the messages are received out of order\n```\n\nThis can include the same message with different arguments:\n\n```ruby\nexpect(double).to receive(:msg).with(\"A\", 1, 3).ordered\nexpect(double).to receive(:msg).with(\"B\", 2, 4).ordered\n```\n\n## Setting Responses\n\nWhether you are setting a message expectation or a method stub, you can\ntell the object precisely how to respond. The most generic way is to pass\na block to `receive`:\n\n```ruby\nexpect(double).to receive(:msg) { value }\n```\n\nWhen the double receives the `msg` message, it evaluates the block and returns\nthe result.\n\n```ruby\nexpect(double).to receive(:msg).and_return(value)\nexpect(double).to receive(:msg).exactly(3).times.and_return(value1, value2, value3)\n  # returns value1 the first time, value2 the second, etc\nexpect(double).to receive(:msg).and_raise(error)\n  # `error` can be an instantiated object (e.g. `StandardError.new(some_arg)`) or a class (e.g. `StandardError`)\n  # if it is a class, it must be instantiable with no args\nexpect(double).to receive(:msg).and_throw(:msg)\nexpect(double).to receive(:msg).and_yield(values, to, yield)\nexpect(double).to receive(:msg).and_yield(values, to, yield).and_yield(some, other, values, this, time)\n  # for methods that yield to a block multiple times\n```\n\nAny of these responses can be applied to a stub as well\n\n```ruby\nallow(double).to receive(:msg).and_return(value)\nallow(double).to receive(:msg).and_return(value1, value2, value3)\nallow(double).to receive(:msg).and_raise(error)\nallow(double).to receive(:msg).and_throw(:msg)\nallow(double).to receive(:msg).and_yield(values, to, yield)\nallow(double).to receive(:msg).and_yield(values, to, yield).and_yield(some, other, values, this, time)\n```\n\n## Arbitrary Handling\n\nOnce in a while you'll find that the available expectations don't solve the\nparticular problem you are trying to solve. Imagine that you expect the message\nto come with an Array argument that has a specific length, but you don't care\nwhat is in it. You could do this:\n\n```ruby\nexpect(double).to receive(:msg) do |arg|\n  expect(arg.size).to eq 7\nend\n```\n\nIf the method being stubbed itself takes a block, and you need to yield to it\nin some special way, you can use this:\n\n```ruby\nexpect(double).to receive(:msg) do |\u0026arg|\n  begin\n    arg.call\n  ensure\n    # cleanup\n  end\nend\n```\n\n## Delegating to the Original Implementation\n\nWhen working with a partial mock object, you may occasionally\nwant to set a message expectation without interfering with how\nthe object responds to the message. You can use `and_call_original`\nto achieve this:\n\n```ruby\nexpect(Person).to receive(:find).and_call_original\nPerson.find # =\u003e executes the original find method and returns the result\n```\n\n## Combining Expectation Details\n\nCombining the message name with specific arguments, receive counts and responses\nyou can get quite a bit of detail in your expectations:\n\n```ruby\nexpect(double).to receive(:\u003c\u003c).with(\"illegal value\").once.and_raise(ArgumentError)\n```\n\nWhile this is a good thing when you really need it, you probably don't really\nneed it! Take care to specify only the things that matter to the behavior of\nyour code.\n\n## Stubbing and Hiding Constants\n\nSee the [mutating constants\nREADME](https://github.com/rspec/rspec-mocks/blob/main/features/mutating_constants/README.md)\nfor info on this feature.\n\n## Use `before(:example)`, not `before(:context)`\n\nStubs in `before(:context)` are not supported. The reason is that all stubs and mocks get cleared out after each example, so any stub that is set in `before(:context)` would work in the first example that happens to run in that group, but not for any others.\n\nInstead of `before(:context)`, use `before(:example)`.\n\n## Settings mocks or stubs on any instance of a class\n\nrspec-mocks provides two methods, `allow_any_instance_of` and\n`expect_any_instance_of`, that will allow you to stub or mock any instance\nof a class. They are used in place of `allow` or `expect`:\n\n```ruby\nallow_any_instance_of(Widget).to receive(:name).and_return(\"Wibble\")\nexpect_any_instance_of(Widget).to receive(:name).and_return(\"Wobble\")\n```\n\nThese methods add the appropriate stub or expectation to all instances of\n`Widget`.\n\nThis feature is sometimes useful when working with legacy code, though in\ngeneral we discourage its use for a number of reasons:\n\n* The `rspec-mocks` API is designed for individual object instances, but this\n  feature operates on entire classes of objects. As a result there are some\n  semantically confusing edge cases. For example in\n  `expect_any_instance_of(Widget).to receive(:name).twice` it isn't clear\n  whether each specific instance is expected to receive `name` twice, or if two\n  receives total are expected. (It's the former.)\n* Using this feature is often a design smell. It may be\n  that your test is trying to do too much or that the object under test is too\n  complex.\n* It is the most complicated feature of `rspec-mocks`, and has historically\n  received the most bug reports. (None of the core team actively use it,\n  which doesn't help.)\n\n\n## Further Reading\n\nThere are many different viewpoints about the meaning of mocks and stubs. If\nyou are interested in learning more, here is some recommended reading:\n\n* Mock Objects: http://www.mockobjects.com/\n* Endo-Testing: http://www.ccs.neu.edu/research/demeter/related-work/extreme-programming/MockObjectsFinal.PDF\n* Mock Roles, Not Objects: http://www.jmock.org/oopsla2004.pdf\n* Test Double: http://www.martinfowler.com/bliki/TestDouble.html\n* Test Double Patterns: http://xunitpatterns.com/Test%20Double%20Patterns.html\n* Mocks aren't stubs: http://www.martinfowler.com/articles/mocksArentStubs.html\n\n## Also see\n\n* [https://github.com/rspec/rspec](https://github.com/rspec/rspec)\n* [https://github.com/rspec/rspec-core](https://github.com/rspec/rspec-core)\n* [https://github.com/rspec/rspec-expectations](https://github.com/rspec/rspec-expectations)\n* [https://github.com/rspec/rspec-rails](https://github.com/rspec/rspec-rails)\n","funding_links":["https://github.com/sponsors/JonRowe","https://github.com/sponsors/benoittgt","https://opencollective.com/rspec"],"categories":["Testing","Ruby"],"sub_categories":["Mocking"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspec%2Frspec-mocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frspec%2Frspec-mocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspec%2Frspec-mocks/lists"}