Learning Goals

Hooks

You have already learned about the before hook that RSpec offers and allows you to prepare the context, that is, the setup of your test, of your example. However, RSpec offers some extra hooks.

before(:all)

This hook attaches code that is executed once for all the examples on a given context/describe. So this should appear inside the do...end block of a describe or context.

In order to see an example of this, you are going to enhance the spec/coffee_spec.rb specifications as follows (Listing 5-5).

# File: spec/coffee_spec.rb

#

RSpec.describe 'A coffee' do

  let(:coffee) { Coffee.new }

  it 'costs 1 euro' do

    expect(coffee.price).to eq(1)

  end

  it 'takes 1 minute to prepare' do

    expect(coffee.prepare_duration).to eq(1)

  end

  context 'with milk' do

    before :all do

      puts 'This is a hook that will be executed once for the "with milk" context examples'

      @with_milk = 'Milk has been added!'

    end

    before { coffee.add_milk }

    it 'costs 1.2 euro' do

      puts @with_milk

      expect(coffee.price).to eq(1.2)

    end

    it 'takes 2 minutes to prepare' do

      puts @with_milk

      expect(coffee.prepare_duration).to eq(2)

    end

  end

end

Listing 5-5

spec/coffee_spec.rb File with the before :all Hook

These are the changes to the code, as in Figure 5-2:

1. 1.

   You have added two more expectations that have to do with the duration to prepare a cup of coffee.

    
2. 2.

   You have added a before(:all) hook on the context with milk. This code will be executed only once for the two examples in that context.

    

Let’s run the suite:

$ bundle exec rspec

Randomized with seed 16834

This is executed only once at the beginning of the specifications run

A coffee

  takes 1 minute to prepare (FAILED - 1)

  costs 1 euro

  with milk

This is a hook that will be executed once for the "with milk" context examples

Milk has been added!

    costs 1.2 euro

Milk has been added!

    takes 2 minutes to prepare (FAILED - 2)

An ideal sandwich

  is delicious

  lets me add toppings

Failures:

  1) A coffee takes 1 minute to prepare

     Failure/Error: expect(coffee.prepare_duration).to eq(1)

     NoMethodError:

       undefined method `prepare_duration' for #<Coffee:0x00007f936b09a500 @ingredients=[]>

     # ./spec/coffee_spec.rb:11:in `block (2 levels) in <top (required)>'

  2) A coffee with milk takes 2 minutes to prepare

     Failure/Error: expect(coffee.prepare_duration).to eq(2)

     NoMethodError:

       undefined method `prepare_duration' for #<Coffee:0x00007f936a8f6010 @ingredients=["milk"]>

     # ./spec/coffee_spec.rb:29:in `block (3 levels) in <top (required)>'

Finished in 0.00819 seconds (files took 0.26973 seconds to load)

6 examples, 2 failures

Failed examples:

rspec ./spec/coffee_spec.rb:10 # A coffee takes 1 minute to prepare

rspec ./spec/coffee_spec.rb:27 # A coffee with milk takes 2 minutes to prepare

Randomized with seed 16834

$

As expected, the two examples that deal with the preparation duration fail. Before you fix them, see the messages that prove how the before(:all) hook works. It is called once for the whole context, and the instance variables created within its block are available to the code of the examples (Figure 5-3).

Let’s quickly fix the code by introducing the #prepare_duration method in the Coffee class (file: coffee.rb – Listing 5-6).

# File: coffee.rb

#

class Coffee

  INGREDIENT_PRICES = {

    'milk' => 0.2

  }

  def initialize

    @ingredients = []

  end

  def price

    1 + sum_of_ingredients_price

  end

  def add_milk

    @ingredients << 'milk'

  end

  def prepare_duration

    1 + @ingredients.size

  end

  private

  def sum_of_ingredients_price

    @ingredients.reduce(0) do |result, ingredient|

      result += result + INGREDIENT_PRICES[ingredient]

    end

  end

end

Listing 5-6

Introduce Method prepare_duration

The new lines added are lines 20–22. Now, if you run the suite, you will get everything green, like this:

$ bundle exec rspec

Randomized with seed 8716

This is executed only once at the beginning of the specifications run

An ideal sandwich

  lets me add toppings

  is delicious

A coffee

  costs 1 euro

  takes 1 minute to prepare

  with milk

This is a hook that will be executed once for the "with milk" context examples

Milk has been added!

    takes 2 minutes to prepare

Milk has been added!

    costs 1.2 euro

Finished in 0.01081 seconds (files took 0.24569 seconds to load)

6 examples, 0 failures

Randomized with seed 8716

$

Note

before(:all) is also available as before(:context).

subject

Let’s now talk about another technique and best practice that you will frequently encounter. It is about the subject under test.

In that case, you can use the method subject inside your example code. Then the subject is going to be an instance of that class, instantiated with the default initializer.

Now the Coffee string is printed as the outermost describe description.

You have removed the let(:coffee)... and all the coffee references. You are now using the subject instead.

If you run your specs for the Coffee, you will see that they will succeed.

So subject saves a little bit of typing, but the problem is that it hides the semantic meaning of the subject under test and the firing phase code is not really easy to understand quickly what it is about. In other words, the coffee.prepare_duration is much more descriptive and friendly to the reader rather than the subject.prepare_duration.

This version goes back to be using coffee instead of subject inside the example code. But the coffee is defined in terms of the subject.

On line spec/sandwich_spec.rb:5, you are calling subject which internally calls the Sandwich initializer without any arguments. That’s why you are getting ArgumentError and (0 for 2), that is, the initializer has been called with no arguments when two were expected.

You create a named subject, you give it the name sandwich, and then you can use it in your example code.

One might ask, “Why would you want to do that and not just use let?” The answer is that I prefer to use subject to indicate the subject under test. I use let for other helper methods that I might need for my tests.

Note that subject is being memoized and evaluated only once within the execution of an example. So, even if your example calls the named subject multiple times, only the first time is being evaluated, as the let does.

Finally, both subject and let have the alternative subject! and let!, respectively. The subject! and let! evaluate their blocks before the example execution (whereas the subject and let are lazily evaluated at the first occurrence within the example code).

Extending RSpec with Helper Methods in Modules

You have learned how to create helper methods inside an example group. It has been presented in the previous chapter. Those methods were available inside the context in which they were defined, but not outside of it.

RSpec offers you the ability to define helper methods that can be used by any context, since they are attached at the RSpec configuration level.

How do you do that?

This module defines a helper method that takes a string value and returns it with all characters upcased. Also, it adds an extra space after each character (except the last one).

In order for you to be able to use this helper method, you need to attach the module to the RSpec configuration as follows:

And in order for the UpcasedAndLineSpaced constant to be found, you will have to require the module file before the RSpec.configure block.

You have added a new specification. See lines 12–14. It is there where you call the upcased_and_line_spaced helper method.

This is a very common practice with RSpec. You will encounter it in many projects. Note that when you do config.include <module>, the methods become available inside the example code. However, when you do config.extend <module>, the methods become available inside the do..end blocks of the describes and contexts.

Metadata

RSpec builds a set of metadata around your example groups and examples. Also, it allows you to build your custom metadata.

Custom Metadata

RSpec allows you to attach metadata to example groups or examples. The metadata are given in the form of a Hash as the last argument to describe, context, or it, before the block definition.

Here is an example: You are going to define some metadata in the spec/sandwich_spec.rb file (Listing 5-16).

# File: spec/sandwich_spec.rb

#

RSpec.describe Sandwich, test: :unit do

  subject(:sandwich) do

    described_class.new('delicious', [])

  end

  it 'is delicious' do

    expect(sandwich.taste).to eq('delicious')

  end

  it 'is displayed as D E L I C I O U S' do

    expect(upcased_and_line_spaced(sandwich.taste)).to eq('D E L I C I O U S')

  end

  it 'lets me add toppings' do

    sandwich.toppings << 'cheese'

    expect(sandwich.toppings).not_to be_empty

  end

end

Listing 5-16

Example of Custom Metadata

The enhancement is on line 3 only (Figure 5-4).

You have attached the metadata test: :unit.

Metadata are available inside the example code. They are available via the example reference that can optionally be defined as the argument to the example do..end block. See how the example is displayed as D E L I C I O U S has access to this variable and to the metadata (Listing 5-17).

# File: spec/sandwich_spec.rb

#

RSpec.describe Sandwich, test: :unit do

  subject(:sandwich) do

    described_class.new('delicious', [])

  end

  it 'is delicious' do

    expect(sandwich.taste).to eq('delicious')

  end

  it 'is displayed as D E L I C I O U S' do |example|

    puts "Type of test: #{example.metadata[:test]}"

    expect(upcased_and_line_spaced(sandwich.taste)).to eq('D E L I C I O U S')

  end

  it 'lets me add toppings' do

    sandwich.toppings << 'cheese'

    expect(sandwich.toppings).not_to be_empty

  end

end

Listing 5-17

Access Metadata

In Figure 5-5, I am highlighting the relevant parts of the code.

Note that the metadata are being inherited from the example group to all the enclosed examples and other example groups (describes or contexts). And each contained example group or example can add more metadata or override the value of metadata inherited.

See how spec on line 18 now overrides the value of the :test metadata key (Figure 5-6).

The new version of the spec/sandwich_spec.rb is as shown in Listing 5-18.

# File: spec/sandwich_spec.rb

#

RSpec.describe Sandwich, test: :unit do

  subject(:sandwich) do

    described_class.new('delicious', [])

  end

  it 'is delicious' do

    expect(sandwich.taste).to eq('delicious')

  end

  it 'is displayed as D E L I C I O U S' do |example|

    puts "Type of test: #{example.metadata[:test]}"

    expect(upcased_and_line_spaced(sandwich.taste)).to eq('D E L I C I O U S')

  end

  it 'lets me add toppings', test: :integration do |example|

    puts "Type of test: #{example.metadata[:test]}"

    sandwich.toppings << 'cheese'

    expect(sandwich.toppings).not_to be_empty

  end

end

Listing 5-18

Override Metadata Values

Now, let’s run the spec/sandwich_spec.rb specs:

$ bundle exec rspec spec/sandwich_spec.rb

Randomized with seed 65045

This is executed only once at the beginning of the specifications run

Sandwich

Type of test: integration

  lets me add toppings

Type of test: unit

  is displayed as D E L I C I O U S

  is delicious

Finished in 0.00841 seconds (files took 0.21139 seconds to load)

3 examples, 0 failures

Randomized with seed 65045

$

As you can see in the preceding code, the lets me add toppings has type of test integration, whereas the is displayed as D E L I C I O U S has type of test unit.

Finally, if you want to set a metadata key to the value true, you can always give the key without the value. Here is an example:

it 'order contains 5 items`, :wip do

   ...

end

In this example, you are attaching the metadata key :wip. This is attached with the value true, even if you have not explicitly set that.

Tasks and Quizzes

This chapter is coming both with a quiz and a task.

Task Details

Write a Ruby Class And Cover It With RSPEC SPECS

You will need to write a Ruby class that would satisfy the following requirements:

NumberEachLine

  prefixes each line with an increasing integer number starting at 1

  when it is configured to start the line count at 8

    prefixes each line with an increasing integer number starting at 8

  when it is configured to pad each number with leading zeros

    prefixes each line with an increasing integer padded with leading zeros

    when it is configured to pad each number with leading blanks

      prefixes each line with an increasing integer padded with leading blanks

    when number of lines does not justify padding

      does not pad with leading zeros

  when it is configured to prefix each line with #

    prefixes each line with an increasing integer number starting at 1 and prefix each line being #

    and when it is configured to pad each number with leading zeros

      prefixes each line with an increasing integer number starting at 1 and pads each number with leading zeros and prefixes the line with #

  when it is configured to suffix each line number with ". "

    prefixes each line with an increasing integer number starting at 1 and suffix on numbers being ". "

  when input is

class Hello

  def initialize(name)

    @name = name

  end

  def greetings

    puts "Hello RSpec::ExampleGroups::NumberEachLine"

  end

  def name

    @name

  end

end

 and we configure pad of numbers with blanks and suffix number with '. '

    generates the following

 1. class Hello

 2.   def initialize(name)

 3.     @name = name

 4.   end

 5.

 6.   def greetings

 7.     puts "Hello RSpec::ExampleGroups::NumberEachLine"

 8.   end

 9.

10.   def name

11.     @name

12.   end

13. end

Finished in 0.00232 seconds (files took 0.07316 seconds to load)

9 examples, 0 failures

The preceding code is a sample output of the RSpec dry run for the requirements of the class. And the following screenshot is a colored output that might be more helpful to you (Figure 5-7).

But let me give you some more details:

1. (1)

   The purpose of this class is to take as input a multiline string and return back each line of the string being suffixed with its corresponding line number. For example, if you have the string

   This is a multi-line

   string. This is second line

   And this is third line

   the class should return back this:

   1This is a multi-line

   2string. This is second line

   3And this is third line
    
2. (2)
   Besides this main functionality, the class should allow for some kind of configuration. For example, you want to tell that each number should be suffixed with the string ". ". If you say that, then the returned string should be something like this:

   1. This is a multi-line

   2. string. This is second line

   3. And this is third line
    
3. (3)
   Or you may say that the line numbering should start from 8, not 1. In that case, the output should be something like this:

   8This is a multi-line

   9string. This is second line

   10And this is third line
    
4. (4)
   You may also say that you want each number to be padded with 0s or other character sequence. For example, assuming that you want the numbers to be padded with blanks, the input is

   This is a multi-line

   string. This is a second line

   And this is the third line

   And this is the fourth line

   And this is the fifth line

   And this is the sixth line

   And this is the seventh line

   And this is the eighth line

   And this is the ninth line

   And this is the tenth line

   And this is the eleventh line

   And then the output will be

    1This is a multi-line

    2string. This is a second line

    3And this is the third line

    4And this is the fourth line

    5And this is the fifth line

    6And this is the sixth line

    7And this is the seventh line

    8And this is the eighth line

    9And this is the ninth line

   10And this is the tenth line

   11And this is the eleventh line
    
5. (5)
   However, when the number of lines does not justify padding, then padding will not be used even if specified. Hence, if you specify that you want padding with 0s but the input is less than ten lines long, then no padding will take place. In other words, the input

   line 1

   line 2

   is output as

   1line 1

   2line 2
    
6. (6)

   You may also ask the class to prefix each line with a prefix string. Assume that you have the following input and the prefix you want to attach to each line is '#':

   line 1

   line 2
    

Then the output will be

#1line1

#2line2

So let’s summarize the configuration options:

1. 1.

   Starting Number: Default value is 1.

    
2. 2.

   Pad Numbers With: A string to pad numbers with. Numbers are right justified, and the padding string is repeated to the left.

    
3. 3.

   Suffix Number With: A string to suffix each number with.

    
4. 4.

   Prefix Line With: A string to prefix each line with.

    

Please note that you don’t have to stick to the RSpec specifications that would give the same output as the one presented at the top of this task. You can come up with your own implementation for the RSpec specifications. What I want you to do is to implement the class and make sure that it is well test covered.

Note that this task is inspired by this online text mechanics page: http://textmechanic.com/text-tools/numeration-tools/number-each-line/.

Key Takeaways

In the following chapter, you will be introduced to another very popular tool that lives in the BDD (Behavior-Driven Development): Cucumber. Cucumber allows you to write your specifications in plain English.