Web API steps introduced in Cycle 2.5 can be used to send HTTP requests to exposed web API endpoints. The Cycle Web API steps support POST and GET request methods using the JSON data format. Cycle also includes steps for handling HTTP responses received from the requests.
Cycle includes a step to define a base URL for the web API endpoints.
Defining a base URL will allow you to use relative paths to reference endpoints when executing POST and GET steps within your feature.
If no base URL is defined, any POST and GET steps will need to use an absolute path to define the endpoint for the step.
And I set "https://myserver.cyclelabs.io/ws" as my http base url (This URL is for your reference and not an active API endpoint. Do not use cyclelabs.io for your API testing)
The step above will set the base URL to be used by any subsequent Web API POST and GET steps in your feature. If you have set a base URL, you can specify endpoints in the POST and GET steps using relative paths.
Cycle will construct the HTTP request URL by combining the base URL with the relative path of the endpoint.
For example, if the endpoint you want to send a request to is "https://myserver.cyclelabs.io/ws/auth/login" and you defined the base URL as shown in the example step, then you can reference the endpoint as "/auth/login" in your Web API steps.
The Web API POST and GET steps support passing headers in the HTTP request.
The Web API GET steps also support passing parameters in the HTTP request.
In order to include request headers or parameters in the HTTP request, you will first need to assign values to corresponding Cycle variables.
The Cycle variable names must match the header and parameter fields in the HTTP request in order for Cycle to properly generate the request.
For example, you may want to make an HTTP GET request with a parameter list that includes the parameters policyCode, policyValue, and policyVariable.
You will need to assign values to Cycle variables named policyCode, policyValue, and policyVariable before executing the Web API step using the parameters.
Example parameter assignment:
And I assign "PICK-RELEASE" to variable "policyCode"
And I assign "INSTALLED" to variable "policyValue"
And I assign "INSTALLED" to variable "policyVariable"
Cycle will generate the HTTP request based on the list of headers or parameters in your step and the values assigned to the items in the list. Cycle will display an error if you attempt to use any headers or parameters that have not been assigned a value.
There are two Web API steps for POST method requests in Cycle.
I http POST JSON to "<ENDPOINT>" "<JSON>"
I http POST JSON to "<ENDPOINT>" "<JSON>" with headers "<HEADER_NAMES>"
The POST method steps require an exposed web API endpoint and a JSON string to post to the endpoint.
The JSON string can either be typed in line as part of the step or referenced via variable to make the step easier to read.
You can optionally pass header fields as part of the HTTP request. The list of header names is comma separated with no spaces.
Each header needs to correspond to an already assigned Cycle variable. Cycle will display an error if you attempt to use any headers that have not been assigned a value.
There are four Web API steps for HTTP GET method requests included in Cycle.
I http GET JSON from "<ENDPOINT>"
I http GET JSON from "<ENDPOINT>" with parameters "<PARAMETER_NAMES>"
I http GET JSON from "<ENDPOINT>" with headers "<HEADER_NAMES>"
I http GET JSON from "<ENDPOINT>" with parameters "<PARAMETER_NAMES>" and headers "<HEADER_NAMES>"
The GET method steps require an exposed web API endpoint.
You can optionally pass parameters, headers, or both parameters and headers to the endpoint using the appropriate steps.
The list of header names and parameter names are comma separated with no spaces.
Each header and parameter needs to correspond to already assigned Cycle variables. Cycle will display an error if you attempt to use any headers or parameters that have not been assigned a value.
There are four Web API steps to handle HTTP responses in Cycle.
I assign http response status code to variable "<VARIABLE_NAME>"
I assign http response header "<HEADER_NAME>" to variable "<VARIABLE_NAME>"
I assign http response headers to variables
I assign http response body to variable "<VARIABLE_NAME>"
The steps can be used to:
Cycle includes a step that can be used to assign a specific value from a JSON element to a variable. This step is especially useful to extract data from an JSON HTTP response body.
I assign value from JSON "<JSON>" with path "<LOCATOR_PATH>" to variable "<VARIABLE_NAME>"
JSON locator paths in Cycle are similar to xPath. You can identify specific elements within the JSON by specifying the path to the element.
Example JSON (sample_JSON):
{ "customer": [
{ "id": "1234",
"name": "Standard Supply Inc."
},
{ "id": "5678",
"name": "Global Industries"
}
]
}
Example step:
And I assign value from JSON $sample_JSON with path "/customer[0]/name"
The step above would assign the value of the first "name" element in the customer array ("Standard Supply Inc.").
Example step:
And I assign value from JSON $sample_JSON with path "/customer[1]/id"
The step above would assign the value of the second "id" element in the customer array ("5678").
A useful online tool for identifying JSON locator paths can be found here.
The following sample feature uses the Web API steps discussed above to complete a simple task of retrieving data using a web service.
First, Cycle sends an HTTP POST request with a JSON body containing authentication credentials to a login endpoint.
If the request returns a 200 response status code (OK), then Cycle saves the authentication cookie sent in the HTTP response to a variable.
Next, Cycle sends an HTTP GET request to an endpoint that returns policy data. The HTTP GET request includes a list of policy parameters which match previously assigned variables. The GET request also passes the previously assigned authentication cookie in the header of the request.
Finally, the JSON response body is assigned to a Cycle variable. Then a value is retrieved from the JSON response and echoed to the output.
Feature: Web API Test
Background: Web API Test
# Set an http base url so we can use relative paths in our POST and GET steps
Given I set "https://myserver.cyclelabs.io/ws" as my http base url
And I assign "cycle_user" to variable "webservice_username"
And I assign "cycle_password" to variable "webservice_password"
Scenario: Web API Test
# Assign a JSON string to a variable, we will pass this JSON string with the HTTP POST request
Given I assign variable "auth_string" by combining """{"usr_id":"""" $webservice_username """","password":"""" $webservice_password """"}"""
# Execute HTTP POST request to the login endpoint using relative path and passing the JSON string
Then I http POST JSON to "/auth/login" $auth_string
# Verify the HTTP response is OK, and assign the response header Set-Cookie value to a variable named Cookie
If I verify http response had status code 200
Then I assign http response header "Set-Cookie" to variable "Cookie"
Else I fail step with error message "Unable to authenticate to WMS"
EndIf
If I verify variable "Cookie" is assigned
# Assign the parameters for the GET request to variables
Given I assign "PICK-RELEASE" to variable "policyCode"
And I assign "INSTALLED" to variable "policyValue"
And I assign "INSTALLED" to variable "policyVariable"
# Execute the HTTP GET request to the policies endpoint, using a parameter list and the authentication Cookie we received in the login request header response
Then I http GET JSON from "/mcs/policies" with parameters "policyCode,policyValue,policyVariable" and headers "Cookie"
# Assign the JSON response body to a variable, assign a value from the response to a variable, and echo the value
Given I assign http response body to variable "policy_response"
Then I assign value from JSON $policy_response with path "/data[0]/returnNum1" to variable "returnNum1"
And I echo $returnNum1
EndIf