The Definitive RSpec Tutorial With Examples | Agira Technologies
loader image
Ruby on Rails

The Definitive RSpec Tutorial With Examples

RSpec is a testing tool for Ruby programmers. RSpec is a Behaviour-Driven Development (BDD) tool. Tests written in RSpec focus on the “behavior” of an application being tested. RSpec does not put emphasis on how the application works but instead on how it behaves, in other words, what the application actually does. RSpec is a DSL for writing tests. In other words, it tries to make tests as readable as possible. Not only that, it also produces output that reads like a story, or spec (“specification”), hence the name.

Setting up RSpec

From the terminal, you can run the following command to install the rspec,

Once the installation is completed now you can change the path to the project directory and run the rspec – -init it will initialize the rspec within the project.

It will create the following file under the project directory,

That’s it the setup is completed. Now we can run the rspec test it will return the following output,

Structure of RSpec

RSpec uses the words “describe” and “it” so we can express concepts like a conversation. describe defines a collection of tests . It takes a class or a string as an argument and is passed a block (do/end).

Next it keyword defines an individual example (test). it takes a string argument and passes the block. This block is where our expectations of a method are expressed.

Testing with RSpec

For this tutorial, I am going to explain the simple application to find adding two numbers by writing a simple calculator function. Now we will create the calculator_spec.rb file under the spec directory and add the following code,

When we run the test we will get the following error,

An error occurred while loading ./spec/calculator_spec.rb.

We will get the NameError because we don’t have a Calculator class. From our project root we will create a lib/ folder, and inside, calculator.rb file. And require this file in calculator_spec.rb file.

Now we will run the test it will show the NoMethodError like following,

Now we will create add within the calculator.rb file and add the following line

If we were to run rspec this time, we will get our first failure.

RSpec clearly provides a reason for the failure: it expected the output to be 7 when we provided the method with (5, 2) as the parameters. Instead, it returned nil. Now we can implement the add method to return the sum of two numbers.

Then, we will run the test again and it will display a single dot, letting us know that our test has passed.


Nested Groups

If we are going to test different scenarios of our app, we will group the related test together. We can achieve this using the describe or context methods in Rspec.

For Example,

RSpec Matchers

We’ve discussed how methods such as describe and context are used to set up a structure for our tests, and how it adds an actual test to it. Let’s look at our code again:

What does expect do, exactly? And what’s the deal with to and eq.

The expect returns an object that responds to the method to. This method to expects to be passed an object that is called matcher. Here eq is matcher. RSpec matchers compare the output of our method with our expected value.

ALSO READ: How To Build A Dating App Like Tinder

RSpec also provide the option to test the Errors as well,

RSpec also allows you to use matchers that depend on the methods defined on the object passed. We also call these are magic matchers. For Example,

The matcher be_nil expects the method nil? to be defined on the object under test. The method nil? is defined on every object in Ruby. And in our case, nil.nil? returns true, of course, so the test would pass.
This test, however, would not pass:

Because of true.nil? returns false.

For more details, you can read here for all available matchers.

RSpec Formatters

The Rspec provides the following different type of format for running the test.

  • progress
  • documentation
  • JSON
  • HTML

We can run the RSpec with the specific format by using the – -format or -f with a specific option.


The default RSpec output is in the “progress” format. In this format, we can see a single dot (.) for the passed test, F for a failed test, E for an error and * for a pending test.


We will run RSpec’s documentation format by passing the command line option – -format documentation. With all tests passing the output will look like the document.

json option will print the output as json format and html will print the output as html format.

ALSO READ: How To Develop A Healthcare Mobile Application For Hospitals

If we want to store the output as file, we need to pass the – -out option with filename, it will store the output in the file.

RSpec also supports running the test with multiple formats at the same time. Let’s consider we want to store the output as html format and also we want to see the progress of the tests. We will achieve this like following

It will store the html output to calculator.html file and print the following output in terminal

Advanced Use Case


RSpec provides the execution hooks using these we can run some code before, after or around the test.


If we want to reuse the same objects for many test cases we can define these objects using let. Using let the variable lazy loads only when it is used the first time in the test and get cached until that specific test is finished.

For example,

From the above code, we have reused the calculator object for all out tests.

Use let! if we want to define the variable when the block is defined. This can be useful to populate your database to test queries or scopes. Let! is a nonlazy method, the object will be created before running any test


If we have several tests related to the same subject use subject{} to DRY them up. The subject is another version of let.

We can declare the subject like following,

The subject will behave the same as let, but it enables the use of one line expectations like following,

Command-line options

The rspec command comes with several options you can use to customize RSpec’s
behavior, including output formats, filtering examples, etc.

ALSO READ: MongoDB In Golang With Examples – A Beginner’s Guide

For a full list of options, run the rspec command with the – -help flag:
$ rspec – -help

– –init option generates the conventional files for an RSpec project.
– – format option to tell RSpec how to format the output.
– –tag option to filter the tests by tags.
– –order option to tell RSpec how to order the files, groups, and tests.
– –out Write output to a file instead of $stdout. This option applies to the previously specified – –format, or the default format if no format is specified.
– –profile option tells us how long each test is taken to run.

Do you find it interesting? you might also like these articles. Top 10 Best Tech Companies For Employees To Work In The USA In 2020 and Top 10 IT Staffing and Recruiting Agencies in the USA.

If you have a business idea in your mind and in search of a reliable web development company, you are in the right place. Hire the best Ruby on Rails developers in the industry from Agira technologies.

Looking for a Tech partner to dominate the digital world?
The following two tabs change content below.
Arjunan Subramani

Arjunan Subramani

Senior Software Engineer | Around 4 Years of experience in Web development and Testing arena. Plus, hands on expertise in Ruby, Ruby on Rails, Watir, Ruby Cucumber.
Arjunan Subramani

Latest posts by Arjunan Subramani (see all)

Leave a Reply

Your email address will not be published. Required fields are marked *

Join our 30,000+ subscribers, never miss out anything on our latest blogs, tips, tutorials, updates & more.