It's not uncommon for our web apps to have features that make API calls to external services. In fact, if you have an application that is heavily reliant on external services, it can make integration testing a nightmare for you and your team.
In this guide, I'll show you how we can use built in RSpec features like Instance Doubles and Shared Contexts to make integration testing a breeze in our Ruby on Rails applications.
The Scenario
Imagine we're building a project management web app that heavily relies on GitLab for file management. When a user creates a new project in our app, we have to create a project on gitlab.com using their API.
In general, we never want to call an external API during a test. Remember, our tests are there to test that in a given scenario, our code behaves correctly. It would take longer to run, risk exposing API credentials and create unwanted data on our external services if we talked to them during our tests.
Furthermore, it is safe to assume that GitLab has already thoroughly tested that their create project endpoint works. There's no need for our tests to cover that as well.
So, how do we test this kind of code repeatedly and efficiently, without creating a bunch of test data on gitlab.com?
Instance Doubles
The solution is to use Instance Doubles, which are also commonly referred to as Stubs or Mocks. They allow us to modify the behaviour of our code during a test.
For example, let's consider GitLab's POST https://gitlab.com/api/v1/projects
endpoint. In our application, we would use an instance of a Gitlab
client to make this request
gitlab_client = Gitlab.client(Settings.gitlab.hosted_client)
gitlab_client.create_project({...})
=> {"id" => 1, ...}
So, let's tell RSpec that every time our code calls gitlab_client.create_project({...})
, simply return some predefined hash instead of a real response from gitlab.com.
To implement this, we can simply define our expected response at the top of our spec like this:
# define our hardcoded expected response from GitLab
let(:project) { {"id" => 1, ...} }
# define an instance double
let(:gitlab_client) do
# override the return for the #project and #create_project methods on every instance of Gitlab::Client
instance_double(Gitlab::Client, project: project, create_project: project)
end
# Gitlab::Client.new will return our instance double from above, instead of a real gitlab client
before(:each) do
allow(Gitlab::Client).to receive(:new).and_return(gitlab_client)
end
Reusable Instance Doubles as Shared Contexts
We just saw how we can override our gitlab client during a test. But, it would be really tedious to write this out every time our code makes an API call to some service. Luckily, it's pretty easy to write this once and reuse it across tests, thanks to Shared Contexts.
Building on our previous example, let's define a shared context that will allow us to easily reuse our instance double:
# spec/support/shared_contexts/gitlab_client.rb
RSpec.shared_context "with gitlab client" do
# define our hardcoded expected response from GitLab
let(:project) { {"id" => 1, ...} }
# define an instance double
let(:gitlab_client) do
# override the return for the project and create_project methods on every instance of Gitlab::Client
instance_double(Gitlab::Client, project: project, create_project: project)
end
# Gitlab::Client.new will return our instance double from above, instead of a real gitlab client
before(:each) do
allow(Gitlab::Client).to receive(:new).and_return(gitlab_client)
end
end
That's it! To use it, we just need to remember to include it in any tests that interact with the gitlab client
RSpec.describe "/projects", type: :request do
include_context "with gitlab client" # important
describe "POST /projects" do
context "with valid parameters" do
it "creates a new project" do
# thanks to the include_context above,
# we can test our create project endpoint
# without worrying about GitLab
expect do
post projects_url, params: { project: build(:project).attributes }
end.to change(Project, :count).by(1)
end
end
end
end
Top comments (0)