Skip to content

Testparser Writing test files

Jump to bottom Edit New page
Xenofon Spafaridis edited this page Feb 23, 2016 · 19 revisions

Contents

Proposed directory structure

The proposed tests directory files and requests are based on this example:

  • The directory /tests contains:

  • /base, for base API

  • /administrator, for administrator's API

  • In /base can use only GET method to the following endpoints:

  • GET /article, /article/{id}, /article/{id}/relationships/tag, /article/{id}/relationships/author

  • GET /tag, /tag/{id},

  • GET /user, /user/{id}

  • Example, we want to (test if there is)/(GET) an article with id "2". We would then test at the /article/2 url.

  • In another example, we want to (GET) the author of the article with id "2". We would then test at the /article/2/relationships/author url.

  • In /administrator, methods GET, POST, PATCH and DELETE can be applied to

  • /article: GET,POST

  • /article/{id}: GET, PATCH, DELETE

  • /tag: GET,POST

  • /tag/{id}: GET, PATCH, DELETE

  • Example, we want to test the administrator's accessibility to add content to an article with id "2". We would then test the PATCH verb at the /administrator/article/2 url.

Test file format

A JSON object MUST be at the root of every testparser test. This object defines a test's "top level". A test MUST contain the following top-level members:

  • request, object
  • response, object

A test MAY contain any of these top-level members:

  • meta, object

For example:

{
  "meta": {
  },
  "request": {
    "url": "article"
  },
  "response": {
    "statusCode": 200
  }
}

meta

The top-level meta object MAY contain any of the following members:

  • order, integer defaults is 0
  • description, string
  • ignore, boolean defaults is false
  • incomplete boolean|string default is false
  • JSONbody, boolean defaults is true

order

accepted value are integers between -99999999 and 99999999

request

The top-level request object MUST contain following members:

  • url, string.

The top-level request object MAY contain any of the following members:

  • method, string default is "GET"
  • headers, array
  • body, string|object|array of strings and objects
  • iterators, object

body

body member is optional HTTP request body which is send along with the request. body elements can one of:

  • a string, which is send as raw request body
  • a object, which is interpreted a JSON decoded, it will be encoded as JSON string before it is send, don't forget to set appropriate Content-Type request header required by the specifications of your server so that it can identify the request content type.
  • an array of string and body elements

For example:

{
  "request": {
    "url": "article",
    "method": "POST",
    "headers": [
      "Content-Type: application/x-www-form-urlencoded"
    ],
    "body": [
      "title=foo1",
      "title=foo2",
      "title=foo5"
    ]
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
    }
  }
}

The above example with create three tests in total.

{
  "request": {
    "url": "article/1",
    "method": "PATCH",
    "headers": [
      "Content-Type: application/json; charset=utf-8"
    ],
    "body": {
      "title": "foo"
    }
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
    }
  }
}

iterators

members of iterators are arrays, their key can be used as variable inside the testparser test so that all possible combinations are used and executed, when iterators or body of type array with multiple elements is specified the Testparser class is returning multiple Testphase objects.

For example:

{
  "request": {
    "url": "article/{{articleId}}/relationships/{{relationshipKey}}",
    "iterators": {
      "articleId": [1, 2, 3],
      "relationshipKey": ["tag", "author"]
    }
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
    }
  }
}

The above example with will create six tests in total.

response

The top-level response object MUST contain the following members:

  • statusCode, integer|integer[]

The top-level response object MAY contain any of the following members:

  • headers, object
  • timeout, integer when not specified default value is null
  • ruleObjects, object[]
  • export, object

statusCode

statusCode can be an integer or an array with integer elements. statusCode is used to validate response's HTTP response code. See HTTP/1.1 Response Status Codes

For example

{
  "request": {
    "url": "article"
  },
  "response": {
    "statusCode": 200
  }
}
{
  "request": {
    "url": "article"
  },
  "response": {
    "statusCode": [200, 201, 204]
  }
}

headers

Members of headers object are pairs of name, value where name is a HTTP header request field and value is the value of that header.

headers are used as a rule to validate the HTTP response's headers. See HTTP/1.1 Response Header Fields

For example

{
  "request": {
    "url": "article"
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
    }
  }
}

ruleObjects

Elements of ruleObjects are JSON Schema using phramework/validate library's implementation.

ruleObjects are used as a rule to validate the response body. NOTE top-level member meta's JSONbody member must be true in order to test JSON encoded response bodies.

For example (1):

{
  "request": {
    "url": "article/?page[limit]=1"
  },
  "response": {
    "statusCode": 200,
    "ruleObjects": [
      {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "maxItems": 1,
            "minItems": 0
          }
        }
      }
    ]
  }
}

The above JSON Schema ruleObject describes that in order to valid response body must be a JSON object, containing a member with name data, which is an JSON array and it must contain zero or one elements. NOTE we are requesting a collection of resource

For example (2):

{
  "request": {
    "url": "article/?page[limit]=1"
  },
  "response": {
    "statusCode": 200,
    "ruleObjects": [
      {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "user"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "/^[1-9][0-9]*$/"
              },
              "attributes": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "email"
                  },
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  }
                },
                "required": [
                  "email"
                ]
              }
            },
            "required": [
              "id",
              "type",
              "attributes"
            ]
          }
        },
        "required": [
          "data"
        ]
      }
    ]
  }
}

The above JSON Schema ruleObject describes that in order to valid response body must be a JSON object, containing a member with name data which is an JSON object. data object must contain type, id and attribute members attribute object must contain email member of type email and may also contain first_name, last_name members of type string.

Using JSON Schema we can fully describe and restrict the responses.

Learn more about JSON Schema at Understanding JSON Schema

Add a custom footer
Add a custom sidebar

Clone this wiki locally