Assertions allow you to validate HTTP responses in your API tests. For example, a basic assertion would ensure that a request to assertible.com returns a Status code 200 every time -- or that the homepage contains the text Assertible.

Multiple test assertions

Assertions are checked every time a test is run. The result of each assertion, and the reason it passed or failed, can be found on the Test Result page. Assertions are also used to determine a test's state. If any of a tests assertions are failing, the test is in a failing state.

Sections

API test assertions results

Add a new assertion

Assertible offers a selection of assertions that are commonly used to test HTTP services. For example, Assertible has assertions to validate HTML and JSON or check a webpage for broken links.

Each test configuration view has an Assertions tab. From there you can add, update, and delete any assertions for that test:

Fig 1.0 Assertions Tab

Types of assertions

Most assertions can be enabled with a single click. Some assertions offer additional configuration and customization. The available assertions are described below:

Assert status code

Assert the desired HTTP status code of the test's request. The default is 200. This assertions is enabled by default for all new tests and can be configured to any value.

Assert JSON data

Asserting JSON response data allows you to select parts of a JSON response and make assertions on the values. For example, a key id has a value equal to 1. See more examples and information about the syntax below:

Sample JSON
{
  "id": 1,
  "org": {
     "name": "Acme",
     "founded": 2015
  },
  "store": {
    "book": [
      { "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      { "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

Given the sample JSON above, the following table shows the Assertible assertion configuration and result:

Property Comparison Target Result
.id Equals 1

PASS

.id Equals 2

FAIL

.id Not equals 2

PASS

.id Greater than 0

PASS

.id Less than 2

PASS

.id Less than 0

FAIL

.store.bicycle.color Equals red

PASS

.store.book[0].author Equals "Nigel Rees"

PASS

.store.book[1].author Equals "Nigel Rees"

FAIL

.store.book[-1].author Equals "Evelyn Waugh"

PASS

.org.name Equals "Acme"

PASS

.store.book.length() Equals 2

PASS

.org.length() Equals 2

PASS

.org.name.length() Equals 0

FAIL

.length() Greater than 2

PASS

Read more about the JSON Path syntax in the assertions documentation.

Assert JSON validation

Validate JSON response bodies are valid JSON. Optionally, a JSON schema can be specified.

If no JSON schema is supplied, the JSON validation assertion will check that the HTTP response value is valid JSON. A top-level object, array, or scalar value will pass the test. Any un-parseable JSON errors or invalid values will fail the assertion.

JSON schema

The JSON validation assertion also supports an optional JSON Schema Draft 4. When a JSON schema is supplied, the JSON validation assertion will validate the HTTP response data against the schema and report all validation errors.

There are some limitations with this assertion. A few json-schema features are not yet supported:

  • format

    For example, the JSON string "chris" with a validation schema that uses format will ignore the formatting and validate the string:

      {
          "type": "string",
          "format": "email"
      }
  • ECMA-262 regex

    Some parts of ECMA-262 regular expressions are not supported:

    • [^]: a validator with {"type":"string", "pattern": "[^]"} will fail to compile due to being an invalid regex.
  • zero terminated floats

    For example, a validator {"type":"integer"} will work on 1.0 even though there is a trailing slash.

Speak up! Let us know if any of these unsupported features are valuable to your use-case. We are working on improving support for JSON schema but feel free to contact us.

Assert XML/HTML data

Asserting XML response data allows you to select parts of an XML or HTML response using XPath and make assertions on the selected value. For example, a key id has a value equal to 1. The XML data assertions works well with both HTML and XML data sources.

NOTE XPath support in Assertible is currently limited to single node selections. Complex XPath returns types are not yet supported. If you need complex selections, feel free to reach out and let us know!
Sample XML XPath assertions

See more examples and information about the syntax below:

<?xml version="1.0" encoding="UTF-8"?>
<store>
  <id>1</id>
  <org>
    <name>Acme</name>
    <founded>2015</founded>
  </org>
  <bookstore>
    <book category="cooking">
      <title lang="en">Everyday Italian</title>
      <author>Giada De Laurentiis</author>
      <year>2005</year>
      <price>30.00</price>
    </book>
    <book category="children">
      <title lang="en">Harry Potter</title>
      <author>J K. Rowling</author>
      <year>2005</year>
      <price>29.99</price>
    </book>
    <book category="web">
      <title lang="en">XQuery Kick Start</title>
      <author>James McGovern</author>
      <author>Per Bothner</author>
      <author>Kurt Cagle</author>
      <author>James Linn</author>
      <author>Vaidyanathan Nagarajan</author>
      <year>2003</year>
      <price>49.99</price>
    </book>
    <book category="web">
      <title lang="en">Learning XML</title>
      <author>Erik T. Ray</author>
      <year>2003</year>
      <price>39.95</price>
    </book>
  </bookstore>
</store>

NOTE XPath array indexing starts at 1, not 0.

Given the sample XML above, the following table shows the Assertible assertion configuration and result:

Property Comparison Target Result
/store/id Equals 1

PASS

/store/id Equals 2

FAIL

/store/id Not equals 2

PASS

/store/bookstore/book[1] Contains Giada De Laurentiis

PASS

/store/bookstore/book[last()] Contains Learning XML

PASS

/store/bookstore/book[last()-1] Contains XQuery Kick Start

PASS

/store/bookstore/book[@category='cooking'] Contains 2005

PASS

/store/bookstore/book[@category='web'][1] Contains 49.99

PASS

(//store/bookstore/book[@category='web'])[1] Contains 49.99

PASS

/store/bookstore/book[@category='web'] Contains 2005

FAIL

/store/bookstore/book[price>40]/year Equals 2003

PASS

/store/bookstore/book[price>40]/author Equals James Linn

FAIL

Assert response header

Make an assertion against a response header. In the header name field, specify the name of the header to look for. The target value field is dependent on the type of comparator used. For example, when using Contains, the target value only needs to match some part of the header value.

Assert response time

Asserts that the response time of the entire request is less than a specified value, 1 second by default. If the HTTP request takes longer to respond than the target value the test will fail, otherwise it will pass.

Assert text body

This assertions checks for any text in the response body of the request. The default value to check for is DOCTYPE -- you can set the target to any given text and assert the response body contains that string. If no match is found the test will fail and if a match is found it will pass.

Note: the body can be any Content-Type, but will it will be checked as a raw string.

Assert HTML validation

Asserts that the response body contains valid HTML, XHTML, etc markup per the WC3 specification. This is useful finding invalid DOM and HTML errors in your webpages that may prevent it from loading correctly on some clients.

When enabled, this assertion will check all of the links on an HTML page and ensure a request to that target is valid. If any of the links on the page or broken, return a Status Code 404, etc, the assertion will fail.

Currently support html tags:

  • <a>
  • <script>
  • <link>
  • <img>

JSON path syntax in detail

Assertible JSON path syntax allows you to get values out of a JSON response using a simple & familiar syntax. Currently, the syntax allows you to traverse keys and array indexes; advanced syntax like array slicing and wildcard array access is not supported.

If you have a use-case that's not yet supported by this syntax Contact us and let us know!

  • key selection example

      {
        "id": 1,
        "firstName": "Chris",
        "foo": {
          "bar": "baz"
        }
      }
    • selector: .firstName

      result: "Chris"

    • selector: .foo.bar

      result: "baz"

  • key selection w/ dot in name

    { "name.with": 1 }
    • selector: .name\.with

      result: 1

  • key selection w/ space in name

    { "name with": 1 }
    • selector: .name with

      result: 1

  • array index

      [
        {
          "id": 1,
          "firstName": "Chris",
        }
      ]
    • selector: .[0].id

      result: 1

  • array length

      { "users": [1,2,3,4,5] }
    • selector: .users.length()

      result: 5

  • object "length"

      { "steps": {"step1": 1, "step2": 2} }
    • selector: .steps.length()

      result: 2


The JSON path .length() function can only be used at the end of a JSON path expression. For example, .foo[(@.length)] and .foo[(.length())] are not currently supported. .length() can only be used on JSON arrays and objects.

Built-in assertions

In addition to user-defined assertions, Assertible has a set of built-in assertions known as core assertions. These assertions deal with the default behaviors a test run must satisfy. For example:

  • Assertible ensures that an HTTP request connects and executes properly: HTTP Request Success.

  • Assertible ensures that a valid web service environment is loaded.

  • Assertible ensures that SSL connections are properly validated, depending on the execution environment's Validate SSL settings.


The easiest way to test and
monitor your web services

Define and test your web service with Assertible Track and test API deployments across environments Schedule API monitoring and failure alerts

Reduce bugs in web applications by using Assertible to create an automated QA pipeline that helps you catch failures & ship code faster.

Sign up for free