How to use rspec to test GroupDocs API – Part 2

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:
string ="GroupDocs"
string.should have(9).characters
string.should_not have(5).characters
  • 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 method: 'GET',
                                  path:   '/mgmt/{{client_id}}/profile'

    it 'returns not empty user hash' do
      response[:user].should_not be_empty

    it 'returns user identifier' do
      response[:user][:id].should be_a(Fixnum)

    it 'returns user primary email' do
      response[:user][:primary_email].should == "" # your primary email here

    it 'returns user private key' do
      response[:user][:pkey].should == "" # your private key here

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
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
Test error raising:
expect { ... }.to raise_error
expect { ... }.to raise_error(ErrorClass)
expect { ... }.to raise_error("message")
expect { ... }.to raise_error(ErrorClass, "message")
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 method: 'PUT',
                                  path:   "/mgmt/#{payload[:guid]}/profile",
                                  request_body: payload

    it 'returns response array' do
      response.should_not be_empty



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.dirname(__FILE__)}/../payload/#{filename}.json")
  JSON.parse(file, symbolize_names: true)

RSpec.configure do |spec|

  # configure API access
  GroupDocs.configure do |groupdocs|
    groupdocs.api_server  = ""
    groupdocs.api_version = "2.0"
    groupdocs.client_id   = ''
    groupdocs.private_key = ''

  # share API tests methods
  spec.shared_context :api_tests do
    let(:response) do |spec|
      response = request.execute!



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):
        "nickname": "",
        "firstname": "firstname",
        "lastname": "lastname",

        "pswd_salt": "XWeSDIKH4vDc0StcdNhGCg==",
        "signedupOn": 1358920966590,
        "signedinOn": 1358920786590,
        "signin_count": 1,
        "roles": [
            "id": 2,
            "name": "Admin"
        "id": 452,
        "guid": "6dac05617fbfwer",
        "primary_email": ""
You need to provide your own parameters in the update_user_profile.json file. Now just enter this command in a terminal:
bundle exec rspec spec/user/update_user_profile_spec.rb