Learning Goals

Introduction

There is also the gem rspec that, when installed, installs all the other gems. And this is the gem that you are going to install here.

New Project

Let’s create a new project, named coffee_shop. It needs to be a Ruby project with Ruby 2.x installed. Start that project in RubyMine. Moreover, make sure that you have the rbenv integration with the .ruby-version file specified having the version of the Ruby you are using. For example, my .ruby-version file, in the root folder of my project, has the content 2.6.5 (Figure 4-2).

Here is a screenshot of your project in RubyMine (Figure 4-3).

rspec Version

You can see that the version of RSpec at the time of writing is 3.9. You may have a later version installed on your machine. But any version 3.x will do.

Initialize RSpec

RSpec Configuration

The spec/spec_helper.rb file initially contains a call to the RSpec.configure method that is used to configure the RSpec behavior. RSpec comes with some sensible defaults, and if you read the comments in the spec/spec_helper.rb file, you can switch on/off anything that you feel like doing so.

are not commented out.

Inside the spec Folder

When you worked with minitest, your tests lived inside the folder test. RSpec assumes that all your tests are going to live inside the folder spec, or any of its subfolders. Also, the files that are going to be considered test files are the ones that will have a filename ending in _spec.rb. Hence, the file spec/spec_helper.rb is not considered a file with tests, whereas, if we had the file with the name spec/customer_spec.rb, this would have been considered a file with tests.

Describing

Let’s assume that you want to model the ideal sandwich, just to start with something more fun.

RSpec is using the words describe and it to express concepts of your model in a conversational format.

See this dialog in Figure 4-4.

This is a spec file. I use the word spec or specification rather than test when I am in the context of RSpec.

In fact, when you are in the RSpec context, you say that the spec file contains/defines example groups. Each example group is defined using the RSpec.describe call.

The first argument to the RSpec.describe call is the documentation (or description or name) string for the particular example group. The do ... end block that is sent to RSpec.describe defines the body of the example group. The body usually defines one or more examples. Each example is defined with the call to method it. An example group may have many calls to it, and each one is going to be a different example in the example group. The first argument to it is the documentation (or description or name) string for the particular example. The block do ... end that is sent to it is the actual implementation of the example (Figure 4-5).

Sanity Check

It is clearly mentioning that spec/sandwich_spec.rb failed at line 5: expect(true).to eq(false). This seems to be quite easy to explain (Figure 4-6).

The example line that exercises the expectation of the specification, expect(true).to eq(false), is mentioning that the value true, which is the actual value, needs to be equal to the value false, which is the expected value. And since true is not equal to false, the specification fails when evaluated by the RSpec runner.

Nice! This is reporting 1 example, 0 failures. You can see the green . implying one example has been successfully evaluated.

Documentation Formatter

The RSpec runner comes with a very useful results formatter. It prints out the specs (each describe and it documentation string) in a nested/tree-like format which finally works as a very good documentation of your project specifications.

part of the output? These are the describe and it documentation/name strings in your spec file. You can also see that the example that ran successfully is displayed with green color.

And then try to run again your specs by simply giving bundle exec rspec. You will see that the output is using the documentation formatter.

Let’s Write a Real Specification

Now that you have set the scene to be able to run your specs, let’s write your first real specification for the sandwich model. Remember that you are doing TDD/BDD. So you first write the specs and then the implementation in the core code that satisfies the specs.

However, usually, you find only three phases, as you have in the preceding example. See Figure 4-7.

Keep this in your mind whenever you design a test. You need to make sure you understand where is the setup code, where is the fire code, and where is the assertion code. If this is not clear from your code, then you need to make it be. Tests need to be simple and easy to identify those phases.

You can now see that the fire phase has been mixed with the assertion phase. But, even so, the test is still clear and the reader can understand that the part inside the expect(....) parentheses is the fire part (Figure 4-8).

Before you give a go to run the preceding spec, let’s also tell something about the expect method. The expect method call takes as argument the actual value. Then you can call an expectation target. In your case, this is .to. The expectation target then takes as an argument an RSpec matcher. In your example, this is the eq() method call. I will talk about all these in more detail later on. But, until then, you can read the expect(<actual>).to eq(<expected>) as we expect the value <actual> to be equal to the value <expected>. If the expectation fails, then expect raises the exception RSpec tools::Expectations::ExpectationNotMetError and terminates the example execution considering that as failed (Figure 4-9).

Run and Watch That Fail and Then Fix It

Sharing Setup Code

You can see that between lines 10 and 16. The actual is sandwich.toppings, and the expectation is that it should not be empty.

However, there is a repetition in the example file (Figure 4-10).

You can see that the setup code is repeated at the beginning of your two examples. If you had many more, that repetition would increase the cost of changing and maintaining the setup phase of these examples. Can you DRY (Do not Repeat Yourself) the example group code?

Yes, you can. RSpec offers various ways you can do this.

before Hook

One way you can put your common setup code into one place is to use the before hook . The before hook hosts a piece of code that will be executed before the execution of every example.

Let’s do that for the spec/sandwich_spec.rb file (Listing 4-15).

# File: spec/sandwich_spec.rb

#

RSpec.describe 'An ideal sandwich' do

  before do

    @sandwich = Sandwich.new('delicious', [])

  end

  it 'is delicious' do

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

  end

  it 'lets me add toppings' do

    @sandwich.toppings << 'cheese'

    expect(@sandwich.toppings).not_to be_empty

  end

end

Listing 4-15

Use of the before Block

Inside the body of the block that is attached to the RSpec.describe call, you use the method before with a block attached. This is the way you define code that you want to be executed every time an example starts. Hence

1. 1.

   Before the example is delicious, the runner will instantiate the variable @sandwich with the value Sandwich.new('delicious', []).

    
2. 2.

   Then it will execute the is delicious code.

    
3. 3.

   Then it will clear all the memory that is related to the example that finished before starting the next example.

    
4. 4.

   Before the example lets me add toppings, it will execute the code inside the before block. It will instantiate a new @sandwich instance.

    
5. 5.

   Then it will execute the code for the example lets me add toppings.

    

And so on.

The technique used here, with the before hook, eliminates the need to have the setup code written multiple times. However, you need to turn your local sandwich variables to references to the instance variable @sandwich (Figure 4-11).

The before hooks are great if you want to prepare the common setup of your examples. They are also very useful if this has to do with things that need to take place in a world outside of your application, for example, to clean up the database that your application might be accessing. You might want every example to run on a clean database.

However, when it comes to instantiating variables, the before hook is not very handy. The maintenance of the instance variable is error prone and involves lots of find/and/replace actions with your editor.

Share with let

The preceding let binds the block of code Sandwich.new('delicious', []) to the name sandwich. Then you can use the sandwich name in your examples. The sandwich will be evaluated only once, and subsequent calls will use the first-time evaluated value.

If you save and run your tests, you will see that everything is green again.

Context

RSpec uses one more method of grouping examples, tests. This is called context , and it is no different from RSpec.describe. Actually, it is an alias to RSpec.describe. The point is that with context, you make the grouping of the examples more intuitive since you group examples according to the context the examples assume they live in.

This is a nice formatted output of your specs without any evaluation. But it is displaying how you have structured your specs. See how the with milk context is creating a new indentation for the examples that it is grouping (Figure 4-12).

You can see how the context created a new block of indented documentation for the grouped examples.

Something else that you need to be aware of is that context can create before hooks as the describe does. And the before hooks are evaluated only for the examples that belong to the particular context.

Running Specific Examples

You can see that you have two failures, both coming from the spec/coffee_spec.rb file.

As you can see, you just run only the examples inside the file spec/coffee_spec.rb.

Let’s try to fix the first of the examples that is failing.

Nice! Only one failure, for the example A coffee with milk costs 1.2 euro.

Imagine that your spec/coffee_spec.rb file contains many more examples, but you only want to run the particular one that failed. How can you do that? You will do that by specifying both the filename and the line number corresponding to the failing example. Actually, the last rspec run gives you the command ready to copy and paste into your terminal (Figure 4-13).

Everything is green. If you want, be happy to refactor the implementation. If refactoring breaks any of the application specifications, you will know that by running the whole test suite again.

RubyMine Integration

Before you continue with more advanced topics on Rspec, let’s make sure that you can run your RSpec suite from within RubyMine.

Right-click your project name, in the RubyMine project explorer, and then select to run all specs in your project, as in the following screenshot (Figure 4-14).

When you do that, RubyMine will execute all the specs in your project (Figure 4-15).

You can even run an individual file. Just right-click and select to run the particular file, as in Figure 4-16 for the sandwich_spec.rb.

The result will appear again at the bottom tab of RubyMine.

And, finally, you can run an individual example or example group. In the following screenshot, I show how I right-click inside the example lets me add toppings and then I select to run the particular example (Figure 4-17).

Note that every time you run your specs through RubyMine, it creates a run configuration, and you can re-execute it with the click of a button (Figure 4-18).

Before I close these notes about the integration with RubyMine, I would like to make you aware of the keyboard shortcuts that can be used to execute the whole suite or a specific example. For example, on my Mac, when the cursor is inside an example, then I can press the keyboard combination Ctrl+Shift+R, and it will run the rspec for the particular example (or context/describe if my cursor is in a context/describe).

Task Details

WRITE TESTS USING RSPEC

You are requested to implement a class that will satisfy the following requirements:

A Mad Libs Story Teller

  when it gets the story template 'A ((an animal)) in the ((a body part)) is worth ((a number)) in the ((a place))'

    then its third question to ask is 'Give me a number'

    then its fourth question to ask is 'Give me a place'

    then its first question to ask is 'Give me an animal'

    then its second question to ask is 'Give me a body part'

    and words for placeholders 'cat', 'hand', 'twelve' and 'London'

      produces the story 'A cat in the hand is worth twelve in the London'

  when it gets the story template 'I had a ((an adjective)) sandwich for lunch today. It dripped all over my ((a body part)) and ((a noun))'

    then its second question to ask is 'Give me a body part'

    then its third question to ask is 'Give me a noun'

    then its first question to ask is 'Give me an adjective'

    and words for placeholders 'smelly', 'big toe' and 'bathtub'

      produces the story 'I had a smelly sandwich for lunch today. It dripped all over my big toe and bathtub'

Finished in 0.00213 seconds (files took 0.07707 seconds to load)

9 examples, 0 failures

This is the screenshot of the output of the RSpec documentation that might be easier for you to read (Figure 4-19).

This exercise is based on the following business requirements:

There is a game called Mad Libs. This is based on a story template. For example, “I ((a verb)) to eat ((a food)).” This story template has two placeholders: the “((a verb))” and the “((a food)).” The game is played with one person holding the story template hidden from the others. But this person asks them questions based on the placeholder content. For this example, the first question is “Give me a verb.” And the second question is “Give me a food.” The other person answers, and the person who holds the story template compiles the story based on these answers. Hence, if the person who answers gives the answers “run” and “pizza,” then the story that is compiled is “I run to eat pizza.”

What you have to implement is not the whole interaction of the game, just the class that has the business rules the game relies on.

In fact, you need to implement that behavior that is documented by the RSpec documentation output that you see in the preceding figure. You have to implement both the class that satisfies these requirements and the RSpec specs that describe them.

Key Takeaways

RSpec is very powerful. In the next chapter, you are going to learn what extra tools it offers.