Send Docs Feedback

Apigee Test is an Apigee Labs feature. It's available free of charge, functions “as is,” and is not supported. There are no service-level agreements (SLAs) for bug fixes. Get help in the Apigee Community.

Test Cases

A Test Case is a container of one or more API calls you want to test. They're executed as a group in the order you specify.

Setting up Test Cases is a lot like setting up a REST client such as Postman to make API calls, but with extra functionality.

You can keep your Test Cases as simple as creating a single API call (Step) to make a GET call and look for an HTTP 200 status code in the response, or as complex as chaining a series of Steps that involve generating an OAuth token, passing it from call to call with GETs, POSTs, and PUTs, and setting multiple HTTP headers. (We show an example of this in Chaining API calls.)

Here's the Test Case home page in Apigee Test:

This topic describes how to fully configure Steps in Test Cases.

You can also create Test Cases with the Create a Test Case API.

How to execute Test Cases

You can execute Test Cases in the following ways:

  • Automatically with Probes. Executing Test Cases from Probes gives you many benefits, including a consistent run frequency, alerts and notifications, calls from multiple geographical locations, and analytics. For more information, see Probes.
  • On demand with webhooks. Apigee Test automatically generates a webhook URL for each Test Case (displayed on the Test Case home page for the selected Test Case or when you execute the Get a Test Case API). Webhooks change when you select a different Config Set (if you're using a Config Set). Execute webhooks with a POST command. No Edge administrator credentials are required for executing a Test Case webhook. Here's cURL example:
    curl -X POST "https://hooks.apigee.com/services/test/testcases/31dcaeae36df42f2dd6225deed3a9261"

Configure the basic API call

On the Step window, click Show Advanced to see all available options. Configure the basic elements of the API call like you would in any other REST client:

  • Enter the URI, including query parameters.
  • Select the HTTP Method.
  • Enter a Request Body for POST and PUT calls.
  • Enter any required HTTP Headers, such as Authorization and Content-Type.

To reference a Config Set variable, such as host in the URL, use this syntax:

${config_set.host} (where your Config Set has a host variable defined)

For example, your URL could be http://${config_set.host}/foo

What determines Step success or failure

When a Step runs, the call either succeeds or fails. But unlike normal API calls, where an HTTP status code of 4xx or 5xx determines success or failure, you get to determine call success or failure in an Apigee Test Step. You can configure call success in a couple of different ways:

  • Asserting by HTTP code - A Step call succeeds in Apigee Test if the HTTP response status code you select in a Step matches the code returned by the API call. For example, if a response returns a 200, and you've selected 200 in the Step, the call succeeds. You could also test to make sure an API call returns a 403 if an unauthorized user tries to access the resource. When you set the HTTP code to 403 on the Step, and a 403 is returned by the API call, the Step succeeds according to Apigee Test.
  • Asserting by the value of an extracted variable - Alternatively, or in addition, you can configure call success based on the value of a variable in the JSON response or response header. For more information, see Asserting API calls with response variables in a Step.
  • Responses are limited to a size of 1MB. If a response is larger than 1MB, the Step fails.

The following figure shows a Step configured to assert based on both HTTP Code and Variables. In order for a call to succeed in Apigee Test, both conditions must be met: an HTTP status code of 200 and a "quantity" variable in the JSON response with a value of 5. If the API call returns a 200 and a quantity ("qty") value of 6, the call fails in Apigee Test.

When a Step fails, the Probe stops executing even if more Steps remain.

The following sections describe additional functionality you can use in Apigee Test steps.

Adding JavaScript to a Step (optional)

Add JavaScript if you want to declare variables that can be used in the Step configuration. For example, you can base64 encode credentials with JavaScript, store the value in a variable, and reference the variable in the Authorization header.

Click Show Advanced on a Step to see the Script field. The JavaScript you enter:

  • Is executed before the API call is made.
  • Is designed to pre-populate variables for use in that Step.
  • Is scoped to that Step only. The variables populated by JavaScript are available only to that API call, not to the other Steps in the Probe.
  • Has a syntax of ${variable_name} - This is how you reference the variable in your Step after you extract it.
  • Can use functions from the btoa and crypto Node.js NPMs.
  • Is limited to 5,000 characters.

Example

In the following example, the script concatenates the username and password (joined by a colon) and base64 encodes the string using the btoa function. The value is stored in a variable called encodedCreds, which is referenced in the call's Authorization header to provide basic auth credentials.

The script also sets a shoppingcartId variable that is used in the call's URI.

Here's a text version of the JavaScript in the example:

var client_id = "h1AXbxAQ9D95JIZ3DNnVYUkZFlHC33uP";
var client_secret = "RAGQHxy1FiQhmVX3";

Extracting response variables in a Step (optional)

By having Apigee Test extract variables from a Step's JSON response or from the HTTP response header, you can reference those variables in any subsequent Step. One of the best uses of variable extraction in Apigee Test is passing an OAuth access token from Step to Step.

Click Show Advanced on a Step to show the Extract Variables field in the Response section. The variables you extract:

  • Must be available in the response as variables or HTTP headers.
  • Are designed to be passed to subsequent API calls.
  • Are scoped to the Probe and are available to all Steps in a Probe after the Step in which they're extracted. For example, if you extract a response variable in your third Step, the value is available to the fourth Step and beyond.
  • Has a syntax of ${variable_name} - This is how you reference the variable in your Step after you extract it.

Example

The following Step calls an Edge OAuth endpoint to generate an access token with client credentials (in the Request Body). The response contains a property called access_token.

In the following sample response, cURL was used to make the API call. In the JSON response payload, the access_token property is highlighted. There are also response headers at the top which could be extracted.

< HTTP/1.1 200 OK
< Content-Type: application/json
< quantity: 5
< Content-Length: 519
< Connection: keep-alive
< 

{
  "issued_at" : "1437583366422",
  "application_name" : "23a89421-9144-497f-a91a-639b1ede625d",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[my_test_product, Premium-Weather-API]",
  "expires_in" : "3599",
  "developer.email" : "inigo@example.com",
  "token_type" : "BearerToken",
  "client_id" : "h1AXbxAQ9D95JIS3TNnVYUkZFlAC93uP",
  "access_token" : "Zi4Q2JSUN8Q8PhOIykebUDDATCqC",
  "organization_name" : "apigeedocs",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
* Connection #0 to host apigeedocs-test.apigee.net left intact
}

In the Response section of the Step, you create a new, arbitrarily named variable called token, and using the JSON Path option you populate that variable with the value of the actual access_token variable. The JSONPath looks like this: $.access_token.

In this and later Steps, you can reference the access token as ${token}. For example, the following shows a later Step referencing the token in the Authorization header with value Bearer ${token}.

For more on OAuth, see OAuth home.

Asserting API calls with response variables or headers in a Step (optional)

Apigee Test says an API call succeeds or fails based on what you configure in a Step's Assert section, as described in What determines Step success or failure. In addition to selecting an HTTP response code that's expected for a successful API call, you can also configure one or more response variables or HTTP headers to indicate call success. For example, if a successful API call means you should get a response variable called quantity with a value of 5, you can configure that in the Assert section.

To use this feature, you must first extract the variable you want to use, as described in Extracting response variables in a Step.

  1. Click Show Advanced on a Step to show the Extract Variables field in the Response section.
  2. First, extract the variable you want to assert as described in the previous section. In the Extract Variables field, configure the variable or header you want to extract (using the JSON Path or Response Header option).
  3. Once you've defined the variable to extract, select the Variables check box in the Assert section, and select either Extracted Variable or Response Header to match the location of the variable you're extracting.
  4. Enter the variable name (the arbitrary name of the variable in the first field of the extracted variable) and value. String values don't require quotes.

Following is an example of extracting a response header (for example, if you used the Assign Message policy to add a quantity header to the response).

  • For the variable name, enter an arbitrary value. This is the Apigee Test variable you're defining to hold the response header value.
  • For the Response Header, enter the name of the header as it appears in the response.
  • In the Assert section, select Extracted Variable and enter the the arbitrary name you entered in the Extract Variables field. That name maps to the actual response header.
  • In this example, for the API call to be a sucess in Apigee Test, the HTTP status code must be 2xx (200, 201, etc.) in addition to the "quantity" response header being 5. If one of those doesn't result, the API call fails.

Guidance for building Steps

Here's some additional guidance for building Steps.

  • Put Steps in the order you want them to be called.
  • Syntax for inserting Config Set variables: ${config_set}. For example, http://${config_set.host}/foo
  • Syntax for using JavaScript or response variables: ${variable_name}
  • Validate as you build Steps. At the bottom of the Test Case, click the Validate button. After validation, you can see details about the request, response, extracted variables, and assertion results.


Chaining API calls

Apigee Test lets you make multiple API calls one after another, letting you simulate a logical flow of calls that might be made by an app. Steps in a Test Case are executed in the order they occur, which covers the first aspect of chaining. But chaining also involves passing data from one call to the next. For example, API calls in a chain may require the same OAuth token for authorization. The passing of data from call to call is accomplished by Apigee Test's ability to extract and store response variables for use in subsequent Steps, as described in Extracting response variables.

This section shows an example of API chaining using configuration details described earlier in this topic. Use the example to learn what's possible with Apigee Test. In the example, the first Step generates an OAuth access token, and the next Steps create a developer, update the developer, get the developer, and finally delete the developer.

1: Generate OAuth access token

This Step calls an OAuth endpoint on Apigee Edge to generate an access token from a developer app's client key and client secret. The resulting access_token variable in the response, which contains the value of the access token, is saved by Apigee Test and is available for all subsequent Steps to use.

2: Create developer

This Step uses the OAuth access token in the Authorization header, referencing the access_token variable set in Step 1.

3: Update developer

The developer's first name is modified. The Step uses the OAuth access token in the Authorization header, referencing the access_token variable set in Step 1. The JavaScript in the Script field is executed before the call, which stores the developer's username in a developerId variable. The variable is referenced in the URI.

4: Get developer

This Step uses the OAuth access token in the Authorization header, referencing the access_token variable set in Step 1. The JavaScript in the Script field is executed before the call, which stores the developer's username in a developerId variable. The variable is referenced in the URI. Because JavaScript is scoped to the Step in which it executes, any JavaScript you want to use must be added to each call.

5: Delete developer

This Step uses the OAuth access token in the Authorization header, referencing the access_token variable set in Step 1. The JavaScript in the Script field is executed before the call, which stores the developer's username in a developerId variable. The variable is referenced in the URI. Because JavaScript is scoped to only its own Step, any JavaScript you want to use must be added to each call.

 

Help or comments?