rspec-sleeping_king_studios 2.2.4 → 2.3.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2cc8203c15e94a3b3eb1b02593024abd5b9d831d
-  data.tar.gz: 3b5f2c2d68e0999136707eed7e1a3eece9e1e429
+  metadata.gz: 5a9d2f85f2b455f1996f711b0d606f5b1ca1c299
+  data.tar.gz: 21a4f0209ed50bc16090b2de208540a10e28dfd4
 SHA512:
-  metadata.gz: e05d8ef7c6e0d9c665e89ef25daec30d7326a7ab5a3f13e4986e3ee9484de2083dfe62e45b0f5b862baa93bf274f3be4250d01a4eb0c8591ab79ff626cf80f4a
-  data.tar.gz: 4aab6dca88d46c22a1f8fbb2efef286eed61ebc654ab5e233decfadc6a277fc61a2283592a5fb42df35cc7040b016f0d1e9f198b5b5cbf3c126ea22be535140d
+  metadata.gz: fefccdff728588bd83fca3941faffc70330531edcfd8a9c9507c5b2cec59340d0492feeeb17d857729974d132e3d2687283f5957da799577226b5979c091e19b
+  data.tar.gz: 47d1c296a0acc07d2b8a24fd5e3f1cceea18fa8ce5f7e7da51e9c510b2f3b06f36199ed3b89628ce8a1f53cb0f8e62137c0ded9f1b79d51ced492779d12662eb

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.3.0
+
+### Concerns
+
+Added ExampleConstants concern to define named, example-scoped constants and classes.
+
+Added Toolbelt concern to automatically expose SleepingKingStudios::Tools methods in examples and example groups.
+
+Added WrapEnv concern to cleanly control environment variables per example or within example blocks.
+
+### Examples
+
+Added shared examples for expecting class readers, writers, and properties.
+
+Added shared examples for expecting private readers, writers, and properties.
+
+Added aliased examples for "has constant", "has immutable constant".
+
+### Matchers
+
+Added :allow_private option to HaveReaderMatcher, HaveWriterMatcher, and HavePropertyMatcher.
+
 ## 2.2.4
 
 Reverted support for RSpec 3.0 to 3.2.
@@ -173,7 +195,7 @@ Removed the functionality checking the value of `:property` after `:property=` h
 
 Now supports composable matchers, as follows:
 
-    expect(object).to have_property(:my_method).with(an_instance_of(Fixnum))
+    expect(object).to have_property(:my_method).with(an_instance_of(Integer))
 
 Also added `#with_value` as an alias for `with`, and the error messages have been edited for clarity.
 

data/DEVELOPMENT.md

@@ -2,65 +2,55 @@
 
 ## Version 2.3
 
-### Features
+## Version 2.3.1
+
+### Features - Syntactic Sugar
 
 - Alias `have_reader`, etc as `define_reader`.
   - Also alias shared examples.
 - Alias `have_constant` as `define_constant`.
   - Alias #immutable as #frozen.
   - Also alias shared examples.
-- Add 'should have class reader/writer/property' shared examples.
-- Add 'should have private reader/writer/property' shared examples.
-- Implement RespondToMatcher#with_at_least(N).arguments, equivalent to with(N).arguments.and_unlimited_arguments.
 
 ## Future Tasks
 
 - Resolve Aruba deprecation warnings.
-- Run each file individually as CI step.
 
 ### Bug Fixes
 
 - false negative on #alias_method?
+  - need reproduction steps!
   - compare via Method#source_location equality and Method#original_name is expected?
 
-### Features
-
-- Implement ::stub_env, #stub_env: |
-
-  describe 'something' do
-    # Changes the value using an around(:example) block.
-    stub_env('FIRST_KEY', 'value')
-
-    # Block syntax.
-    stub_env('SECOND_KEY') { calculated_value }
-
-    it 'should something' do
-      # Temporarily changes the value, calls the block, and resets the value.
-      stub_env('THIRD_KEY', 'value') do
-
-      end # stub_env
-    end # it
-  end # describe
+### Features - Functionality
 
-- Implement example-scoped test constants: |
-
-  example_class 'Example::Class::Name' do |klass| ... end
-
-  example_module 'Example::Module::Name' do |mod| ... end
+- Add spy+matcher for expect(my_object, :my_method).to have_changed ?
 
-  example_const 'Example::Constant::Name' do ... end
+### Features - Quality of Life
 
+- Implement RespondToMatcher#with_optional_keywords, #with_required_keywords.
 - Implement be_immutable matcher.
 - Enhance RSpec matcher examples to display the #failure_message on a failed "should pass/fail with" example.
 - let?(:name) { } # Defines a memoized helper, but only if one is not already defined.
-- Add spy+matcher for expect(my_object, :my_method).to have_changed ?
+
+### Features - Syntactic Sugar
+
+- Implement RespondToMatcher#with_at_least(N).arguments, equivalent to with(N).arguments.and_unlimited_arguments.
 
 ### Maintenance
 
+- Update all Concerns to be #include-d, not #extend-ed.
+- Update SharedExampleGroup concern to use Ruby paradigms:
+  - overload #include_examples
+  - use proper method-based lookup, inheritance, etc
+  - less fragility than hooking into existing RSpec internals
 - Revisit failure messages for #respond_to, #be_constructible - see #received/#have_received for example?
 - Revisit how matchers are documented, particularly in README.md
   - Use matcher class name instead of macro names?
   - Clarify documentation of parameters - YARD-like?
+- Integration specs for shared example groups
+  - Run in external process, parse output for expected values (similar to Aruba)
+  - Allows testing of failing example groups
 - Pare down Cucumber features for matchers - repurpose as documentation/examples only.
   - Break down into smaller (bite-sized?) individual examples.
 - RuboCop - use RSpec rule file as starting point?

data/README.md

@@ -4,7 +4,7 @@ A collection of matchers and extensions to ease TDD/BDD using RSpec. Extends bui
 
 ## Support
 
-RSpec::SleepingKingStudios is tested against RSpec 3.0 through 3.6, but support for RSpec 3.2 and below will be removed in version 2.3.0.
+RSpec::SleepingKingStudios is tested against RSpec 3.3 through 3.6.
 
 Currently, the following versions of Ruby are officially supported:
 
@@ -14,7 +14,7 @@ Currently, the following versions of Ruby are officially supported:
 
 For Ruby 2.0 support, use version 2.1 or earlier: `gem "rspec-sleeping_king_studios", "~> 2.1.1"`.
 
-For RSpec 3.0 to 3.2 support, use version 2.2 or earlier: `gem "rspec-sleeping_king_studios", "~> 2.2.4"`.
+For RSpec 3.0 to 3.2 support, use version 2.2 or earlier: `gem "rspec-sleeping_king_studios", "~> 2.2.2"`.
 
 If you require a previous version of Ruby or RSpec, the 1.0 branch supports Ruby 1.9.3 and RSpec 2: `gem "rspec-sleeping_king_studios", "~> 1.0.1"`. However, changes from 2.0 and higher will not be backported.
 
@@ -98,12 +98,55 @@ This option is used with the HavePredicateMatcher (see `#have_predicate`, below)
 
 RSpec::SleepingKingStudios defines a few concerns that can be included in or extended into modules or example groups for additional functionality.
 
+### Example Constants
+
+    require 'rspec/sleeping_king_studios/concerns/example_constants'
+
+    RSpec.describe 'constants' do
+      extend RSpec::SleepingKingStudios::Concerns::ExampleConstants
+
+      example_constant 'THE_ANSWER', 42
+
+      example_class 'Spec::Examples::Question' do |klass|
+        klass.send :define_method, :answer, THE_ANSWER
+      end # example_class
+
+      let(:described_class) { Spec::Examples::Question }
+      let(:instance)        { described_class.new }
+
+      it { expect(described_class.name).to be == 'Spec::Examples::Question' }
+
+      it { expect(instance.answer).to be THE_ANSWER }
+    end # describe
+
+Provides a programmatic way to define temporary constants and classes scoped to the current example.
+
+#### `::example_constant`
+
+`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.
+
+`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.
+
+`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.
+
+Sets the value of the named constant to the specified value within the context of the current example.
+
+#### `::example_class`
+
+`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.
+
+`option base_class [Class]` Defaults to Object. The base class of the generated class.
+
+`yield klass [Class]` If a block is given, it is executed in the context of the generated class and yielded the class.
+
+Creates 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.
+
 ### Focus Examples
 
     require 'rspec/sleeping_king_studios/concerns/focus_examples'
 
     RSpec.describe String do
-      extend RSpec::SleepingKingStudios::Concerns::WrapExamples
+      extend RSpec::SleepingKingStudios::Concerns::FocusExamples
 
       shared_examples 'should be a greeting' do
         it { expect(salutation).to be =~ /greeting/i }
@@ -160,6 +203,74 @@ Utility functions for defining shared examples. If included in a module, any sha
 
 (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.
 
+### Toolbelt
+
+    require 'rspec/sleeping_king_studios/concerns/toolbelt'
+
+    RSpec.describe "a String" do
+      include RSpec::SleepingKingStudios::Concerns::Toolbelt
+
+      shared_examples 'should process' do |string|
+        singular = tools.string.singularize(string)
+        plural   = tools.string.pluralize(string)
+
+        it "should singularize #{string} to #{singular}" do
+          expect(tools.singularize string).to be_a String
+        end # it
+
+        it "should pluralize #{string} to #{plural}" do
+          expect(tools.pluralize string).to be_a String
+        end # it
+      end # shared_examples
+
+      include_examples 'should pluralize', 'light'
+    end # describe
+
+A helper module for exposing SleepingKingStudios::Tools methods in examples and example groups.
+
+### Wrap Environment
+
+    require 'rspec/sleeping_king_studios/concerns/wrap_env'
+
+    RSpec.describe 'environment' do
+      include RSpec::SleepingKingStudios::Concerns::WrapEnv
+
+      it { expect(ENV['VAR_NAME']).to be nil }
+
+      context 'when the variable is set in the example group' do
+        wrap_env 'VAR_NAME', 'custom_value'
+
+        it { expect(ENV['VAR_NAME']).to be == 'custom_value' }
+      end # context
+
+      context 'when the variable is set in the example group with a block' do
+        let(:calculated_value) { 'calculated_value' }
+
+        wrap_env('VAR_NAME') { calculated_value }
+
+        it { expect(ENV['VAR_NAME']).to be == calculated_value }
+      end # context
+
+      context 'when the variable is set inside an example' do
+        it 'should set the variable' do
+          expect(ENV['VAR_NAME']).to be nil
+
+          begin
+            wrap_env('VAR_NAME', 'new_value') do
+              expect(ENV['VAR_NAME']).to be == 'new_value'
+
+              raise RuntimeError, 'must handle errors and reset the var'
+            end # wrap_env
+          rescue RuntimeError
+          end # begin-rescue
+
+          expect(ENV['VAR_NAME']).to be nil
+        end # it
+      end # context
+    end # describe
+
+Provides helper methods for temporarily overwriting values in the environment, which are safely and automatically reset after the example or block.
+
 ### Wrap Examples
 
     require 'rspec/sleeping_king_studios/concerns/wrap_examples'
@@ -446,7 +557,13 @@ Checks if the actual object responds to `#property` and `#property=`, and option
 
     expect(instance).to have_property(:foo).with("foo")
 
-**Parameters:** Property. Expects a string or symbol that is a valid identifier.
+    expect(instance).to have_property(:foo, :allow_private => true).with("foo")
+
+**Parameters:**
+
+`param property [String, Symbol]` The name of the property.
+
+`option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected reader or writer method.
 
 **Chaining:**
 
@@ -458,19 +575,23 @@ Checks if the actual object responds to `#property` and `#property=`, and option
 
     require 'rspec/sleeping_king_studios/matchers/core/have_reader'
 
-Checks if the actual object responds to `#property`, and optionally if the current value of `actual.property()` is equal to a specified value.
+Checks 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.
 
 **How To Use:**
 
     expect(instance).to have_reader(:foo).with("foo")
 
-**Parameters:** Property. Expects a string or symbol that is a valid identifier.
+    expect(instance).to have_reader(:foo, :allow_private => true).with("foo")
 
-**Chaining:**
+**Parameters:**
 
-* **`#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:
+`param property [String, Symbol]` The name of the reader method.
+
+`option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected method.
+
+**Chaining:**
 
-    expect(instance).to have_reader(:bar).with(an_instance_of(String))
+* **`#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))`
 
 #### `#have_writer` Matcher
 
@@ -482,7 +603,13 @@ Checks if the actual object responds to `#property=`.
 
     expect(instance).to have_writer(:foo=)
 
-**Parameters:** Property. Expects a string or symbol that is a valid identifier. An equals sign '=' is automatically added if the identifier does not already terminate in '='.
+    expect(instance).to have_writer(:foo=, :allow_private => true)
+
+**Parameters:**
+
+`param property [String, Symbol]` The name of the writer method. An equals sign '=' is automatically added if the identifier does not already terminate in '='.
+
+`option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected method.
 
 ## Shared Examples
 
@@ -512,6 +639,32 @@ These examples are shorthand for defining a property expectation.
       # You can use the custom shared examples here.
     end # describe
 
+#### Should Have Class Property
+
+    include_examples 'should have class property', :foo, 42
+
+Delegates 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:
+
+    include_examples 'should have class property', :bar, ->() { an_instance_of(String) }
+
+    include_examples 'should have class property', :baz, ->(value) { value.count = 3 }
+
+#### Should Have Class Reader
+
+    include_examples 'should have class reader', :foo, 42
+
+Delegates 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:
+
+    include_examples 'should have class reader', :bar, ->() { an_instance_of(String) }
+
+    include_examples 'should have class reader', :baz, ->(value) { value.count = 3 }
+
+#### Should Have Class Writer
+
+    include_examples 'should have class writer', :foo=
+
+Delegates to the `#have_writer` matcher (see Core/#have_writer, above) and passes if `described_class` responds to the specified property writer.
+
 #### Should Have Constant
 
     include_examples 'should have constant', :FOO, 42
@@ -550,6 +703,20 @@ Delegates to the `#have_property` matcher (see Core/#have\_property, above) and
 
     include_examples 'should have property', :baz, ->(value) { value.count = 3 }
 
+You can also set the :allow_private option to allow the examples to match a private reader and/or writer method:
+
+    include_examples 'should have property', :foo, :allow_private => true
+
+    include_examples 'should have property', :foo, 42, :allow_private => true
+
+#### Should Have Private Property
+
+    include_examples 'should have private property', :foo
+
+    include_examples 'should have private property', :foo, 42
+
+Passes 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.
+
 #### Should Have Reader
 
     include_examples 'should have reader', :foo, 42
@@ -560,24 +727,48 @@ Delegates to the `#have_reader` matcher (see Core/#have_reader, above) and passe
 
     include_examples 'should have reader', :baz, ->(value) { value.count = 3 }
 
+You can also set the :allow_private option to allow the examples to match a private reader method:
+
+    include_examples 'should have reader', :foo, :allow_private => true
+
+    include_examples 'should have reader', :foo, 42, :allow_private => true
+
 #### Should Not Have Reader
 
     include_examples 'should not have reader', :foo
 
 Delegates 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.
 
+#### Should Have Private Reader
+
+    include_examples 'should have private reader', :foo
+
+    include_examples 'should have private reader', :foo, 42
+
+Passes 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.
+
 #### Should Have Writer
 
     include_examples 'should have writer', :foo=
 
 Delegates to the `#have_writer` matcher (see Core/#have_writer, above) and passes if the actual object responds to the specified property writer.
 
+You can also set the :allow_private option to allow the examples to match a private writer method:
+
+    include_examples 'should have writer', :foo=, :allow_private => true
+
 #### Should Not Have Writer
 
     include_examples 'should not have writer', :foo=
 
 Delegates 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.
 
+#### Should Have Private Writer
+
+    include_examples 'should have private writer', :foo=
+
+Passes 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.
+
 ### RSpec Matcher Examples
 
 These examples are used for validating custom RSpec matchers. They are used

data/lib/rspec/sleeping_king_studios/concerns/example_constants.rb

@@ -0,0 +1,94 @@
+# lib/rspec/sleeping_king_studios/concerns/example_constants.rb
+
+require 'rspec/sleeping_king_studios/concerns'
+
+module RSpec::SleepingKingStudios::Concerns
+  module ExampleConstants
+    DEFAULT_VALUE = Object.new.freeze
+    private_constant :DEFAULT_VALUE
+
+    def self.assign_constant namespace, constant_name, constant_value
+      prior_value = DEFAULT_VALUE
+
+      if namespace.const_defined?(constant_name)
+        prior_value = namespace.const_get(constant_name)
+      end # if
+
+      namespace.const_set(constant_name, constant_value)
+
+      yield
+    ensure
+      if prior_value == DEFAULT_VALUE
+        namespace.send :remove_const, constant_name
+      else
+        namespace.const_set(constant_name, prior_value)
+      end # if-else
+    end # class method assign_constant
+
+    def self.guard_existing_constant! namespace, constant_name
+      return unless namespace.const_defined?(constant_name)
+
+      message =
+        "constant #{constant_name} is already defined with value "\
+        "#{namespace.const_get(constant_name).inspect}"
+
+      raise NameError, message
+    end # class method guard_existing_constant!
+
+    def self.resolve_namespace module_names
+      last_defined = nil
+
+      resolved =
+        module_names.reduce(Object) do |ns, module_name|
+          next ns.const_get(module_name) if ns.const_defined?(module_name)
+
+          last_defined ||= { :namespace => ns, :module_name => module_name }
+
+          ns.const_set(module_name, Module.new)
+        end # reduce
+
+      yield resolved
+    ensure
+      if last_defined
+        last_defined[:namespace].send(:remove_const, last_defined[:module_name])
+      end # if
+    end # class method resolve_namespace
+
+    def example_class class_name, base_class: Object, &block
+      example_constant(class_name) do
+        base_class = Object.const_get(base_class) if base_class.is_a?(String)
+        klass      = Class.new(base_class)
+
+        klass.define_singleton_method(:name) { class_name }
+        klass.singleton_class.send(:alias_method, :inspect, :name)
+        klass.singleton_class.send(:alias_method, :to_s,    :name)
+
+        klass.instance_exec(klass, &block) if block_given?
+
+        klass
+      end # example_constant
+    end # method example_class
+
+    def example_constant qualified_name, constant_value = DEFAULT_VALUE, force: false, &block
+      around(:example) do |example|
+        resolved_value =
+          if constant_value == DEFAULT_VALUE
+            block ? example.instance_exec(&block) : nil
+          else
+            constant_value
+          end # if
+
+        module_names  = qualified_name.to_s.split('::')
+        constant_name = module_names.pop
+
+        ExampleConstants.resolve_namespace(module_names) do |namespace|
+          ExampleConstants.guard_existing_constant!(namespace, constant_name) unless force
+
+          ExampleConstants.assign_constant(namespace, constant_name, resolved_value) do
+            example.call
+          end # assign_constant
+        end # resolve_namespace
+      end # before example
+    end # method example_constant
+  end # module
+end # module

data/lib/rspec/sleeping_king_studios/concerns/shared_example_group.rb

@@ -8,7 +8,7 @@ module RSpec::SleepingKingStudios::Concerns
   #
   # @example
   #   module MySharedExamples
-  #     extend Rspec::SleepingKingStudios::Concerns::SharedExampleGroup
+  #     extend RSpec::SleepingKingStudios::Concerns::SharedExampleGroup
   #
   #     shared_examples 'my examples' do
   #       # Define shared examples here.
@@ -48,6 +48,8 @@ module RSpec::SleepingKingStudios::Concerns
     #
     # Hook to merge defined example groups when included in another module.
     def included other
+      super
+
       merge_shared_example_groups other
     end # method included
 

data/lib/rspec/sleeping_king_studios/concerns/toolbelt.rb

@@ -0,0 +1,25 @@
+# lib/rspec/sleeping_king_studios/concerns/toolbelt.rb
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'rspec/sleeping_king_studios/concerns'
+
+module RSpec::SleepingKingStudios::Concerns
+  # Defines ::tools and #tools methods for example groups and examples, exposing
+  # an instance of SleepingKingStudios::Tools::Toolbelt.
+  module Toolbelt
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Class methods to define when including
+    # RSpec::SleepingKingStudios::Concerns::Toolbelt in a class.
+    module ClassMethods
+      def tools
+        @tools ||= SleepingKingStudios::Tools::Toolbelt.instance
+      end # class method tools
+    end # module
+
+    def tools
+      @tools ||= self.class.tools
+    end # method tools
+  end # module
+end # module

data/lib/rspec/sleeping_king_studios/concerns/wrap_env.rb

@@ -0,0 +1,46 @@
+# lib/rspec/sleeping_king_studios/concerns/wrap_env.rb
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'rspec/sleeping_king_studios/concerns'
+
+module RSpec::SleepingKingStudios::Concerns
+  # Methods for temporarily overwriting values in the environment, which are
+  # safely and automatically reset after the block or example.
+  module WrapEnv
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Class methods to define when including
+    # RSpec::SleepingKingStudios::Concerns::WrapEnv in a class.
+    module ClassMethods
+      def wrap_env key, value = nil, &block
+        around(:example) do |wrapped_example|
+          begin
+            if block_given?
+              example = wrapped_example.example
+              value   = example.instance_exec(&block)
+            end # if
+
+            prior_value = ENV[key]
+            ENV[key]    = value
+
+            wrapped_example.call
+          ensure
+            ENV[key]    = prior_value
+          end # begin-ensure
+        end # around example
+      end # class method wrap_env
+      alias_method :stub_env, :wrap_env
+    end # module
+
+    def wrap_env key, value
+      prior_value = ENV[key]
+      ENV[key]    = value
+
+      yield
+    ensure
+      ENV[key]    = prior_value
+    end # method wrap_env
+    alias_method :stub_env, :wrap_env
+  end # module
+end # module