{"id":14991224,"url":"https://github.com/rspec/rspec-core","last_synced_at":"2025-08-06T13:31:26.998Z","repository":{"id":602750,"uuid":"238972","full_name":"rspec/rspec-core","owner":"rspec","description":"RSpec runner and formatters","archived":true,"fork":false,"pushed_at":"2024-11-30T10:40:27.000Z","size":12027,"stargazers_count":1232,"open_issues_count":0,"forks_count":754,"subscribers_count":50,"default_branch":"main","last_synced_at":"2025-08-01T19:22:12.677Z","etag":null,"topics":["rspec","ruby"],"latest_commit_sha":null,"homepage":"http://rspec.info","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"influxdata/influxdb","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:41:05.000Z","updated_at":"2025-07-27T09:26:20.000Z","dependencies_parsed_at":"2023-07-05T15:03:01.263Z","dependency_job_id":"1d125e1f-3787-4b49-a86c-b0d154a163d7","html_url":"https://github.com/rspec/rspec-core","commit_stats":{"total_commits":4860,"total_committers":376,"mean_commits":"12.925531914893616","dds":0.7111111111111111,"last_synced_commit":"aec5f49485d97908183dbe790a7fefb8baaa8091"},"previous_names":[],"tags_count":154,"template":false,"template_full_name":null,"purl":"pkg:github/rspec/rspec-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rspec","download_url":"https://codeload.github.com/rspec/rspec-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspec%2Frspec-core/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268322125,"owners_count":24231816,"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","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-09-24T14:21:54.397Z","updated_at":"2025-08-06T13:31:26.885Z","avatar_url":"https://github.com/rspec.png","language":"Ruby","readme":"# rspec-core [![Build Status](https://github.com/rspec/rspec-core/workflows/RSpec%20CI/badge.svg)](https://github.com/rspec/rspec-core/actions) [![Code Climate](https://codeclimate.com/github/rspec/rspec-core.svg)](https://codeclimate.com/github/rspec/rspec-core)\n\nrspec-core provides the structure for writing executable examples of how your\ncode should behave, and an `rspec` command with tools to constrain which\nexamples get run and tailor the output.\n\n**This is the old rspec core 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-core # for rspec-core only\n    rspec --help\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 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\n## Basic Structure\n\nRSpec uses the words \"describe\" and \"it\" so we can express concepts like a conversation:\n\n    \"Describe an order.\"\n    \"It sums the prices of its line items.\"\n\n```ruby\nRSpec.describe Order do\n  it \"sums the prices of its line items\" do\n    order = Order.new\n\n    order.add_entry(LineItem.new(:item =\u003e Item.new(\n      :price =\u003e Money.new(1.11, :USD)\n    )))\n    order.add_entry(LineItem.new(:item =\u003e Item.new(\n      :price =\u003e Money.new(2.22, :USD),\n      :quantity =\u003e 2\n    )))\n\n    expect(order.total).to eq(Money.new(5.55, :USD))\n  end\nend\n```\n\nThe `describe` method creates an [ExampleGroup](http://rubydoc.info/gems/rspec-core/RSpec/Core/ExampleGroup).  Within the\nblock passed to `describe` you can declare examples using the `it` method.\n\nUnder the hood, an example group is a class in which the block passed to\n`describe` is evaluated. The blocks passed to `it` are evaluated in the\ncontext of an _instance_ of that class.\n\n## Nested Groups\n\nYou can also declare nested groups using the `describe` or `context`\nmethods:\n\n```ruby\nRSpec.describe Order do\n  context \"with no items\" do\n    it \"behaves one way\" do\n      # ...\n    end\n  end\n\n  context \"with one item\" do\n    it \"behaves another way\" do\n      # ...\n    end\n  end\nend\n```\n\nNested groups are subclasses of the outer example group class, providing\nthe inheritance semantics you'd want for free.\n\n## Aliases\n\nYou can declare example groups using either `describe` or `context`.\nFor a top level example group, `describe` and `context` are available\noff of `RSpec`. For backwards compatibility, they are also available\noff of the `main` object and `Module` unless you disable monkey\npatching.\n\nYou can declare examples within a group using any of `it`, `specify`, or\n`example`.\n\n## Shared Examples and Contexts\n\nDeclare a shared example group using `shared_examples`, and then include it\nin any group using `include_examples`.\n\n```ruby\nRSpec.shared_examples \"collections\" do |collection_class|\n  it \"is empty when first created\" do\n    expect(collection_class.new).to be_empty\n  end\nend\n\nRSpec.describe Array do\n  include_examples \"collections\", Array\nend\n\nRSpec.describe Hash do\n  include_examples \"collections\", Hash\nend\n```\n\nNearly anything that can be declared within an example group can be declared\nwithin a shared example group. This includes `before`, `after`, and `around`\nhooks, `let` declarations, and nested groups/contexts.\n\nYou can also use the names `shared_context` and `include_context`. These are\npretty much the same as `shared_examples` and `include_examples`, providing\nmore accurate naming when you share hooks, `let` declarations, helper methods,\netc, but no examples.\n\nIf you want to reuse shared examples or contexts across your RSpec suite you can\ndefine them in a stand alone _*.rb_ files (_spec/support/shared_examples/definition.rb_\nfor example). But you will have to manually `require` them (there is no autoloading of\n_spec/support/_ directory unless you set it up yourself).\n\n## Metadata\n\nrspec-core stores a metadata hash with every example and group, which\ncontains their descriptions, the locations at which they were\ndeclared, etc, etc. This hash powers many of rspec-core's features,\nincluding output formatters (which access descriptions and locations),\nand filtering before and after hooks.\n\nAlthough you probably won't ever need this unless you are writing an\nextension, you can access it from an example like this:\n\n```ruby\nit \"does something\" do |example|\n  expect(example.metadata[:description]).to eq(\"does something\")\nend\n```\n\n### `described_class`\n\nWhen a class is passed to `describe`, you can access it from an example\nusing the `described_class` method, which is a wrapper for\n`example.metadata[:described_class]`.\n\n```ruby\nRSpec.describe Widget do\n  example do\n    expect(described_class).to equal(Widget)\n  end\nend\n```\n\nThis is useful in extensions or shared example groups in which the specific\nclass is unknown. Taking the collections shared example group from above, we can\nclean it up a bit using `described_class`:\n\n```ruby\nRSpec.shared_examples \"collections\" do\n  it \"is empty when first created\" do\n    expect(described_class.new).to be_empty\n  end\nend\n\nRSpec.describe Array do\n  include_examples \"collections\"\nend\n\nRSpec.describe Hash do\n  include_examples \"collections\"\nend\n```\n\n## A Word on Scope\n\nRSpec has two scopes:\n\n* **Example Group**: Example groups are defined by a `describe` or\n  `context` block, which is eagerly evaluated when the spec file is\n  loaded. The block is evaluated in the context of a subclass of\n  `RSpec::Core::ExampleGroup`, or a subclass of the parent example group\n  when you're nesting them.\n* **Example**: Examples -- typically defined by an `it` block -- and any other\n  blocks with per-example semantics -- such as a `before(:example)` hook -- are\n  evaluated in the context of\n  an _instance_ of the example group class to which the example belongs.\n  Examples are _not_ executed when the spec file is loaded; instead,\n  RSpec waits to run any examples until all spec files have been loaded,\n  at which point it can apply filtering, randomization, etc.\n\nTo make this more concrete, consider this code snippet:\n\n``` ruby\nRSpec.describe \"Using an array as a stack\" do\n  def build_stack\n    []\n  end\n\n  before(:example) do\n    @stack = build_stack\n  end\n\n  it 'is initially empty' do\n    expect(@stack).to be_empty\n  end\n\n  context \"after an item has been pushed\" do\n    before(:example) do\n      @stack.push :item\n    end\n\n    it 'allows the pushed item to be popped' do\n      expect(@stack.pop).to eq(:item)\n    end\n  end\nend\n```\n\nUnder the covers, this is (roughly) equivalent to:\n\n``` ruby\nclass UsingAnArrayAsAStack \u003c RSpec::Core::ExampleGroup\n  def build_stack\n    []\n  end\n\n  def before_example_1\n    @stack = build_stack\n  end\n\n  def it_is_initially_empty\n    expect(@stack).to be_empty\n  end\n\n  class AfterAnItemHasBeenPushed \u003c self\n    def before_example_2\n      @stack.push :item\n    end\n\n    def it_allows_the_pushed_item_to_be_popped\n      expect(@stack.pop).to eq(:item)\n    end\n  end\nend\n```\n\nTo run these examples, RSpec would (roughly) do the following:\n\n``` ruby\nexample_1 = UsingAnArrayAsAStack.new\nexample_1.before_example_1\nexample_1.it_is_initially_empty\n\nexample_2 = UsingAnArrayAsAStack::AfterAnItemHasBeenPushed.new\nexample_2.before_example_1\nexample_2.before_example_2\nexample_2.it_allows_the_pushed_item_to_be_popped\n```\n\n## The `rspec` Command\n\nWhen you install the rspec-core gem, it installs the `rspec` executable,\nwhich you'll use to run rspec. The `rspec` command comes with many useful\noptions.\nRun `rspec --help` to see the complete list.\n\n## Store Command Line Options `.rspec`\n\nYou can store command line options in a `.rspec` file in the project's root\ndirectory, and the `rspec` command will read them as though you typed them on\nthe command line.\n\n## Get Started\n\nStart with a simple example of behavior you expect from your system. Do\nthis before you write any implementation code:\n\n```ruby\n# in spec/calculator_spec.rb\nRSpec.describe Calculator do\n  describe '#add' do\n    it 'returns the sum of its arguments' do\n      expect(Calculator.new.add(1, 2)).to eq(3)\n    end\n  end\nend\n```\n\nRun this with the rspec command, and watch it fail:\n\n```\n$ rspec spec/calculator_spec.rb\n./spec/calculator_spec.rb:1: uninitialized constant Calculator\n```\n\nAddress the failure by defining a skeleton of the `Calculator` class:\n\n```ruby\n# in lib/calculator.rb\nclass Calculator\n  def add(a, b)\n  end\nend\n```\n\nBe sure to require the implementation file in the spec:\n\n```ruby\n# in spec/calculator_spec.rb\n# - RSpec adds ./lib to the $LOAD_PATH\nrequire \"calculator\"\n```\n\nNow run the spec again, and watch the expectation fail:\n\n```\n$ rspec spec/calculator_spec.rb\nF\n\nFailures:\n\n  1) Calculator#add returns the sum of its arguments\n     Failure/Error: expect(Calculator.new.add(1, 2)).to eq(3)\n\n       expected: 3\n            got: nil\n\n       (compared using ==)\n     # ./spec/calculator_spec.rb:6:in `block (3 levels) in \u003ctop (required)\u003e'\n\nFinished in 0.00131 seconds (files took 0.10968 seconds to load)\n1 example, 1 failure\n\nFailed examples:\n\nrspec ./spec/calculator_spec.rb:5 # Calculator#add returns the sum of its arguments\n```\n\nImplement the simplest solution, by changing the definition of `Calculator#add` to:\n\n```ruby\ndef add(a, b)\n  a + b\nend\n```\n\nNow run the spec again, and watch it pass:\n\n```\n$ rspec spec/calculator_spec.rb\n.\n\nFinished in 0.000315 seconds\n1 example, 0 failures\n```\n\nUse the `documentation` formatter to see the resulting spec:\n\n```\n$ rspec spec/calculator_spec.rb --format doc\nCalculator\n  #add\n    returns the sum of its arguments\n\nFinished in 0.000379 seconds\n1 example, 0 failures\n```\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\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## Also see\n\n* [https://github.com/rspec/rspec-metagem](https://github.com/rspec/rspec-metagem)\n* [https://github.com/rspec/rspec-expectations](https://github.com/rspec/rspec-expectations)\n* [https://github.com/rspec/rspec-mocks](https://github.com/rspec/rspec-mocks)\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":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspec%2Frspec-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frspec%2Frspec-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspec%2Frspec-core/lists"}