{"id":35211817,"url":"https://github.com/sleepingkingstudios/rspec-sleeping_king_studios","last_synced_at":"2026-03-17T20:03:55.105Z","repository":{"id":7183557,"uuid":"8486138","full_name":"sleepingkingstudios/rspec-sleeping_king_studios","owner":"sleepingkingstudios","description":"A collection of RSpec patches and custom matchers.","archived":false,"fork":false,"pushed_at":"2026-02-21T01:17:59.000Z","size":1361,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-21T07:20:42.781Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/sleepingkingstudios.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2013-02-28T19:18:04.000Z","updated_at":"2026-02-21T01:17:35.000Z","dependencies_parsed_at":"2024-05-12T18:42:04.860Z","dependency_job_id":"d96e6f3e-cf45-4d95-b717-70b054c7e4db","html_url":"https://github.com/sleepingkingstudios/rspec-sleeping_king_studios","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/sleepingkingstudios/rspec-sleeping_king_studios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepingkingstudios%2Frspec-sleeping_king_studios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepingkingstudios%2Frspec-sleeping_king_studios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepingkingstudios%2Frspec-sleeping_king_studios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepingkingstudios%2Frspec-sleeping_king_studios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sleepingkingstudios","download_url":"https://codeload.github.com/sleepingkingstudios/rspec-sleeping_king_studios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepingkingstudios%2Frspec-sleeping_king_studios/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30630034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T17:32:55.572Z","status":"ssl_error","status_checked_at":"2026-03-17T17:32:38.732Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2025-12-29T19:00:56.008Z","updated_at":"2026-03-17T20:03:55.074Z","avatar_url":"https://github.com/sleepingkingstudios.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RSpec::SleepingKingStudios\n\nA collection of matchers and extensions to ease TDD/BDD using RSpec. Extends built-in matchers with new functionality, such as support for Ruby 2.0+ keyword arguments, and adds new matchers for testing boolean-ness, object reader/writer properties, object constructor arguments, ActiveModel validations, and more. Also defines shared example groups for more expressive testing.\n\n\u003cblockquote\u003e\n  Read The\n  \u003ca href=\"https://www.sleepingkingstudios.com/rspec-sleeping_king_studios\" target=\"_blank\"\u003e\n    Documentation\n  \u003c/a\u003e\n\u003c/blockquote\u003e\n\n## About\n\n### Setup\n\nTo add support for `RSpec::SleepingKingStudios` extensions to `rubocop-rspec`, add the following to your `.rubocop.yml` configuration file:\n\n```yml\ninherit_gem:\n  rspec-sleeping_king_studios: 'config/rubocop-rspec.yml'\n```\n\n### Compatibility\n\nRSpec::SleepingKingStudios is tested against the following dependencies:\n\n- Ruby (MRI) 3.1 through 3.4\n- RSpec versions 3.9 through 3.13\n- ActiveModel versions 6.1 through 8.0\n\n### Documentation\n\nDocumentation is generated using [YARD](https://yardoc.org/), and can be generated locally using the `yard` gem.\n\n### License\n\nCopyright (c) 2013-2025 Rob Smith\n\nRSpec::SleepingKingStudios is released under the [MIT License](https://opensource.org/licenses/MIT).\n\n### Contribute\n\nThe canonical repository for this gem is located at https://github.com/sleepingkingstudios/rspec-sleeping_king_studios.\n\nTo report a bug or submit a feature request, please use the [Issue Tracker](https://github.com/sleepingkingstudios/rspec-sleeping_king_studios/issues).\n\nTo contribute code, please fork the repository, make the desired updates, and then provide a [Pull Request](https://github.com/sleepingkingstudios/rspec-sleeping_king_studios/pulls). Pull requests must include appropriate tests for consideration, and all code must be properly formatted.\n\n### Code of Conduct\n\nPlease note that the `RSpec::SleepingKingStudios` project is released with a [Contributor Code of Conduct](https://github.com/sleepingkingstudios/rspec-sleeping_king_studios/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.\n\n## Configuration\n\nRSpec::SleepingKingStudios now has configuration options available through `RSpec.configuration`. For example, to set the behavior of the matcher examples when a failure message expectation is undefined (see RSpec Matcher Examples, below), put the following in your `spec_helper` or other configuration file:\n\n    RSpec.configure do |config|\n      config.sleeping_king_studios do |config|\n        # RSpec::SleepingKingStudios configuration can be set here.\n      end # config\n    end # config\n\n### Configuration Options\n\n#### Examples\n\n##### Handle Missing Failure Message With\n\n    RSpec.configure do |config|\n      config.sleeping_king_studios do |config|\n        config.examples do |config|\n          config.handle_missing_failure_message_with = :ignore\n        end # config\n      end # config\n    end # config\n\nThis option is used with the RSpec matcher examples (see Examples, below), and determines the behavior when a matcher is expected to fail, but the corresponding failure message is not defined (via `let(:failure_message)` or `let(:failure_message_when_negated)`). The default option is `:pending`, which marks the generated example as skipped (and will show up as pending in the formatter). Other options include `:ignore`, which marks the generated example as passing, and `:exception`, which marks the generated example as failing.\n\n##### Match String Failure Message As\n\n    RSpec.configure do |config|\n      config.sleeping_king_studios do |config|\n        config.examples do |config|\n          config.match_string_failure_message_as = :exact\n        end # config\n      end # config\n    end # config\n\nThis option is used with the RSpec matcher examples (see Examples, below), and determines whether an expected failure message is matched against the actual failure message as an exact match or as a substring. The default option is `:substring`, which means that any failure message that contains the expected message as a substring will match. Alternatively, setting the option to `:exact` will mean that only a failure message that is an exact match for the expected message will match.\n\n#### Matchers\n\n##### Allow Empty Include Matchers\n\n    RSpec.configure do |config|\n      config.sleeping_king_studios do |config|\n        config.matchers do |config|\n          config.allow_empty_include_matchers = false\n        end # config\n      end # config\n    end # config\n\nThis option is used with the IncludeMatcher (see `#include`, below). If this option is set to false, an ArgumentError will be raised when attempting to instantiate an IncludeMatcher without any expectations.\n\nThis prevents an insidious bug when using the `do..end` block syntax to create a block expectation while the matcher macro is itself an argument to another function, such as ExpectationTarget#to. This bug causes the block to be silently ignored and any enumerable object to match against the matcher, even an empty object.\n\n##### Strict Predicate Matching\n\n    RSpec.configure do |config|\n      config.sleeping_king_studios do |config|\n        config.matchers do |config|\n          config.strict_predicate_matching = true\n        end # config\n      end # config\n    end # config\n\nThis option is used with the HavePredicateMatcher (see `#have_predicate`, below). If set to true, ensures that any method that is expected to be a predicate will return either true or false. The matcher will fail if the method returns any other value. The default value is false, which allows for loose matching of predicate methods.\n\n## Concerns\n\nRSpec::SleepingKingStudios defines a few concerns that can be included in or extended into modules or example groups for additional functionality.\n\n### Example Constants\n\n    require 'rspec/sleeping_king_studios/concerns/example_constants'\n\n    RSpec.describe 'constants' do\n      extend RSpec::SleepingKingStudios::Concerns::ExampleConstants\n\n      example_constant 'THE_ANSWER', 42\n\n      example_class 'Spec::Examples::Question' do |klass|\n        value = help_string\n\n        klass.send(:define_method, :answer) { THE_ANSWER }\n        klass.send(:define_method, :help)   { value }\n      end # example_class\n\n      let(:described_class) { Spec::Examples::Question }\n      let(:instance)        { described_class.new }\n      let(:help_string) do\n        \"It looks like you're defining a class. Would you like help?\"\n      end # let\n\n      it { expect(described_class.name).to be == 'Spec::Examples::Question' }\n\n      it { expect(instance.answer).to be THE_ANSWER }\n\n      it { expect(instance.help).to be == help_string }\n    end # describe\n\nProvides a programmatic way to define temporary constants and classes scoped to the current example.\n\n#### `::example_constant`\n\n`param constant_name [String, Symbol]` The name of the constant. Can be a qualified name separated by :: (e.g. `'Spec::Examples::Question'`), in which case any missing modules will be temporarily set as well.\n\n`param constant_value` Defaults to nil. If the constant value is not set and a block is given, the block will be executed in the context of the example (so previously-set constants will be available, as well as example features such as the values of `let` blocks) and the value of the constant will be set to the result of the block call.\n\n`option force [Boolean]` Defaults to false. If the constant is already defined, trying to set the constant value will raise an error unless the force option is set to true.\n\nSets the value of the named constant to the specified value within the context of the current example.\n\n#### `::example_class`\n\n`param constant_name [String, Symbol]` The name of the constant. Can be a qualified name separated by :: (e.g. `'Spec::Examples::Question'`), in which case any missing modules will be temporarily set as well.\n\n`option base_class [Class]` Defaults to Object. The base class of the generated class.\n\n`yield klass [Class]` If a block is given, it is executed in the context of the example (so previously-set constants will be available, as well as example features such as the values of `let` blocks) and yielded the class.\n\nCreates a new class with the specified base class and sets the value of the named constant to the created class within the context of the current example.\n\n\u003ca id=\"include-contract\"\u003e\u003c/a\u003e\n\n### Include Contract\n\n```ruby\nrequire 'rspec/sleepingkingstudios/concerns/include_contract'\n```\n\nDefines helpers for including reusable contracts in RSpec example groups.\n\nContracts are a mechanism for sharing tests between projects. For example, one library may define an interface or specification for a type of object, while a second library implements that object. By defining a contract and sharing that contract as part of the library, the developer ensures that any object that matches the contract has correctly implemented and conforms to the interface. This reduces duplication of tests and provides resiliency as an interface is developed over time and across versions of the library.\n\nMechanically speaking, each contract encapsulates a section of RSpec code. When the contract is included in a spec, that code is then injected into the spec. Writing a contract, therefore, is no different than writing any other RSpec specification - it is only the delivery mechanism that differs. A contract can be any object that responds to #to_proc; the simplest contract is therefore a Proc or lambda that contains some RSpec code.\n\nAlthough the examples use bare `lambda`s, any object that responds to `#to_proc` can be used as a contract. See also [Contracts](#contracts), which provide an approach to defining contracts that makes documenting contracts much cleaner.\n\n```ruby\nmodule ExampleContracts\n  # This contract asserts that the object has the Enumerable module as an\n  # ancestor, and that it responds to the #each method.\n  SHOULD_BE_ENUMERABLE_CONTRACT = lambda do\n    it 'should be Enumerable' do\n      expect(subject).to be_a Enumerable\n    end\n\n    it 'should respond to #each' do\n      expect(subject).to respond_to(:each).with(0).arguments\n    end\n  end\nend\n\nRSpec.describe Array do\n  extend RSpec::SleepingKingStudios::Concerns::IncludeContract\n\n  include_contract ExampleContracts::SHOULD_BE_ENUMERABLE_CONTRACT\nend\n\nRSpec.describe Hash do\n  extend  RSpec::SleepingKingStudios::Concerns::IncludeContract\n  include ExampleContracts\n\n  include_contract 'should be enumerable'\nend\n```\n\nWe can also write contracts that take parameters, allowing us to customize the expected behavior of the object.\n\n```ruby\nmodule SerializerContracts\n  # This contract asserts that the serialized result has the expected values.\n  SHOULD_SERIALIZE_ATTRIBUTES_CONTRACT = lambda \\\n  do |*attributes, **values, \u0026block|\n    describe '#serialize' do\n      let(:serialized) { subject.serialize }\n\n      it { expect(subject).to respond_to(:serialize).with(0).arguments }\n\n      attributes.each do |attribute|\n        it \"should serialize #{attribute}\" do\n          expect(serialized[attribute]).to be == subject[attribute]\n        end\n      end\n\n      values.each do |attribute, value|\n        it \"should serialize #{attribute}\" do\n          expect(serialized[attribute]).to be == value\n        end\n      end\n\n      instance_exec(\u0026block) if block\n    end\n  end\nend\n\nRSpec.describe CaptainPicard do\n  extend  RSpec::SleepingKingStudios::Concerns::IncludeContract\n  include SerializerContracts\n\n  include_contract 'should serialize attributes',\n    :name,\n    :rank,\n    lights: 4 do\n      it 'should serialize the catchphrase' do\n        expect(serialized[:catchphrase]).to be == 'Make it so.'\n      end\n  end\nend\n```\n\nFirst, we pass the contract a series of attribute names. These are used to assert that the serialized attributes match the values on the original object.\n\nSecond, we pass the contract a set of attribute names and values. These are used to assert that the serialized attributes have the specified values.\n\nFinally, we can pass the contract a block, which the contract then executes. Note that the block is executed in the context of our describe block, and thus can take advantage of our memoized #serialized helper method.\n\n#### `.include_contract`\n\nThe `.include_contract` class method applies the contract to the current example group. It passes any additional arguments, keywords, or block to the contract implementation.\n\n#### `.finclude_contract`\n\nThe `.finclude_contract` class method creates a new focused context inside the current example group and applies the contract to that context. If RSpec is configured to run only focused specs, then only the contract specs will be run. This is useful to quickly focus and run the specs from a particular contract.\n\n#### `.xinclude_contract`\n\nThe `.xinclude_contract` class method creates a new skipped context inside the current example group and applies the contract to that context. The contract specs will not be run, but will instead be marked as pending. This is useful to temporarily disable the specs from a particular contract.\n\n### Focus Examples\n\n    require 'rspec/sleeping_king_studios/concerns/focus_examples'\n\n    RSpec.describe String do\n      extend RSpec::SleepingKingStudios::Concerns::FocusExamples\n\n      shared_examples 'should be a greeting' do\n        it { expect(salutation).to be =~ /greeting/i }\n      end # shared_examples\n\n      shared_examples 'should greet the user by name' do\n        it { expect(salutation).to match user.name }\n      end # shared_examples\n\n      let(:salutation) { 'Greetings, programs!' }\n\n      # Focused example groups are always run when config.filter_run :focus is\n      # set to true.\n      finclude_examples 'should be a greeting'\n\n      # Skipped example groups are marked as pending and never run.\n      xinclude_examples 'should greet the user by name'\n    end # describe\n\nA shorthand for focusing or skipping included shared example groups with a single keystroke, e.g. `include_examples '...'` =\u003e `finclude_examples '...'`.\n\nA simplified syntax for re-using shared context or examples without having to explicitly wrap them in `describe` blocks or allowing memoized values or callbacks to change the containing context. In the example above, if the programmer had used the standard `include_context` instead, the first expectation would have failed, as the value of :quote would have been overwritten.\n\n*Important Note:* Do not use these methods with example groups that have side effects, e.g. that define a memoized `#let` helper or a `#before` block that is intended to modify the behavior of sibling examples. Wrapping the example group in a `describe` block breaks that relationship. Best practice is to use the `#wrap_examples` method to safely encapsulate example groups with side effects, and the `#fwrap_examples` method to automatically focus such groups.\n\n#### `::finclude_examples`\n\n(also `::finclude_context`) A shortcut for focusing the example group by wrapping it in a `describe` block, similar to the built-in `fit` and `fdescribe` methods.\n\n#### `::xinclude_examples`\n\n(also `::xinclude_context`) A shortcut for skipping the example group by wrapping it in a `describe` block, similar to the built-in `xit` and `xdescribe` methods.\n\n### Memoized Helpers\n\n```ruby\nrequire 'rspec/sleepingkingstudios/concerns/memoized_helpers'\n```\n\nMethods for defining memoized helpers, similar to the core RSpec `let` method.\n\n#### `.let?`\n\nThe `.let?` class method defines a memoized helper if and only if there is not an existing method with the same name defined in the example group. Among other use cases, this allows for defining default values in shared examples.\n\n```ruby\nRSpec.describe Rocket do\n  subject(:rocket) { described_class.new(name: 'Imp IV') }\n\n  shared_examples 'should launch the rocket' do\n    let?(:launch_site) { 'KSC' }\n\n    it 'should launch the rocket' do\n      expect { rocket.launch_from(launch_site) }\n        .to change(rocket, :launched?)\n        .to be true\n    end\n  end\n\n  describe '#launch_from' do\n    include_examples 'should launch the rocket'\n\n    describe 'with launch_site: value' do\n      let(:launch_site) { 'Baikerbanur' }\n\n      include_examples 'should launch the rocket'\n    end\n  end\nend\n```\n\n### Shared Example Groups\n\n    require 'rspec/sleeping_king_studios/concerns/shared_example_group'\n\n    module MyCustomExamples\n      extend RSpec::SleepingKingStudios::Concerns::SharedExampleGroup\n\n      shared_examples 'has custom behavior' do\n        # Define expectations here...\n      end # shared_examples\n      alias_shared_examples 'should have custom behavior', 'has custom behavior'\n    end # module\n\nUtility functions for defining shared examples. If included in a module, any shared examples defined in that module are scoped to the module, rather than placed in a global scope. This allows you to define different shared examples with the same name in different contexts, similar to the current behavior when defining a shared example inside an example group. To use the defined examples, simply `include` the module in an example group. **Important Note:** Shared examples and aliases must be defined **before** including the module in an example group. Any shared examples or aliases defined afterword will not be available inside the example group.\n\n#### `::alias_shared_examples`\n\n(also `::alias_shared_context`) Aliases a defined shared example group, allowing it to be accessed using a new name. The example group must be defined in the current context using `shared_examples`. The aliases must be defined before including the module into an example group, or they will not be available in the example group.\n\n#### `::shared_examples`\n\n(also `::shared_context`) Defines a shared example group within the context of the current module. Unlike a top-level example group defined using RSpec#shared_examples, these examples are not globally available, and must be mixed into an example group by including the module. The shared examples must be defined before including the module, or they will not be available in the example group.\n\n### Toolbelt\n\n    require 'rspec/sleeping_king_studios/concerns/toolbelt'\n\n    RSpec.describe \"a String\" do\n      include RSpec::SleepingKingStudios::Concerns::Toolbelt\n\n      shared_examples 'should process' do |string|\n        singular = tools.string.singularize(string)\n        plural   = tools.string.pluralize(string)\n\n        it \"should singularize #{string} to #{singular}\" do\n          expect(tools.singularize string).to be_a String\n        end # it\n\n        it \"should pluralize #{string} to #{plural}\" do\n          expect(tools.pluralize string).to be_a String\n        end # it\n      end # shared_examples\n\n      include_examples 'should pluralize', 'light'\n    end # describe\n\nA helper module for exposing SleepingKingStudios::Tools methods in examples and example groups.\n\n### Wrap Environment\n\n    require 'rspec/sleeping_king_studios/concerns/wrap_env'\n\n    RSpec.describe 'environment' do\n      include RSpec::SleepingKingStudios::Concerns::WrapEnv\n\n      it { expect(ENV['VAR_NAME']).to be nil }\n\n      context 'when the variable is set in the example group' do\n        wrap_env 'VAR_NAME', 'custom_value'\n\n        it { expect(ENV['VAR_NAME']).to be == 'custom_value' }\n      end # context\n\n      context 'when the variable is set in the example group with a block' do\n        let(:calculated_value) { 'calculated_value' }\n\n        wrap_env('VAR_NAME') { calculated_value }\n\n        it { expect(ENV['VAR_NAME']).to be == calculated_value }\n      end # context\n\n      context 'when the variable is set inside an example' do\n        it 'should set the variable' do\n          expect(ENV['VAR_NAME']).to be nil\n\n          begin\n            wrap_env('VAR_NAME', 'new_value') do\n              expect(ENV['VAR_NAME']).to be == 'new_value'\n\n              raise RuntimeError, 'must handle errors and reset the var'\n            end # wrap_env\n          rescue RuntimeError\n          end # begin-rescue\n\n          expect(ENV['VAR_NAME']).to be nil\n        end # it\n      end # context\n    end # describe\n\nProvides helper methods for temporarily overwriting values in the environment, which are safely and automatically reset after the example or block.\n\n### Wrap Examples\n\n    require 'rspec/sleeping_king_studios/concerns/wrap_examples'\n\n    RSpec.describe String do\n      extend RSpec::SleepingKingStudios::Concerns::WrapExamples\n\n      shared_context 'with a long quote' do\n        let(:quote) do\n          'Greetings, starfighter! You have been recruited by the Star League'\\\n          ' to defend the frontier against Xur and the Ko-Dan armada!'\n        end # let\n      end # shared context\n\n      shared_context 'with a short quote' do`\n        let(:quote) { 'Greetings, programs!' }\n      end # shared_context\n\n      describe '#length' do\n        wrap_context 'with a long quote' do\n          it { expect(quote.length).to be == 124 }\n        end # wrap_context\n\n        wrap_context 'with a short quote' do\n          it { expect(quote.length).to be == 20 }\n        end # wrap_context\n      end # describe\n    end # describe\n\nA simplified syntax for re-using shared context or examples without having to explicitly wrap them in `describe` blocks or allowing memoized values or callbacks to change the containing context. In the example above, if the programmer had used the standard `include_context` instead, the first expectation would have failed, as the value of :quote would have been overwritten.\n\n#### `::wrap_examples`\n\n(also `::wrap_context`) Creates an implicit `describe` block and includes the context or examples within the `describe` block to avoid leaking values or callbacks to the outer context. Any parameters or keywords will be passed along to the `include_examples` call. If a block is given, it is evaluated in the context of the `describe` block after the `include_examples` call, allowing you to define additional examples or customize the values and callbacks defined in the shared examples.\n\n#### `::fwrap_examples`\n\n(also `::fwrap_context`) A shortcut for wrapping the context or examples in an automatically-focused `describe` block, similar to the built-in `fit` and `fdescribe` methods.\n\n#### `::xwrap_examples`\n\n(also `::xwrap_context`) A shortcut for wrapping the context or examples in an automatically-skipped `describe` block, similar to the built-in `xit` and `xdescribe` methods.\n\n## Contracts\n\n```ruby\nrequire 'rspec/sleeping_king_studios/contract'\n```\n\nAn `RSpec::SleepingKingStudios::Contract` object encapsulates a partial RSpec specification. Unlike a traditional shared example group, a contract can be reused across projects, allowing a library to define an interface, provide a reference implementation, and publish tests that validate other implementations.\n\nContracts can be added to an example group either through the `.apply` method or using the [Include Contract concern](#include-contract).\n\n```ruby\nmodule ExampleContracts\n  # This contract asserts that the object has the Enumerable module as an\n  # ancestor, and that it responds to the #each method.\n  class ShouldBeEnumerableContract\n    extend RSpec::SleepingKingStudios::Contract\n\n    # @!method apply(example_group)\n    #   Adds the contract to the example group.\n\n    contract do\n      it 'should be Enumerable' do\n        expect(subject).to be_a Enumerable\n      end\n\n      it 'should respond to #each' do\n        expect(subject).to respond_to(:each).with(0).arguments\n      end\n    end\n  end\nend\n\nRSpec.describe Array do\n  ExampleContracts::SHOULD_BE_ENUMERABLE_CONTRACT.apply(self)\nend\n\nRSpec.describe Hash do\n  extend  RSpec::SleepingKingStudios::Concerns::IncludeContract\n  include ExampleContracts\n\n  include_contract 'should be enumerable'\nend\n```\n\nThe major advantage a Contract object provides over using a Proc is documentation - tools such as YARD do not gracefully handle bare lambdas, while the functionality and requirements of a Contract can be specified using standard patterns, such as documenting the parameters passed to a contract using the #apply method.\n\nContracts can be defined with parameters, which allows us to customize the expected behavior of the object.\n\n```ruby\nmodule SerializerContracts\n  # This contract asserts that the serialized result has the expected\n  # values.\n  #\n  # First, we pass the contract a series of attribute names. These are\n  # used to assert that the serialized attributes match the values on the\n  # original object.\n  #\n  # Second, we pass the contract a set of attribute names and values.\n  # These are used to assert that the serialized attributes have the\n  # specified values.\n  #\n  # Finally, we can pass the contract a block, which the contract then\n  # executes. Note that the block is executed in the context of our\n  # describe block, and thus can take advantage of our memoized\n  # #serialized helper method.\n  class ShouldSerializeAttributesContract\n    extend RSpec::SleepingKingStudios::Contract\n\n    contract do |*attributes, **values, \u0026block|\n      describe '#serialize' do\n        let(:serialized) { subject.serialize }\n\n        it { expect(subject).to respond_to(:serialize).with(0).arguments }\n\n        attributes.each do |attribute|\n          it \"should serialize #{attribute}\" do\n            expect(serialized[attribute]).to be == subject[attribute]\n          end\n        end\n\n        values.each do |attribute, value|\n          it \"should serialize #{attribute}\" do\n            expect(serialized[attribute]).to be == value\n          end\n        end\n\n        instance_exec(\u0026block) if block\n      end\n    end\n  end\n\nRSpec.describe CaptainPicard do\n  SerializerContracts::ShouldSerializeAttributesContract.apply(\n    self,\n    :name,\n    :rank,\n    lights: 4) \\\n  do\n    it 'should serialize the catchphrase' do\n      expect(serialized[:catchphrase]).to be == 'Make it so.'\n    end\n  end\nend\n```\n\n### Contract Methods\n\nEach `RSpec::SleepingKingStudios::Contract` defines the following methods.\n\n#### `.apply`\n\nThe `.apply` method adds the contract to the given example group, using the same internals used in the [Include Contract concern](#include-contract).\n\n```ruby\nRSpec.describe Book do\n  subject(:book) { Book.first }\n\n  SerializerContracts::ShouldSerializeAttributesContract.apply(\n    self,\n    :title,\n    author: book.author.as_json\n  )\nend\n```\n\n#### `.contract`\n\nThe `.contract` method is used to define the contract implementation.\n\n```ruby\nmodule ModelContracts\n  class ShouldHavePrimaryKey\n    extend RSpec::SleepingKingStudios::Contract\n\n    contract do |primary_key_name: :id|\n      describe \"##{primary_key_name}\" do\n        it { expect(subject).to respond_to(primary_key_name).with(0).arguments }\n      end\n    end\n  end\nend\n```\n\nIf a block is not given, it returns the current implementation as a `Proc` (or `nil`, if a contract implementation has not yet been set).\n\n#### `.to_proc`\n\nThe `.to_proc` method returns the current implementation as a `Proc` (or `nil`, if a contract implementation has not yet been set).\n\n## Matchers\n\nTo enable a custom matcher, simply require the associated file. Matchers can be required individually or by category:\n\n    require 'rspec/sleeping_king_studios/all'\n    #=\u003e requires all features, including matchers\n\n    require 'rspec/sleeping_king_studios/matchers/core/all'\n    #=\u003e requires all of the core matchers\n\n    require 'rspec/sleeping_king_studios/matchers/core/construct'\n    #=\u003e requires only the :construct matcher\n\nAs of version 2.2, you can also load only the matcher, without adding the associated macro to your example groups. This can be useful in case of naming conflicts with other libraries, or if you need only the matcher in isolation.\n\n    require 'rspec/sleeping_king_studios/matchers/core/be_boolean_matcher'\n    #=\u003e requires the matcher itself as RSpec::SleepingKingStudios::Matchers::Core::BeBooleanMatcher,\n    #   but does not add a #be_boolean macro to example groups.\n\n### ActiveModel\n\n    require 'rspec/sleeping_king_studios/matchers/active_model/all'\n\nThese matchers validate ActiveModel functionality, such as validations.\n\n#### `#have_errors` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/active_model/have_errors'\n\nVerifies that the actual object has validation errors. Optionally can specify individual fields to validate, or even specific messages for each attribute.\n\n**How To Use:**\n\n    expect(instance).to have_errors\n\n    expect(instance).to have_errors.on(:name)\n\n    expect(instance).to have_errors.on(:name).with_message('not to be nil')\n\n**Chaining:**\n\n* **`#on`:** [String, Symbol] Adds a field to validate; the matcher only passes if all validated fields have errors.\n* **`#with`:** [Array\u003cString\u003e] Adds one or more messages to the previously-defined field validation. Raises ArgumentError if no field was previously set.\n* **`#with_message`:** [String] Adds a message to the previously-defined field validation. Raises ArgumentError if no field was previously set.\n* **`#with_messages`:** [Array\u003cString\u003e] Adds one or more messages to the previously-defined field validation. Raises ArgumentError if no field was previously set.\n\n### BuiltIn\n\n    require 'rspec/sleeping_king_studios/matchers/built_in/all'\n\nThese extend the built-in RSpec matchers with additional functionality.\n\n#### `#be_kind_of` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/built_in/be_kind_of'\n\nNow accepts an Array of types. The matcher passes if the actual object is any of the parameter types.\n\nAlso allows nil parameter as a shortcut for NilClass.\n\n**How To Use:**\n\n    expect(instance).to be_kind_of [String, Symbol, nil]\n    #=\u003e passes iff instance is a String, a Symbol, or is nil\n\n#### `#include` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/built_in/include'\n\nNow accepts Proc parameters; items in the actual object are passed into proc#call, with a truthy response considered a match to the item. In addition, now accepts an optional block as a shortcut for adding a proc expectation.\n\n**How To Use:**\n\n    expect(instance).to include { |item| item =~ /pattern/ }\n\n#### `#respond_to` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/built_in/respond_to'\n\nNow has additional chaining functionality to validate the number of arguments accepted by the method, the keyword arguments (if any) accepted by the method, and whether the method accepts a block argument.\n\n**How To Use:**\n\n    # With a block.\n    expect(instance).to respond_to(:foo).with_a_block.\n\n    # With a variable number of arguments and a block.\n    expect(instance).to respond_to(:foo).with(2..3).arguments.and_a_block\n\n    # With keyword arguments.\n    expect(instance).to respond_to(:foo).with_keywords(:bar, :baz)\n\n    # With both arguments and keywords.\n    expect(instance).to respond_to(:foo).with(2).arguments.and_keywords(:bar, :baz)\n\n**Chaining:**\n\n* **`#with`:** Expects at most one Integer or Range argument, and zero or more Symbol arguments corresponding to optional keywords. Verifies that the method accepts that keyword, or has a variadic keyword of the form `**kwargs`. As of 2.1.0 and required keywords, verifies that all required keywords are provided.\n* **`#with_unlimited_arguments`:** (also `and_unlimited_arguments`) No parameters. Verifies that the method accepts any number of arguments via a variadic argument of the form `*args`.\n* **`#with_a_block`:** (also `and_a_block`) No parameters. Verifies that the method requires a block argument of the form `\u0026my_argument`. _Important note:_ A negative result _does not_ mean the method cannot accept a block, merely that it does not require one. Also, _does not_ check whether the block is called or yielded.\n* **`#with_keywords`:** (also `and_keywords`) Expects one or more String or Symbol arguments. Verifies that the method accepts each provided keyword or has a variadic keyword of the form `**kwargs`. As of 2.1.0 and required keywords, verifies that all required keywords are provided.\n* **`#with_any_keywords`:** (also `and_any_keywords`, `and_arbitrary_keywords`, `and_arbitrary_keywords`) No parameters. Verifies that the method accepts any keyword arguments via a variadic keyword of the form `**kwargs`.\n\n### Core\n\n    require 'rspec/sleeping_king_studios/matchers/core/all'\n\nThese matchers check core functionality, such as object boolean-ness, the existence of properties, and so on.\n\n#### `#be_a_uuid` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/be_a_uuid'\n\n**Aliases:** `#a_uuid`.\n\n**How To Use:**\n\n    # With an object comparison.\n    expect(string).to be_a_uuid\n\n    # Inside a composable matcher.\n    expect(array).to include(a_uuid)\n\n**Parameters:** None.\n\n#### `#be_boolean` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/be_boolean'\n\nChecks if the provided object is true or false.\n\n**Aliases:** `#a_boolean`.\n\n**How To Use:**\n\n    # With an object comparison.\n    expect(object).to be_boolean\n\n    # Inside a composable matcher.\n    expect(array).to include(a_boolean)\n\n**Parameters:** None.\n\n#### `#construct` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/construct'\n\nVerifies that the actual object can be constructed using `::new`. Can take an optional number of arguments.\n\n**How To Use:**\n\n    # With an expected number of arguments.\n    expect(described_class).to construct.with(1).arguments\n\n    # With an expected number of arguments and set of keywords.\n    expect(instance).to construct.with(0, :bar, :baz)\n\n**Parameters:** None.\n\n**Chaining:**\n\n* **`#with`:** Expects one Integer, Range, or nil argument, and zero or more Symbol arguments corresponding to optional keywords. Verifies that the class's constructor accepts that keyword, or has a variadic keyword of the form `**params`.  As of Ruby 2.1 and required keywords, verifies that all required keywords are provided.\n* **`#with_unlimited_arguments`:** (also `and_unlimited_arguments`) No parameters. Verifies that the class's constructor accepts any number of arguments via a variadic argument of the form `*args`.\n* **`#with_keywords`:** (also `and_keywords`) Expects one or more String or Symbol arguments. Verifies that the class's constructor accepts each provided keyword or has a variadic keyword of the form `**params`. As of 2.1.0 and required keywords, verifies that all required keywords are provided.\n* **`#with_arbitrary_keywords`:** (also `and_arbitrary_keywords`) No parameters. Verifies that the class's constructor accepts any keyword arguments via a variadic keyword of the form `**params`.\n\n#### `#deep_match` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/deep_match'\n\nPerforms a recursive comparison between two object or data structures. Also supports using RSpec matchers as values in the expected object.\n\n**How To Use:**\n\n    expected = {\n      status: 200,\n      body: {\n        order: {\n          id:    an_instance_of(Integer),\n          total: '9.99'\n        }\n      }\n    }\n    expect(response).to deep_match(expected)\n\nWhen the value does not match the expectation, the failure message will provide a detailed diff showing added, missing, and changed values.\n\n    response = {\n      status: 400,\n      body: {\n        order: {\n          fulfilled: false,\n          total:     '19.99'\n        }\n      },\n      errors: ['Insufficient funds']\n    }\n    expect(response).to deep_match(expected)\n    # Failure/Error: expect(response).to deep_match(expected)\n    #\n    #   expected: == {:body=\u003e{:order=\u003e{:id=\u003ean instance of Integer, :total=\u003e\"9.99\"}}, :status=\u003e200}\n    #        got:    {:status=\u003e400, :body=\u003e{:order=\u003e{:fulfilled=\u003efalse, :total=\u003e\"19.99\"}}, :errors=\u003e[\"Insufficient funds\"]}\n    #\n    #   (compared using Hashdiff)\n    #\n    #   Diff:\n    #   + :body.:order.:fulfilled =\u003e got false\n    #   - :body.:order.:id =\u003e expected an instance of Integer\n    #   ~ :body.:order.:total =\u003e expected \"9.99\", got \"19.99\"\n    #   + :errors =\u003e got [\"Insufficient funds\"]\n    #   ~ :status =\u003e expected 200, got 400\n\n#### `#have_aliased_method` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_aliased_method'\n\nChecks if the object aliases the specified method with the specified other name. Matches if and only if the object responds to both the old and new method names, and if the old method and the new method are the same method.\n\n**How To Use**:\n\n    expect(object).to have_aliased_method(:old_method).as(:new_method)\n\n**Parameters:** Old method name. Expects the name of the method which has been aliased as a String or Symbol.\n\n**Chaining:**\n\n* **`#as`:** Required. Expects one String or Symbol, which is the name of the generated method.\n\n#### `#have_changed` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_changed'\n\nChecks that a watched value has changed. The `have_changed` matcher must be paired with a value spy (see `#watch_value`, below), which is typically created with the `watch_value` helper. This is an alternative to the core RSpec `change` matcher, but allows you track changes to multiple values without nested expectations or other workarounds.\n\n**How To Use**\n\n    spy = watch_value(object, property)\n\n    object.property = 'new value'\n\n    expect(spy).to have_changed\n\nYou can also create a value spy with a block:\n\n    spy = watch_value { object.property }\n\n**Parameters:** None.\n\n**Chaining:**\n\n* **by:** Expects one argument. If the value has changed, then the current value will be subtracted from the initial value and the difference compared with the expected value given to `#by`. *Note:* `not_to have_changed.by()` is not supported and will raise an error.\n* **from:** Expects one argument. The initial value of the spy (at the time the spy was initialized) must be equal to the given value.\n* **to:** Expects one argument. The current value of the spy (at the time `expect().to have_changed` is evaluated) must be equal to the given value.\n\n**Warning:** Make sure that the value spy is initialized before running whatever code is expected to change the value. In particular, if you are setting up your spies using RSpec `let()` statements, it is recommended to use the imperative `let!()` form to ensure that the spies are initialized before running the example.\n\n#### `#have_constant` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_constant'\n\nChecks for the presence of a defined constant `:CONSTANT_NAME` and optionally the value of the constant. Can also check that the value is immutable, e.g. for an additional layer of protection over important constants.\n\n**How To Use:**\n\n    expect(instance).to have_constant(:FOO)\n\n    expect(instance).to have_constant(:BAR).with_value('Bar')\n\n    expect(instance).to have_immutable_constant(:BAZ).with_value('Baz')\n\n**Parameters:** Constant name. Expects a string or symbol that is a valid identifier.\n\n**Chaining:**\n\n* **`#immutable`:** Sets a mutability expectation, which passes if the value of the constant is immutable. Values of `nil`, `false`, `true` are always immutable, as are `Numeric` and `Symbol` primitives. `Array` values must be frozen and all array items must be immutable. `Hash` values must be frozen and all hash keys and values must be immutable. All other objects must be frozen.\n\n* **`#with`:** (also `#with_value`) Expects `true` or `false`, which is checked against the current value of `actual.property?()` if actual responds to `#property?`.\n\n#### `#have_predicate` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_predicate'\n\nChecks if the actual object responds to `#property?`, and optionally if the current value of `actual.property?()` is equal to a specified value. If `config.sleeping_king_studios.matchers.strict_predicate_matching` is set to true, will also validate that the `#property?` returns either `true` or `false`.\n\n**How To Use:**\n\n  expect(instance).to have_predicate(:foo?).with(true)\n\n**Parameters:** Property. Expects a string or symbol that is a valid identifier.\n\n**Chaining:**\n\n* **`#with`:** (also `#with_value`) Expects `true` or `false`, which is checked against the current value of `actual.property?()` if actual responds to `#property?`.\n\n#### `#have_property` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_property'\n\nChecks if the actual object responds to `#property` and `#property=`, and optionally if the current value of `actual.property()` is equal to a specified value.\n\n**How To Use:**\n\n    expect(instance).to have_property(:foo).with(\"foo\")\n\n    expect(instance).to have_property(:foo, :allow_private =\u003e true).with(\"foo\")\n\n**Parameters:**\n\n`param property [String, Symbol]` The name of the property.\n\n`option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected reader or writer method.\n\n**Chaining:**\n\n* **`#with`:** (also `#with_value`) Expects one object, which is checked against the current value of `actual.property()` if actual responds to `#property`. Can also be used with an RSpec matcher:\n\n    expect(instance).to have_property(:bar).with(an_instance_of(String))\n\n#### `#have_reader` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_reader'\n\nChecks if the actual object responds to `#property` with 0 arguments, and optionally if the current value of `actual.property()` is equal to a specified value.\n\n**How To Use:**\n\n    expect(instance).to have_reader(:foo).with(\"foo\")\n\n    expect(instance).to have_reader(:foo, :allow_private =\u003e true).with(\"foo\")\n\n**Parameters:**\n\n`param property [String, Symbol]` The name of the reader method.\n\n`option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected method.\n\n**Chaining:**\n\n* **`#with`:** (also `#with_value`) Expects one object, which is checked against the current value of `actual.property()` if actual responds to `#property`. Can also be used with an RSpec matcher: `expect(instance).to have_reader(:bar).with(an_instance_of(String))`\n\n#### `#have_writer` Matcher\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_writer'\n\nChecks if the actual object responds to `#property=`.\n\n**How To Use:**\n\n    expect(instance).to have_writer(:foo=)\n\n    expect(instance).to have_writer(:foo=, :allow_private =\u003e true)\n\n**Parameters:**\n\n`param property [String, Symbol]` The name of the writer method. An equals sign '=' is automatically added if the identifier does not already terminate in '='.\n\n`option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected method.\n\n#### `#watch_value` Helper\n\n    require 'rspec/sleeping_king_studios/matchers/core/have_changed'\n\nCreates a value spy that watches the value of a method call or block. The spy also caches the initial value at the time the spy was created; this allows comparisons between the initial and current values. Value spies are used with the `#have_changed` matcher (see above).\n\n**How To Use:**\n\n    spy = watch_value(object, property)\n\n    spy = watch_value { object.property }\n\n**Parameters:**\n\n`param object [Object]` The object to watch. Ignored if given a block.\n\n`param method_name [String, Symbol]` The name of the method to watch. Ignored if given a block.\n\n**Chaining:** None.\n\n## Sandbox\n\nThe `RSpec::SleepingKingStudios::Sandbox` module allows for running a spec file or files in an isolated environment and capturing the results. This can be useful for testing code meant to enhance your tests, such as a custom RSpec matcher or a shared example group.\n\nFirst, define a spec file to run. As a recommended convention, spec files to be run in a sandbox should be given the `spec.fixture.rb` suffix to ensure they are not accidentally run with the main test suite.\n\n```ruby\n# frozen_string_literal: true\n\n# In spec/rocket_spec.fixture.rb:\nRSpec.describe Rocket do\n  describe '#launch' do\n    it 'should launch the rocket' do\n      expect { subject.launch }.to change(subject, :launched?).to be true\n    end\n  end\nend\n```\n\nDefining fixture files rather than generating temporary files is recommended for performance reasons, but both approaches are possible. Once the file is defined, it can be run in a sandbox:\n\n```ruby\nresult = RSpec::SleepingKingStudios::Sandbox.run('spec/rocket_spec.fixture.rb')\n\nresult.class #=\u003e RSpec::SleepingKingStudios::Sandbox::Result\nresult.output #=\u003e \"\"\"\n# Rocket\n#   #launch\n#     should launch the rocket\n#\n# 1 example, 0 failures\n# \"\"\"\nresult.status #=\u003e 1\nresult.summary #=\u003e 1 example, 0 failures\nresult.example_descriptions #=\u003e [\n#   'Rocket#launch should launch the rocket'\n# ]\n```\n\nThe `.run` method returns an instance of `RSpec::SleepingKingStudios::Sandbox::Result`, which wraps the result of running the specified spec files. It defines the following methods:\n\n- `#errors`: The output captured from STDERR when running the files.\n- `#example_descriptions`: The full description for each evaluated example.\n- `#json`: The json output from running the files.\n- `#output`: The output captured from STDOUT when running the files. The specs are run with the `--format=doc` flag, so this will include the individual examples as well as the summary.\n- `#summary`: The summary line for the tests.\n\n## Deferred Examples\n\n`RSpec::SleepingKingStudios::Deferred` provides a mechanism for defining specifications that can be reused and shared between projects. For example, a library could use deferred examples to define an interface and test a reference implementation; projects that use that library could then use the published deferred examples to validate their own implementations of that interface.\n\nAt its core, a deferred example group is a Ruby `module`, and hooks into the inheritance hierarchy when `include`d into an example group. This gives certain advantages relative to traditional shared examples (and contracts):\n\n- Deferred examples are defined in a specific context, and can be shared by simply `include`-ing the containing module (or the deferred examples directly). There is no global namespace, and using deferred examples (even from other projects) is as simple as an `include` call.\n- Deferred examples stack, rather than conflict. This means helper methods and memoized helpers can reference other included examples using `super()`, rather than simply overwriting other helpers at the same \"level\".\n- Unlike shared example groups, deferred examples defined via a `Provider` (see [Parameterized Examples](#parameterized-examples), below) can accept a block parameter.\n\n```ruby\nmodule ShouldBeAVehicleExamples\n  include RSpec::SleepingKingStudios::Deferred::Examples\n\n  describe '#type' do\n    it { expect(subject).to respond_to(:type).with(0).arguments }\n\n    it { expect(subject.type).to be == expected_type }\n  end\nend\n\nRSpec.describe Rocket do\n  include ShouldBeAVehicleExamples\n\n  subject(:rocket) { described_class.new }\n\n  let(:expected_type) { :rocket }\n\n  describe '#launch' do\n    it { expect(rocket).to respond_to(:launch) }\n  end\nend\n```\n\n### Parameterized Examples\n\nDeferred examples can also be defined with parameters using the `Deferred::Provider` DSL. Defining a parameterized example group allows for defining and sharing specs that describe complex and conditional behavior.\n\nFor deferred specs that set up a context rather than examples, `deferred_context` is provided as an alias to `Provider.deferred_examples`.\n\n```ruby\nmodule VehicleExamples\n  include RSpec::SleepingKingStudios::Deferred::Provider\n\n  deferred_context 'when the vehicle needs to be serviced' \\\n  do |serviced_at: '2020-01-01'|\n    before(:example) do\n      vehicle.last_serviced_at = serviced_at\n    end\n  end\n\n  deferred_examples 'should be a Vehicle' do |vehicle_type:|\n    it { expect(subject).to be_a Spec::Models::Vehicle }\n\n    describe '#type' do\n      it { expect(subject.type).to be == vehicle_type }\n    end\n  end\nend\n```\n\nThe deferred examples can be included in example groups using the `Deferred::Consumer` DSL.\n\n```ruby\nRSpec.describe Car do\n  include RSpec::SleepingKingStudios::Deferred::Consumer\n  include VehicleExamples\n\n  subject(:car) { described_class.new }\n\n  include_deferred 'should be a Vehicle', vehicle_type: :car\nend\n\nRSpec.describe Rocket do\n  include RSpec::SleepingKingStudios::Deferred::Consumer\n  include VehicleExamples\n\n  subject(:rocket) { described_class.new }\n\n  include_deferred 'should be a Vehicle', vehicle_type: :rocket\nend\n```\n\n`Deferred::Consumer` also defines support for wrapped deferred examples, which automatically generate a new context and include the deferred examples in the new example group. If `#wrap_deferred` is passed a block, that block will automatically be evaluated in the context of the example group, allowing you to define additional context or examples.\n\n```ruby\nRSpec.describe Car do\n  include RSpec::SleepingKingStudios::Deferred::Consumer\n  include VehicleExamples\n\n  subject(:car) { described_class.new }\n\n  wrap_deferred 'when the vehicle needs to be serviced' do\n    it { expect(car.last_serviced_at).to be == '2020-01-01' }\n  end\nend\n```\n\n`Deferred::Consumer` also includes the shortcuts `#finclude_deferred` and `#fwrap_deferred` to automatically focus deferred examples, or `#xinclude_deferred` and `#xwrap_deferred` to skip deferred examples.\n\nThe `defined_deferred_examples?` and `defined_deferred_context?` methods allow checking for the presence of a deferred example group.\n\n```ruby\nRSpec.describe Boat do\n  include RSpec::SleepingKingStudios::Deferred::Consumer\n  include VehicleExamples\n\n  subject(:boat) { described_class.new }\n\n  if defined_deferred_examples?('should be a water Vehicle')\n    include_deferred 'should be a water Vehicle'\n  else\n    pending 'deferred examples \"should be a water Vehicle\" is not defined'\n  end\nend\n```\n\n## Shared Examples\n\nTo use a custom example group, `require` the associated file and then `include`\nthe module in your example group:\n\n    require 'rspec/sleeping_king_studios/examples/some_examples'\n\n    RSpec.describe MyCustomMatcher do\n      include RSpec::SleepingKingStudios::Examples::SomeExamples\n\n      # You can use the custom shared examples here.\n      include_examples 'some examples'\n    end # describe\n\nUnless otherwise noted, these shared examples expect the example group to define either an explicit `#instance` method (using `let(:instance) {}`) or an implicit `subject`. Their behavior is **undefined** if neither `#instance` nor `subject` is defined.\n\n### Property Examples\n\nThese examples are shorthand for defining a property expectation.\n\n    require 'rspec/sleeping_king_studios/examples/property_examples'\n\n    RSpec.describe MyClass do\n      include RSpec::SleepingKingStudios::Examples::PropertyExamples\n\n      # You can use the custom shared examples here.\n    end # describe\n\n#### Should Have Class Property\n\n    include_examples 'should have class property', :foo, 42\n\nDelegates to the `#have_property` matcher (see Core/#have\\_property, above) and passes if `described_class` responds to the specified reader and writer methods. If a value is specified, the described class must respond to the property and return the specified value. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:\n\n    include_examples 'should have class property', :bar, -\u003e() { an_instance_of(String) }\n\n    include_examples 'should have class property', :baz, -\u003e(value) { value.count = 3 }\n\n#### Should Have Class Reader\n\n    include_examples 'should have class reader', :foo, 42\n\nDelegates to the `#have_reader` matcher (see Core/#have_reader, above) and passes if `described_class` responds to the specified property reader. If a value is specified, the described class must respond to the property and return the specified value. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:\n\n    include_examples 'should have class reader', :bar, -\u003e() { an_instance_of(String) }\n\n    include_examples 'should have class reader', :baz, -\u003e(value) { value.count = 3 }\n\n#### Should Have Class Writer\n\n    include_examples 'should have class writer', :foo=\n\nDelegates to the `#have_writer` matcher (see Core/#have_writer, above) and passes if `described_class` responds to the specified property writer.\n\n#### Should Have Constant\n\n    include_examples 'should have constant', :FOO, 42\n\nDelegates to the `#have_constant` matcher (see Core/#have_constant, above) and passes if the described class defines the specified constant. If a value is specified, the class or module must define the constant with the specified value. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:\n\n    include_examples 'should have constant', :BAR, -\u003e() { an_instance_of(String) }\n\n    include_examples 'should have constant', :BAZ, -\u003e(value) { value.count = 3 }\n\n#### Should Have Immutable Constant\n\n    include_examples 'should have immutable constant', :FOO, 42\n\nAs the 'should have constant' example, but sets a mutability expectation on the constant. See Core/#have_constant for specifics on which objects are considered mutable.\n\n#### Should Have Predicate\n\n    include_examples 'should have predicate', :foo, true\n\n    include_examples 'should have predicate', :foo?, true\n\nDelegates to the `#have_predicate` matcher (see Core/#have_predicate, above) and passes if the actual object responds to the specified predicate. If a value is specified, the object must respond to the predicate and return the specified value, which must be true or false. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:\n\n    include_examples 'should have predicate', :bar, -\u003e() { a_boolean }\n\n    include_examples 'should have predicate', :baz, -\u003e(value) { value == true }\n\n#### Should Have Property\n\n    include_examples 'should have property', :foo, 42\n\nDelegates to the `#have_property` matcher (see Core/#have\\_property, above) and passes if the actual object responds to the specified reader and writer methods. If a value is specified, the object must respond to the property and return the specified value. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:\n\n    include_examples 'should have property', :bar, -\u003e() { an_instance_of(String) }\n\n    include_examples 'should have property', :baz, -\u003e(value) { value.count = 3 }\n\nYou can also set the :allow_private option to allow the examples to match a private reader and/or writer method:\n\n    include_examples 'should have property', :foo, :allow_private =\u003e true\n\n    include_examples 'should have property', :foo, 42, :allow_private =\u003e true\n\n#### Should Have Private Property\n\n    include_examples 'should have private property', :foo\n\n    include_examples 'should have private property', :foo, 42\n\nPasses if the actual object has the specified private or protected property reader and writer, and fails if the actual object does not have the specified reader and writer or if the specified reader or writer is a public method. If a value is specified, the value of the private reader must match the specified value.\n\n#### Should Have Reader\n\n    include_examples 'should have reader', :foo, 42\n\nDelegates to the `#have_reader` matcher (see Core/#have_reader, above) and passes if the actual object responds to the specified property reader. If a value is specified, the object must respond to the property and return the specified value. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:\n\n    include_examples 'should have reader', :bar, -\u003e() { an_instance_of(String) }\n\n    include_examples 'should have reader', :baz, -\u003e(value) { value.count = 3 }\n\nYou can also set the :allow_private option to allow the examples to match a private reader method:\n\n    include_examples 'should have reader', :foo, :allow_private =\u003e true\n\n    include_examples 'should have reader', :foo, 42, :allow_private =\u003e true\n\n#### Should Not Have Reader\n\n    include_examples 'should not have reader', :foo\n\nDelegates to the `#have_reader` matcher (see Core/#have_reader, above) and passes if the actual object does not respond to to the specified property reader.\n\n#### Should Have Private Reader\n\n    include_examples 'should have private reader', :foo\n\n    include_examples 'should have private reader', :foo, 42\n\nPasses if the actual object has the specified private or protected property reader, and fails if the actual object does not have the specified reader or if the specified reader is a public method. If a value is specified, the value of the private reader must match the specified value.\n\n#### Should Have Writer\n\n    include_examples 'should have writer', :foo=\n\nDelegates to the `#have_writer` matcher (see Core/#have_writer, above) and passes if the actual object responds to the specified property writer.\n\nYou can also set the :allow_private option to allow the examples to match a private writer method:\n\n    include_examples 'should have writer', :foo=, :allow_private =\u003e true\n\n#### Should Not Have Writer\n\n    include_examples 'should not have writer', :foo=\n\nDelegates to the `#have_writer` matcher (see Core/#have_writer, above) and passes if the actual object does not respond to to the specified property writer.\n\n#### Should Have Private Writer\n\n    include_examples 'should have private writer', :foo=\n\nPasses if the actual object has the specified private or protected property writer, and fails if the actual object does not have the specified writer or if the specified writer is a public method.\n\n### RSpec Matcher Examples\n\nThese examples are used for validating custom RSpec matchers. They are used\ninternally by RSpec::SleepingKingStudios to verify the functionality of the\nnew and modified matchers.\n\n    require 'rspec/sleeping_king_studios/examples/rspec_matcher_examples'\n\n    RSpec.describe MyCustomMatcher do\n      include RSpec::SleepingKingStudios::Examples::RSpecMatcherExamples\n\n      # You can use the custom shared examples here.\n    end # describe\n\nThe `#instance` or `subject` for these examples should be an instance of a class matching the RSpec matcher API. For example, consider a matcher that checks if a number is a multiple of another number. This matcher would be used as follows:\n\n    expect(12).to be_a_multiple_of(3)\n    #=\u003e true\n\n    expect(14).to be_a_multiple_of(3)\n    #=\u003e false\n\nTherefore, the `#instance` or `subject` should be defined as `BeAMultipleMatcher.new(3)`. If the custom matcher has additional fluent methods or options, these can be added to the instance as well, e.g. `expect(15).to be_a_multiple_of(3).and_of(5)` would be tested as `BeAMultipleMatcher.new(3).and_of(5)`.\n\nIn addition, all of these examples require a defined `#actual` method in the example group containing the object to be tested. The actual object is the object used in the expectation. In the above examples, the actual object is `12` in the first example, and `14` in the second. You can define the `#actual` method using `#let()`, e.g. `let(:actual) { Object.new }`.\n\nPutting it all together:\n\n    require 'rspec/sleeping_king_studios/examples/rspec_matcher_examples'\n\n    RSpec.describe BeAMultipleOfMatcher do\n      include RSpec::SleepingKingStudios::Examples::RSpecMatcherExamples\n\n      let(:instance) { BeAMultipleOfMatcher.new(3) }\n\n      describe 'with a valid number' do\n        let(:actual) { 15 }\n\n        # Include examples here.\n\n        describe 'with a second factor' do\n          let(:instance) { BeAMultipleOfMatcher.new(3).and_of(5) }\n\n          # Include examples here.\n        end # describe\n      end # describe\n    end # describe\n\n#### Passes With A Positive Expectation\n\n    include_examples 'passes with a positive expectation'\n\nVerifies that the instance matcher will pass with a positive expectation (e.g. `expect().to`). Equivalent to verifying the result of the following:\n\n    expect(actual).to match_my_custom_matcher(*expected_values)\n    #=\u003e passes\n\n#### Passes With A Negative Expectation\n\n    include_examples 'passes with a negative expectation'\n\nVerifies that the instance matcher will pass with a negative expectation (e.g. `expect().not_to`). Equivalent to verifying the result of the following:\n\n    expect(actual).not_to match_my_custom_matcher(*expected_values)\n    #=\u003e passes\n\n#### Fails With A Positive Expectation\n\n    include_examples 'fails with a positive expectation'\n\nVerifies that the instance matcher will fail with a positive expectation (e.g. `expect().to`), and have the expected failure message. Equivalent to verifying the result of the following:\n\n    expect(actual).to match_my_custom_matcher(*expected_values)\n    #=\u003e fails\n\nIn addition, verifies the `#failure_message` of the matcher by comparing it against a `#failure_message` method in the example group. This should be defined using `let(:failure_message) { 'expected to match' }`.\n\nThe behavior if the example group does not define `#failure_message` depends on the value of the `RSpec.configure.sleeping_king_studios.examples.handle_missing_failure_message_with` option (see Configuration, above). Accepted values are `:ignore`, `:pending` (default; marks the example as pending), and `:exception` (raises an exception).\n\n#### Fails With A Negative Expectation\n\n    include_examples 'fails with a negative expectation'\n\nVerifies that the instance matcher will fail with a negative expectation (e.g. `expect().not_to`), and have the expected failure message. Equivalent to verifying the result of the following:\n\n    expect(actual).not_to match_my_custom_matcher(*expected_values)\n    #=\u003e fails\n\nIn addition, verifies the `#failure_message_when_negated` of the matcher by comparing it against a `#failure_message_when_negated` method in the example group. This should be defined using `let(:failure_message_when_negated) { 'expected not to match' }`.\n\nSee Fails With A Positive Expectation, above, for behavior when the example group does not define `#failure_message_when_negated`.\n\n## License\n\nRSpec::SleepingKingStudios is released under the [MIT License](http://www.opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleepingkingstudios%2Frspec-sleeping_king_studios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsleepingkingstudios%2Frspec-sleeping_king_studios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleepingkingstudios%2Frspec-sleeping_king_studios/lists"}