On this page

Suggestions
Checkpoint Description
Character String Extraction Description
Regular Expression Description
Comparison Operator Description
Response Code Check
Response Header Check
Response Body (JSON) Check
Variables Check
Example: Obtaining a String from the Response Body Based on the Specified key:value
Example: Obtaining Data from the Response Body Based on JSONPath

Show all

Help Center/ CodeArts TestPlan/ User Guide/ Configuring a Test Case/ Creating an Automated API Test Case/ Adding an API Test Script by Using a Custom URL Request/ Setting Checkpoints for an API Script

Setting Checkpoints for an API Script

Updated on 2025-01-10 GMT+08:00

View PDF

Suggestions

You are advised to set checkpoints. For API requests, you need to provide checkpoints for determining response codes.

If the checkpoints are left empty, the result is success regardless of the response code of the API.

Checkpoint Description

A test checkpoint is also called assertion. It determines whether the system meets the expectation based on the API response.

On the Checkpoints tab page of the test step in the test case details of API automation, you can define test checkpoints.

Click to enlarge

Checkpoint parameters include Property, Comparison Operator, and Target Value.

Parameter	Description
Retries	Number of times that the test step is re-executed if the checkpoint fails. The value is an integer ranging from 0 to 5.
Retry Interval	Interval for retrying a checkpoint if the checkpoint fails. The unit is ms. The value is an integer ranging from 0 to 10,000.
Source	Source of the detected field, such as the response body (JSON), response header, response code, and variable.
Property	Enter $ to invoke global variables, local variables, and built-in functions. If the source is a response code, this parameter can be left empty. For details, see Response Code Check. If the source is a response header, the property is the name of the field in the response header. For details, see Response Header Check. If the source is the response body (JSON), the property can be set in either of the following ways: Common extraction expression (not starting with $), for example, item.name. Obtain the value of a field. Nested values are supported. For details, see Response Body (JSON) Check. When an array is extracted from the response body, the index can be a number or a key:value expression. For details, see Example: Obtaining a String from the Response Body Based on the Specified key:value. JSONPath expression (starting with $. or $[), for example, $.store.book[0].title. For details, see Obtaining Data from the Response Body Based on JSONPath. If the source is a variable, the property is a global variable, a local variable, or a variable after response extraction. For details, see Variables Check.
Advanced Extraction Type	(Optional) Use the advanced extraction type to assist in extracting checkpoint information. If N/A is selected, no additional matching mode is used. Currently, there are two modes: Character string extraction (truncation). For details, see Character String Extraction Description. Regular expressions to filter source strings. For details, see Regular Expression Description. For the advanced extraction type, the string extraction function is preferred. If the function cannot meet the requirements, you can use the regular expression.
Type Value	Parameter required in the advanced extraction type.
Comparison Operator	Comparison operator, such as numbers, strings, JSON objects, and types, are supported. For details, see Comparison Operator Description.
Target Value	Expected value of a checkpoint. Built-in parameters can be used for target values. For details, see Built-in Parameters.

For example, the following table describes the parameter settings to check whether the range from the 0th digit (first digit) to the 4th digit of the item.name field in the response body (JSON format) is petty.

Parameter	Value
Source	Response body (JSON)
Property	item.name
Advanced Extraction Type	Character string extraction
Type Value	0–5
Comparison Operator	Equals (string)
Target Value	petty

Character String Extraction Description

When setting checkpoints or response extraction, if the expressions in the property setting bar cannot meet the requirements, you can set Advanced Extraction Type to Character string extraction.

There are two Type Value text boxes for string truncation:

The first box indicates the start index. The first digit is 0. The start index is contained in the truncated string.
The second box indicates the end index. The end index is not contained in the truncated string.

The following response body is used as an example.

To extract the fifth to ninth digits of code in the first element of the result array from the response body and compare them with the target value, configure the checkpoints by referring to the following figure.
To extract the fifth to ninth digits of code in the first element of the result array in the response body and assign the value to the variable code, configure the response extraction by referring to the following figure.

Regular Expression Description

When setting checkpoints or response extraction, if the expressions in the property setting bar or the character string extraction function cannot meet the requirements, you can set Advanced Extraction Type to Regular expression.

The Java regular expression engine can be used.

The following response body is used as an example.

To verify the IP value of remoteUrl in the first element of the result array in the response body, use regular expression for matching and enter the target value in the checkpoint setting area. The following figure shows an example. Set Type Value to ((2[0-4]\d|25[0-5]|[01]?\d\d?)\.){3}(2[0-4]\d|25[0-5]|[01]?\d\d?).
To extract the IP value of remoteUrl in the first element of the result array in the response body, and assign the value to the variable remoteIp, use regular expression for matching and set the response extraction by referring to the following figure. Set Type Value to ((2[0-4]\d|25[0-5]|[01]?\d\d?)\.){3}(2[0-4]\d|25[0-5]|[01]?\d\d?).

Comparison Operator Description

CodeArts TestPlan supports the following comparison types.

Comparison Type	Comparison Operator	Value Mandatory or Not	Example
Digit	== != >= <= > <	Yes	Response code = 200 Response code != 200 Response code >= 200 Response code <= 200 Response code > 200 Response code < 200
String	Equals Does not equal Equals (case insensitive) Contains Does not contain	Yes	Parameter 1 in the response body equals test. Parameter 2 in the response body does not equal test. Parameter 3 in the response body equals TEST. Parameter 4 in the response body contains tri. Parameter 5 in the response body does not contain tri.
Regular expression	Regular expression	Yes	Regular expression for parameter 1 in the response body: ^[A-Za-z0-9]{1,32}$
General	Is empty Is not empty	No	Parameter 1 in the response body is empty. Parameter 2 in the response body is not empty.
JSON array	Has null JSON array Has non-null JSON array	No	Parameter 1 in the response body has a null JSON array. Parameter 2 in the response body has a non-null JSON array.
JSON array	JSON array size	Yes	Size of the parameter 1 JSON array in the response body.
Type	Is JSON type Is JSON array type	No	Parameter 1 in the response body is of the JSON type. Parameter 2 in the response body is of the JSON array type.
JSON object	JSON value	Yes	The JSON value of parameter 1 in the response body is {"name":"zhangsan"}.

Response Code Check

Compare the response code with the target value. For example, check whether the response code is 200.

Click to enlarge

Response Header Check

Compare the value of a field in the response header with the target value. For example, check whether the value of content-type in the response header is equal to text/plain;charset=UTF-8.

Click to enlarge

Response Body (JSON) Check

Check the value of the object field in the response body (JSON). For example:
The response body structure is as follows.

To check the value of the field whose name is status in the response body object, configure the checkpoint by referring to the following figure.
Check the field value of an array object in the response body (JSON). (The array condition uses the subscript starting from 0 to determine the object.) For example:
The response body structure is as follows.

To check the value of userId in the first element object field of the result array in the response body, configure the checkpoint by referring to the following figure.
Check the field value of an array object in the response body (JSON). (The array condition uses the fuzzy match function to determine the object.) For example:
The response body structure is as follows.
1. Check all objects whose name is beer in the result array of the response body. Obtain the values of id after the first object. Configure the checkpoint by referring to the following figure.
  
  NOTE:
  
  If there is only one object in the obtained array, [0] can be omitted. The expression in the example can be written as result[name==beer].id.
2. Check the ID of the object whose name in the result array of the response body is beer, and of which the a property under obj is 2. Configure the checkpoint by referring to the following figure.

Variables Check

Check global variables, local variables, and variable values after response extraction, and compare them with target values. For example:

Check whether the value of the global variable hostIp is 127.0.0.1.
Check whether the value of the local variable local is text.
Check whether the value of the variable name after response extraction is Liquor.

Example: Obtaining a String from the Response Body Based on the Specified key:value

You can enter an array whose subscript is in the key:value format for the Property field of the check body to obtain the JSON string that meets the condition from the response body based on the specified key:value.

The following connectors are supported between key:value.

Connector	Description	Example
==	Equals (string or digit)	name==John age==20
!=	Does not equal (string or digit)	name!=John age!=20
>	Greater than (digit)	age>20
>=	Greater than or equal to (digit)	age>=20
<	Less than (digit)	age<20
<=	Less than or equal to (digit)	age<=20

The array subscript supports multiple groups of key:value conditions connected by &&, indicating that the extracted JSON string must meet all key:value conditions. For example, student[age>20&gender=female] indicates that the extraction conditions are that the age must be greater than 20 and the gender must be female.

The search criteria of an array support nested arrays. In this case, the sub-condition can be met only when all objects in the nested condition meet the conditions.

NOTE:

If the value is an empty object, use $null, that is, key==$null.
If the value is a null string ("null"), use null, that is, key==null.
If the value is an empty string (""), use key==.
If the property value of a checkpoint contains special characters, use single quotation marks or double quotation marks as boundary characters.
For example, name=="zhangsan(ab)".

The following response body (JSON) is used as an example:

{
	"status": "success",
	"result": [
		{
			"name": "Beer",
			"quantity": "20"
			"address": "Shelf 10 in repo A3",
			"obj": {
				"a": 1,
				"b": "test",
				"c": "test"
			},
			"array": [
				{
					"id": 1,
					"name": "aaa"
				},
				{
					"id": 2,
					"name": "bbb"
				}
			]
		},
		{
			"name": "Beer",
			"quantity": "10",
			"address": "Shelf 10 in repo A3",
			"obj": {
				"a": 1,
				"b": "test",
				"c": "test"
			},
			"array": [
				{
					"id": 1,
					"name": "aaa"
				},
				{
					"id": 2,
					"name": "bbb"
				}
			]
		},
		{
			"name": "Liquor",
			"quantity": "20"
			"address": "Shelf 10 in repo A3",
			"obj": {
				"a": 1,
				"b": "test",
				"c": "test"
			},
			"array": [
				{
					"id": 1,
					"name": "aaa"
				},
				{
					"id": 2,
					"name": "bbb"
				}
			]
		},
		{
			"name": "Liquor",
			"quantity": "30"
			"address": "Shelf 10 in repo A3",
			"obj": {
				"a": 1,
				"b": "test",
				"c": "test"
			},
			"array": [
				{
					"id": 3,
					"name": "aaa"
				},
				{
					"id": 4,
					"name": "bbb"
				}
			]
		},
		{
			"name": null,
			"quantity": "10",
			"address": "Shelf 10 in repo A3",
			"obj": {
				"a": 2,
				"b": "test",
				"c": "test"
			},
			"array": [
				{
					"id": 5,
					"name": "aaa"
				},
				{
					"id": 6,
					"name": "bbb"
				}
			]
		},
		{
			"name": "",
			"quantity": "10",
			"address": "Shelf 10 in repo A3",
			"obj": {
				"a": 2,
				"b": "test",
				"c": "test"
			},
			"array": [
				{
					"id": 5,
					"name": "aaa"
				},
				{
					"id": 6,
					"name": "bbb"
				}
			]
		}
	],
	"condition": [
		{
			"name": "Beer",
			"quantity": "120",
			"address": "Shelf 15 in warehouse A1",
		}
	],
	"reason": null
}

The following table lists the expressions for obtaining data from the response body.

Extraction Condition	Expression
Obtain the data whose name is Liquor from the result array.	result[name==Liquor]
Obtain the data whose name is not Beer and quantity is greater than 20 from the result array.	result[name!=Beer&&quantity>20]
Obtain the data whose name is a null object and id is less than or equal to 2 from the result array.	result[name==$null&&array[id<=2]]
Obtain the data whose name is a null string and property a under obj is 2 from the result array.	result[name==null&&obj.a==2]
Obtain the data whose name is an empty string ("") from the result array.	result[name==]

If you need to check whether the data (JSON) whose name is Liquor and quantity is greater than 20 is [{"name": "Liquor", "quantity": "30", " address": "Shelf 10 in warehouse A3", "obj": {"a": 1, "b": "test", "c": " test"}, "array": [{"id": 3, "name": "aaa"}, {"id": 4, " name": "bbb"}]], refer to the following table for the configuration of each field.

Parameter	Value
Source	Response body (JSON)
Property	result[name!=Beer&&quantity>20]
Comparison Operator	Equals (string)
Target Value	[{"name": "Liquor", "quantity": "30"," address": "Shelf 10 in warehouse A3", "obj": {"a": 1, "b": "test", "c": " test"}, "array": [{"id": 3, "name": "aaa"},{"id": 4," name": "bbb"}]]

Example: Obtaining Data from the Response Body Based on JSONPath

For details about JSONPath, visit the official website.

The following response body (JSON) is used as an example:

{
    "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
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            },
            {
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            }
        ],
        "bicycle": {
            "color": "red",
            "price": 19.95
        }
    },
    "expensive": 10
}

The JSONPath expression can contain dots (.) or brackets ([]). For example:

$.store.book[0].title
$['store']['book'][0]['title']

The following table describes the JSONPath expressions and their meanings.

JSONPath Expression	Description
$.store.book[*].author	The authors of all books.
$..author	All authors.
$.store.*	All things, both books and bicycles.
$.store..price	The price of everything.
$..book[2]	The third book.
$..book[-2]	The second to last book.
$..book[0,1]	The first two books.
$..book[:2]	All books from index 0 (inclusive) until index 2 (exclusive).
$..book[1:2]	All books from index 1 (inclusive) until index 2 (exclusive).
$..book[-2:]	Last two books.
$..book[2:]	Book number two from tail.
$..book[?(@.isbn)]	All books with an ISBN number.
$.store.book[?(@.price < 10)]	All books in store cheaper than 10.
$..book[?(@.price <= $['expensive'])]	All books in store that are not "expensive".
$..book[?(@.author =~ /.*REES/i)]	All books matching regex (ignore case).
$..*	Give me everything.

NOTE:

If the length or size function is used, do not use deep scanning (that is, the .. symbol) when calling the function for multiple times. For example, if $..book.length() returns the number of books, you need to determine the path and change it to $.store.book.length().

Parent topic: Adding an API Test Script by Using a Custom URL Request

Previous topic: Adding and Setting the URL Request of an API Script

Next topic: Setting the Response Extraction of an API Script