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 MatchersSo 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 GroupCreate 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 MatchersNow 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 TestNow 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


payload_fileHere 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!


update_user_profile.jsonNow 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