API endpoint monitors can use assertions to verify the response contents. Without assertions, the monitor only tests whether the endpoint is accessible via HTTP, but does not test the actual data returned by your API. If assertions are defined, the test is only considered successful if all of the assertions pass.
Each monitor step can have any number of assertions. Assertions are made against the response headers or body and can be simple substring checks, regular expression matches, as well as JSON- and XML-specific assertions.
Add assertions
You can add assertions both when you create a new API monitor and edit existing API monitors.
AlertSite UXM
The Assertions table is displayed next to the response. (If the response is not displayed, click Validate Step.)
The easiest way to add assertions is to do this directly from the response body: click a line in a JSON or XML response, or select a keyword or phrase in a text response, then click Add Keyword Assertion. You can also add the assertions manually to the table.
Click the image to enlarge it.
When you add XML assertions, AlertSite suggests possible assertions for the selected element and its attributes, and you can choose which ones to add.
Click the image to enlarge it.
To create an assertion for a response header, switch to the Headers tab, click the header in the list, then click Add Header Assertion. You can verify the header value or just the presence of a specific header in the response.
Click the image to enlarge it.
AlertSite 1.0
You can view and edit assertions in the Assertions table on the monitor configuration screen. Click to add a new assertion and specify the assertion type, source data, and expected value.
Click the image to enlarge it.
Assertion configuration
Each assertion consists of the following elements:
| Column | Description |
|---|---|
| Source |
What is being verified:
|
| Property |
Specifies the JSON or XML field, or the HTTP response header to be verified.
|
| Operator |
The comparison operator. Supported operators depend on the Source. Response - Raw Text:
JSON Response or XML Response:
Timeout:
Status Code:
Header:
|
| Value |
The expected value or the value to compare against. Depending on the assertion configuration, it can be a single value (such as text or number), a list of values, a JSON object or a regular expression. When AlertSite runs the assertion, it calculates the actual value of the specified Source and Property, and compares it to the value specified here. Tips:
|
If you need more advanced checks (for example, verify header values or use scripts), you can convert your monitor to SoapUI and edit the generated SoapUI project.
JSONPath
JSON assertions can use JSONPath expressions to locate fields based on certain conditions or select multiple fields at once. See JSONPath Syntax for more information.
XPath
XML assertions use XPath to access elements in XML responses. AlertSite supports XPath 2.0. To learn more about the XPath syntax, please see this tutorial:
https://www.w3schools.com/xml/xpath_syntax.asp
or the formal specification:
Regular expressions
The regular expression syntax in API assertions is the one used in Java:
https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html#sum
Example
Match a timestamp in the yyyy-mm-ddThh:mm:ss.sssZ format:
\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z
Modifiers
Regular expressions can include modifiers to change the way the pattern matching is handled. The table below lists some common modifiers.
When a modifier appears at the beginning of the pattern, such as (?i)cat.*, it affects the whole pattern. If it appears mid-pattern, it only affects the portion of the pattern that follows.
To specify multiple modifiers, put them together as in (?ims).
| Modifier | Description |
|---|---|
(?i) |
Enables case-insensitive matching. For example, (?i)cat.* matches cat, Cats, CATEGORY, and so on.
By default, only characters from the US-ASCII charset are being matched. To enable Unicode-aware case matching, use |
(?m) |
By default, ^ and $ match the beginning and end of the entire input. The (?m) modifier enables the multiline mode so that ^ and $ match the beginning and end of individual lines. |
(?s) |
By default, . matches any character except for new line characters (\r and \n). If (?s) is used, . also matches new lines. |
(?u) |
When used together with (?i), makes case-insensitive matching Unicode-aware. |
See Also
JSONPath Syntax
Creating an API Endpoint Monitor
API Endpoint Monitor Settings