{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1837,"path":"application-development/automated-test-framework-atf/test-steps-rest-category.md","title":"REST category","bundle":null,"doc_type":null,"release":"australia","body":"\n# REST category\n\nVerify the functionality of REST calls.\n\n## Send REST Request - Inbound - REST API Explorer\n\nThis test step begins with the REST API Explorer. Use the REST API Explorer to create and specify the HTTP method, path, query parameters, request headers, and body of a REST request, and then send the REST request to the current instance.\n\nWhen you have tested the request, the **Create Automated Test Step** button appears. Click **Create Automated Test Step** to create the test step. This button does not appear until after the request has been sent. You cannot create a test step when the request payload is larger than the maximum request payload size property.\n\nThis test step creates the same test record as the **Send REST Request - Inbound** test step. After the test step is created, you cannot go back and use the REST API Explorer to update the test. All changes must be made on the **Send REST Request - Inbound** test step form.\n\nNo HTTP response validation is performed as part of this step. The step fails if the response payload size is too big, the request parameters are invalid, or the request could not be sent. Use the assert steps to validate the response.\n\nYou cannot use this step to send a request to another instance or third party/remote address.\n\nThese inputs are for the REST API Explorer. The fields you see depend upon the API selected. For more information on using REST APIs on your instance, see [REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/c_RESTAPI.md).\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nNamespace\n\n\n\nNamespace for the request. Select from the list.\n\n
\n\nAPI Name\n\n\n\nAPI to be used. Select from the list.\n\n
\n\nAPI Version\n\n\n\nAPI version to be used. Select the version available on your instance from the list.\n\n
\n\nPath parameters\n\n\n\nThe part of the path after the API name. Path parameters are generally name-value pairs where the allowable values are in a list.\n\n
\n\nQuery parameters\n\n\n\nName-value pairs of query parameters added to the URI after the path. The REST API Explorer encodes the URI, so it is not necessary to encode query parameters and values.\n\n
\n\nRequest headers\n\n\n\nName-value pairs contained in the request header. The authentication header is set to **Send as me** to use the current user's credentials. To use the test step in production, you may need to change the **Authentication Type** field in the **Send REST - Inbound** test step. Do not encode the name or value.\n\n
\n\nRequest Body\n\n\n\nThe request content. Some requests do not have a body.\n\n
## Send REST Request - Inbound\n\nCreate a test step to send a REST request to the current instance. Specify the HTTP method, path, query parameters, request headers, and body of a REST request.\n\nNo HTTP response validation is performed as part of this step. The step fails if the response payload size is too big, the request parameters are invalid, or the request could not be sent. Use the assert steps to validate the response.\n\nYou cannot use this step to send a request to another instance or third party/remote address.\n\nFor more information on using REST APIs, see the [REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/c_RESTAPI.md).\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nAuthentication Type\n\n\n\nThe type of authentication to use. For public APIs, select **None**.\n\n To configure basic or mutual authentication, users need the atf\\_ws\\_designer role. For more information, see [Automated Test Framework roles](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/automated-test-framework-atf/atf-roles.md).\n\n
\n\nBasic authentication\n\n\n\nThe basic authentication profile to use when doing the test. You must create or select a basic authentication profile to assign to test steps to avoid authentication issues when running the test. For more information, see [Create a basic auth profile using the Automated Test Framework](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/automated-test-framework-atf/atf-create-basic-auth-profile.md).\n\n
\n\nMutual authentication\n\n\n\nAn X.509 certificate for mutual authentication. You must create or select a client certificate to assign to test steps to avoid authentication issues when running the test. For more information, see [Set up Certificate-based authentication](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/set-up-mutual-auth.md).\n\n
\n\nMethod\n\n\n\nThe HTTP method to be used:- **GET**\n- **POST**\n- **PUT**\n- **DELETE**\n- **PATCH**\n\n
\n\nPath\n\n\n\nThe path to be used. This field accepts only the portion of the URI after the instance name. If you use `https://`, you get an error.\n\n
\n\nQuery Parameters\n\n\n\nQuery parameter names and values. Do not encode the parameter names or values.\n\n
\n\nHeaders\n\n\n\nHeader names and values. Do not encode the header names or values.\n\n
\n\nBody\n\n\n\nThe body of the request.\n\n
## Assert Status Code\n\nAssert that the HTTP response status code has the specified relationship to the specified value. You specify a numeric value of the status code and the relationship.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nOperation\n\n\n\nComparison to be performed between values:- **is**\n- **is not**\n- **less than**\n- **greater than**\n- **less than or is**\n- **greater than or is**\n\n
\n\nStatus code\n\n\n\nStatus code to be tested against the response code.\n\n
## Assert Status Code Name\n\nAssert that the HTTP response status code name has the specified relationship to the specified value. You specify a value of the status code name, and the relationship.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nOperation\n\n\n\nComparison to be performed between values:- **contains**\n- **does not contain**\n- **is**\n- **is not**\n\n
\n\nStatus code name\n\n\n\nStatus code name to be tested.\n\n
## Assert Response Time\n\nAssert that the HTTP response time has the specified relationship to the specified value. You specify a value of the response time and the relationship.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nOperation\n\n\n\nComparison to be performed between **Response time** entered and actual response time:- **less than**\n- **greater than**\n\n
\n\nResponse time \\(ms\\)\n\n\n\nTime in milliseconds to be compared to the actual response time.\n\n
## Assert Response Header\n\nAssert the HTTP response header exists, or the header has the specified relationship to the specified value.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nHeader\n\n\n\nHeader name.\n\n
\n\nOperation\n\n\n\nComparison to be performed between values:- **contains**\n- **does not contain**\n- **is**\n- **is not**\n- **is not empty**\n\n
\n\nValue\n\n\n\nElement value to be used in the test. Not shown if the **Operation** is **is not empty**.\n\n
## Assert Response JSON Payload is Valid\n\nAssert that the response payload is in valid JSON format.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
## Assert Response XML Payload is Well-Formed\n\nAssert that the response payload is well-formed XML.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
## Assert XML Payload Element\n\nAssert the XML response payload element exists, or has the specified relationship to the specified value.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nElement path\n\n\n\nXML path to the element to be evaluated. For example, `/result/short_description` for```\n{\n \"result\": {\n \"number\": \"INC0020001\",\n \"short_description\": \"test\"\n }\n}\n```\n\n
\n\nOperation\n\n\n\nComparison to be performed between values:- **contains**\n- **does not contain**\n- **is**\n- **is not**\n- **is not empty**\n\n
\n\nValue\n\n\n\nElement value to be used in the test. Not shown if the **Operation** is **is not empty**.\n\n
## Assert JSON Response Payload Element\n\nAssert the JSON response payload element exists, or has the specified relationship to the specified value.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nElement path\n\n\n\nSNC path to the element to be evaluated. For example, `/result/short_description` for```\n{\n \"result\": {\n \"number\": \"INC0020001\",\n \"short_description\": \"test\"\n }\n}\n```\n\n See [Importing JSON files](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/json-data-source-examples.md) for more information.\n\n
\n\nOperation\n\n\n\nComparison to be performed between values:- **contains**\n- **does not contain**\n- **is**\n- **is not**\n- **is not empty**\n\n
\n\nValue\n\n\n\nElement value to be used in the test. Not shown if the **Operation** is **is not empty**.\n\n
## Assert Response Payload\n\nAssert the HTTP response payload has the specified relationship to the specified value. You specify the value and the relationship.\n\nAssert steps must immediately follow a **Send REST Request - Inbound** step. You can have multiple REST assert steps following a **Send REST Request - Inbound** step, but the assert steps cannot be separated from the **Send REST Request - Inbound** step by steps from other test categories.\n\n**Note:** The entire payload is used to look for a match. A large payload can affect performance.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nExecution order\n\n\n\nInteger specifying the order in which the test executes this step.As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the **Execution order** values.\n\n
\n\nActive\n\n\n\nOption to activate this test step for use.\n\n
\n\nApplication\n\n\n\nApplication scope in which the system runs this step.\n\n
\n\nTest\n\n\n\nRead-only name of the test that you're adding the step to.\n\n
\n\nStep config\n\n\n\nRead-only name of the step.\n\n
\n\nDescription\n\n\n\nDescription of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.\n\n
\n\nNotes\n\n\n\nNotes about the test step.\n\n
\n\nOperation\n\n\n\nComparison to be performed between values:- **contains**\n- **does not contain**\n- **is**\n- **is not**\n- **is not empty**\n\n
\n\nResponse body\n\n\n\nThe value of the response body to be used in the test.Must contain the name and value to be compared as it appears in the response payload. Must not contain any curly braces.\n\n Not shown if the **Operation** is **is not empty**.\n\n
To check the short description in the response payload\n\n```\n{\"result\":{\"number\":\"INC0010040\",\"short_description\":\"Test ATF Incident\"}}\n```\n\nthe **Response body** should contain\n\n```\n\"short_description\":\"Test ATF Incident\"\n```\n\nThese formats are incorrect and the step fails.\n\n- `{\"short_description\":\"Test ATF Incident\"}`\n- `\"{\"short_description\":\"Test ATF Incident\"}\"`\n- `short_description: Test ATF Incident`\n- `short_description:\"Test ATF Incident\"`\n\n"}}