1. 介紹

RESTinstance庫是用來測試RESTful風格API介面的robot framework測試庫。不同於RequestsLibrary庫，RESTinstance庫有如下一些優勢。

2. 優勢

• RESTinstance基於Robot Framework的程式語言無關性，乾淨和簡潔的語法來進行API測試。
• 使用JSON Schema來驗證JSON語義，指導使用者基於屬性來編寫API測試用例。
• 自動生成requests和responses的JSON Schema，通過測試Schema會變得更加精確。

詳細的優勢資訊請檢視連結

3. 安裝

提供了幾種安裝方式，你可以選擇最適合的一種。

3.1 python庫安裝

在Python 3.x或者2.7版本，可以通過安裝或者升級命令來安裝：

pip install --upgrade RESTinstance

3.2 Docker映象方式

RESTinstance Docker映象包含了python3.6執行環境和最新的robot framework版本：

docker pull asyrjasalo/restinstance
docker run --rm -ti --env HOST_UID=$(id -u) --env HOST_GID=$(id -g) \
  --env HTTP_PROXY --env HTTPS_PROXY --network host \
  --volume "$PWD/tests":/home/robot/tests \
  --volume "$PWD/results":/home/robot/results \
  asyrjasalo/restinstance tests

4. 使用

4.1 快速啟動

建議：用Robot Framework執行下面的例子README.rst

*** Settings ***
Library         REST    https://jsonplaceholder.typicode.com
Documentation   Test data can be read from variables and files.
...             Both JSON and Python type systems are supported for inputs.
...             Every request creates a so-called instance. Can be `Output`.
...             Most keywords are effective only for the last instance.
...             Initial schemas are autogenerated for request and response.
...             You can make them more detailed by using assertion keywords.
...             The assertion keywords correspond to the JSON types.
...             They take in either path to the property or a JSONPath query.
...             Using (enum) values in tests optional. Only type is required.
...             All the JSON Schema validation keywords are also supported.
...             Thus, there is no need to write any own validation logic.
...             Not a long path from schemas to full Swagger/OpenAPI specs.
...             The persistence of the created instances is the test suite.
...             Use keyword `Rest instances` to output the created instances.


*** Variables ***
${json}         { "id": 11, "name": "Gil Alexander" }
&{dict}         name=Julie Langford


*** Test Cases ***
GET an existing user, notice how the schema gets more accurate
    GET         /users/1                  # this creates a new instance
    Output      schema response body
    Object      response body             # values are fully optional
    Integer     response body id          1
    String      response body name        Leanne Graham
    [Teardown]  Output                    # note the updated response schema

GET existing users, use JSONPath for very short but powerful queries
    GET         /users?_limit=5           # further assertions are to this
    Array       response body
    Integer     $[0].id                   1           # first id is 1
    String      $[0]..lat                 -37.3159    # any matching child
    Integer     $..id                     maximum=5   # multiple matches
    [Teardown]  Output  $[*].email        # outputs all emails as an array

POST with valid params to create a new user, can be output to a file
    POST        /users                    ${json}
    Integer     response status           201
    [Teardown]  Output  response body     ${OUTPUTDIR}/new_user.demo.json

PUT with valid params to update the existing user, values matter here
    PUT         /users/2                  { "isCoding": true }
    Boolean     response body isCoding    true
    PUT         /users/2                  { "sleep": null }
    Null        response body sleep
    PUT         /users/2                  { "pockets": "", "money": 0.02 }
    String      response body pockets     ${EMPTY}
    Number      response body money       0.02
    Missing     response body moving      # fails if property moving exists

PATCH with valid params, reusing response properties as a new payload
    &{res}=     GET   /users/3
    String      $.name                    Clementine Bauch
    PATCH       /users/4                  { "name": "${res.body['name']}" }
    String      $.name                    Clementine Bauch
    PATCH       /users/5                  ${dict}
    String      $.name                    ${dict.name}

DELETE the existing successfully, save the history of all requests
    DELETE      /users/6                  # status can be any of the below
    Integer     response status           200    202     204
    Rest instances  ${OUTPUTDIR}/all.demo.json  # all the instances so far

5. 對比

我們來分別用RequestsLibrary和RESTinstance來編寫介面自動化測試用例，這樣就可以直觀地進行對比。
我們假設http://echo.jsontest.com/framework/robot-framework/api/rest會返回如下值：

{
   "api": "rest",
   "framework": "robot-framework"
}

RequestsLibary實現

*** settings ***
Library  Collections
Library  requests
 
*** test cases ***
simpleRequest
    ${result} =  get  http://echo.jsontest.com/framework/robot-framework/api/rest
    Should Be Equal  ${result.status_code}  ${200}
    ${json} =  Set Variable  ${result.json()}
    ${framework} =  Get From Dictionary  ${json}  framework
    Should Be Equal  ${framework}  robot-framework
    ${api} =  Get From Dictionary  ${json}  api
    Should Be Equal  ${api}  rest

RESTinstance實現

*** settings ***
Library  REST  http://echo.jsontest.com
 
*** test cases ***
simpleRequest
    GET  /framework/robot-framework/api/rest
    Object  response body
    String  response body api  rest  
    String  response body framework  robot-framework

從以上兩個測試用例中，我們就可以很容易看出來哪個庫更方便使用了。

6. 結論

RESTinstance庫比RequestsLibrary庫更適合RESTful風格的HTTP API測試。