Logo: Relish

  1. Sign up
  2. Sign in

Project: RSpec Core 3.2

Define helper methods in a module

You can define helper methods in a module and include it in your example
groups using the config.include configuration option. config.extend can be
used to extend the module onto your example groups so that the methods in the
module are available in the example groups themselves (but not in the actual
examples).

You can also include or extend the module onto only certain example groups
by passing a metadata hash as the last argument. Only groups that match the
given metadata will include or extend the module. You can also specify
metadata using only symbols.

Note that examples that match a config.include module's metadata will also have the module included. RSpec treats every example as having a singleton example group (analogous to Ruby's singleton classes) containing just the one example.

Background
Given
a file named "helpers.rb" with:
module Helpers
  def help
    :available
  end
end
Scenarios
Include a module in all example groups
Given
a file named "include_module_spec.rb" with:
require './helpers'

RSpec.configure do |c|
  c.include Helpers
end

RSpec.describe "an example group" do
  it "has access to the helper methods defined in the module" do
    expect(help).to be(:available)
  end
end
When
I run rspec include_module_spec.rb
Then
the examples should all pass
Extend a module in all example groups
Given
a file named "extend_module_spec.rb" with:
require './helpers'

RSpec.configure do |c|
  c.extend Helpers
end

RSpec.describe "an example group" do
  puts "Help is #{help}"

  it "does not have access to the helper methods defined in the module" do
    expect { help }.to raise_error(NameError)
  end
end
When
I run rspec extend_module_spec.rb
Then
the examples should all pass
And
the output should contain "Help is available"
Include a module in only some example groups
Given
a file named "include_module_in_some_groups_spec.rb" with:
require './helpers'

RSpec.configure do |c|
  c.include Helpers, :foo => :bar
end

RSpec.describe "an example group with matching metadata", :foo => :bar do
  it "has access to the helper methods defined in the module" do
    expect(help).to be(:available)
  end
end

RSpec.describe "an example group without matching metadata" do
  it "does not have access to the helper methods defined in the module" do
    expect { help }.to raise_error(NameError)
  end

  it "does have access when the example has matching metadata", :foo => :bar do
    expect(help).to be(:available)
  end
end
When
I run rspec include_module_in_some_groups_spec.rb
Then
the examples should all pass
Extend a module in only some example groups
Given
a file named "extend_module_in_only_some_groups_spec.rb" with:
require './helpers'

RSpec.configure do |c|
  c.extend Helpers, :foo => :bar
end

RSpec.describe "an example group with matching metadata", :foo => :bar do
  puts "In a matching group, help is #{help}"

  it "does not have access to the helper methods defined in the module" do
    expect { help }.to raise_error(NameError)
  end
end

RSpec.describe "an example group without matching metadata" do
  puts "In a non-matching group, help is #{help rescue 'not available'}"

  it "does not have access to the helper methods defined in the module" do
    expect { help }.to raise_error(NameError)
  end
end
When
I run rspec extend_module_in_only_some_groups_spec.rb
Then
the examples should all pass
And
the output should contain "In a matching group, help is available"
And
the output should contain "In a non-matching group, help is not available"
Use symbols as metadata
Given
a file named "symbols_as_metadata_spec.rb" with:
require './helpers'

RSpec.configure do |c|
  c.include Helpers, :include_helpers
  c.extend  Helpers, :extend_helpers
end

RSpec.describe "an example group with matching include metadata", :include_helpers do
  puts "In a group not matching the extend filter, help is #{help rescue 'not available'}"

  it "has access to the helper methods defined in the module" do
    expect(help).to be(:available)
  end
end

RSpec.describe "an example group with matching extend metadata", :extend_helpers do
  puts "In a group matching the extend filter, help is #{help}"

  it "does not have access to the helper methods defined in the module" do
    expect { help }.to raise_error(NameError)
  end
end
When
I run rspec symbols_as_metadata_spec.rb
Then
the examples should all pass
And
the output should contain "In a group not matching the extend filter, help is not available"
And
the output should contain "In a group matching the extend filter, help is available"

Last published about 1 month ago by myronmarston.