In the first article, How to use rspec to test GroupDocs API. Part 1, we created first test for GroupDocs API. This article describes in details how tests works, what expectation and matchers are, and how to test an API with the PULL method.
Expectation and Matchers
So what are expectation and matchers? Lets look at a small example:
Expectations are defined by should and the negative form should_not.
Matchers are defined by have(9).characters and have(5).characters.
I should also mention that spec (specification) is a description of how some part of your application should work (in our case, one of the GroupDocs API methods). Lets take the get_user_profile_spec.rb file that we created in the last article and describe what that code is doing.
require 'spec_helper'
describe 'User' do
describe 'GetUserProfile' do
include_context :api_tests
let(:request) do
GroupDocs::Api::Request.new method: 'GET',
path: '/mgmt/{{client_id}}/profile'
end
it 'returns not empty user hash' do
response[:user].should_not be_empty
end
it 'returns user identifier' do
response[:user][:id].should be_a(Fixnum)
end
it 'returns user primary email' do
response[:user][:primary_email].should == "" # your primary email here
end
it 'returns user private key' do
response[:user][:pkey].should == "" # your private key here
end
end
end
We use require 'spec_helper' to include some configuration and helper functions. The describe method creates a group. This method could be nested with others like in the code: we’re testing the GetUserProfile method, a part of User API. Sometimes you’ll see the context method. This is just an alias for describe. The two methods have no functional difference, instead the difference is contextual to
make tests more understandable.
Example of simple Group
Create a file called sample_spec.rb with the following code:
describe "something" do
it "does something" do
end
end
Run the following command in a console: rspec sample_spec.rb -fn You’ll get something like this:
Different Types of Matchers
Now lets find what kinds of matchers there are. In the get_user_profile_spec.rb, when we test a response from the server we use a separate it block for each parameter we want to check. We use only 3 of all possible matchers: be_empty, be_a(), == . For your tests you can use: Test validity and existance:
be_true - check is true (not nil or false)
be_false - check is false (nil or false)
be_nil - check is nil
There are a lot of other built-in matchers in rspec. You can find a full list online. If you need some special functionality you can create you own matchers.
Adding a Test
Now lets add one more test for the UpdateUserProfile API method. We will use the PUT method and json file for parameters. In the user folder, create a file called update_user_profile_spec.rb with the following content:
require 'spec_helper'
describe 'User' do
describe 'UpdateUserProfile' do
include_context :api_tests
let(:payload) { payload_file(:update_user_profile) }
let(:request) do
GroupDocs::Api::Request.new method: 'PUT',
path: "/mgmt/#{payload[:guid]}/profile",
request_body: payload
end
it 'returns response array' do
response.should_not be_empty
end
end
end
payload_file
Here we use one new function, payload_file. We need to add it to our spec_helper.rb file where it will look like this:
require 'groupdocs'
require 'json'
#
# Parses payload JSON file.
#
# @param [String] filename
# @return [Hash]
#
def payload_file(filename)
file = File.read("#{File.dirname(__FILE__)}/../payload/#{filename}.json")
JSON.parse(file, symbolize_names: true)
end
RSpec.configure do |spec|
# configure API access
GroupDocs.configure do |groupdocs|
groupdocs.api_server = "https://api.groupdocs.com"
groupdocs.api_version = "2.0"
groupdocs.client_id = ''
groupdocs.private_key = ''
end
# share API tests methods
spec.shared_context :api_tests do
let(:response) do |spec|
response = request.execute!
end
end
end
update_user_profile.json
Now all we need to do, is create a update_user_profile.json file in the paylod directory (/groupdocs_tests/paylod/update_user_profile.json):
