Skip to main content
Version: 23.3

Running API Tests

You can run and edit API tests in the API Test Editor in Eggplant Functional. You also can call API tests from several other places, including from SenseTalk scripts, from schedules, and from the command line.

Run API Tests from a SenseTalk Script​

Calling an API test from a SenseTalk script works just like calling one SenseTalk script from another SenseTalk script.

This script calls an API Test named ApiTest1 and returns its URL, response header, and response body.

Example​

put ApiTest1() into foo
put foo.url
put foo.responseHeaders
put foo.responseBody

The API Function​

Use the api() Function to access all the properties of an API test, including both the request and response. Note that this function always returns the properties from the API test that ran most recently, so you might want to save properties from individual tests as a variable if you want to use them at a later time. This example runs an API test called ApiTest1 and uses the api function to store the response time in a variable called TimeVar.

Example​

ApiTest1
put api().responseTime into TimeVar

The api() function returns a property list from the most recent API test that includes the following values:

  • authenticationType: Returns the authentication type used for the request.
  • httpMethod: Returns the request type (e.g., GET, POST).
  • mimeType: Returns the MIME type used in the response.
  • oauth1Token: Returns the token if OAuth 1.0 is the authentication method; otherwise, empty.
  • password: Returns a redacted string if a password is used for authentication; otherwise, empty.
  • requestBody: Returns the body content of the request for POST, PUT, and PATCH requests; otherwise, empty.
  • requestBodyFormat: Returns the Body Format type selected in the Request Body section. For requests that don't have body content, the returned value is the most recently chosen Body Format type.
  • requestHeaders: Returns any headers entered in the Request Headers section as key/value pairs; otherwise, empty.
  • responseBody: Returns the response data from the server.
  • responseCookies: Returns details about cookies in the response, if any.
  • responseHeaders: Returns the response headers as key/value pairs.
  • responseTime: Returns the response time from the request from the server, in seconds.
  • statusCode: Returns the status code received from the server (e.g., 200, 404).
  • url: Returns the request URL.
  • userName: Returns the username for authentication (if used); otherwise, empty.

Override API Test Properties​

You can override any of the properties of an API test using SenseTalk. To see a list of these properties, first run an API test. Then run put api().keys.archive. This function returns a list of the properties (keys) that can be set, not their values as entered in the referenced API test.

To override these properties, provide them as a dictionary in a function call. This example overwrites the URL and username used in an API test called myApiTest.

Example​

myApiTest(url: "http://www.google.com", username: "documentation")

Chain API Tests​

You can chain API tests together in SenseTalk scripts in the Script Editor. This enables you to use the results of those API tests in larger tests using SenseTalk. The following example uses the results from two API tests, Get_BasicAuth_json and Head_BasicAuth_json, as part of a larger test of an error tracking system.

Example​

log "-------------------------------------------------------------------------------------"
log " Feature #XXXX"
log " Support for Basic Authentication"
log "--------------------------------------------------------------------------------------"

BeginTestCase "Basic Authentication - Valid Authentication - Get Request"
Get_BasicAuth_json
EndTestCase "Basic Authentication - Valid Authentication - Get Request"
BeginTestCase "Basic Authentication - Valid Authentication - Head Request"
Head_BasicAuth_json
EndTestCase "Basic Authentication - Valid Authentication - Head Request"
BeginTestCase "Basic Authentication - Invalid Authentication"
set the suiteVariables.username to "xxxxx"
Get_BasicAuth_json
EndTestCase "Basic Authentication - Invalid Authentication"

Run API Tests from the Command Line​

Use the runscript command to run API tests from the command line. Use the -CommandLineOutput flag to output script logs.

Examples​

Mac (bash shell)​

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Bob/Documents/APITesting.suite/APITests/ApiTest2.apitest -CommandLineOutput yes

Windows (command shell)​

"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Bob\Documents\APITesting.suite\APITests\ApiTest1.apitest" -CommandLineOutput yes

Linux (bash shell)​

runscript ~/Documents/APITesting.suite/APITests/Untitled.apitest -CommandLineOutput yes

You can override any parameters you've set in the API test from the command line, as well.

Examples​

Mac (bash shell)​

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Bob/Documents/APITesting.suite/APITests/ApiTest2.apitest -pv '(url:"http://chicago.publicserver.com/issues/14618.xml")' -CommandLineOutput Yes

Windows (command shell)​

"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Bob\Documents\AutoDoctorScreenshots.suite\APITests\JsonGet.apitest" -pv (url:\"http://chicago.publicserver.com/issues/14920.xml\") -CommandLineOutput Yes

Linux (bash shell)​

runscript ~/Documents/APITesting.suite/APITests/Untitled.apitest -pv '(url:"http://chicago.publicserver.com/issues/14920.xml")' -CommandLineOutput yes

Run API Tests from a Schedule​

Use schedules to define a collection of API tests and scripts to run, the order to run them in, and any parameters or dependencies. Access schedules from the Schedules pane.

Click the arrow to the right of the Status column to view detailed results of the selected test or script run. Note that you don't need to connect to a system under test (SUT) to run a schedule of API tests.

Password Storage and Encryption for API Tests​

Passwords you enter in the Authentication fields of the API Test Editor must be in plain text. Eggplant Functional encodes these passwords when you save and decodes them when you load an API test.

You should encode any passwords you choose to save as suite variables, as it's not recommended to save passwords as plain text. Those passwords must then be decoded before they're passed to API tests. Note that you need to use this method only if you're using a form of authentication that's not directly supported in Eggplant Functional.

You can both encode and decode passwords using Eggplant Functional.

Step by Step: Encode Passwords​

  1. Open the Run window. In the Ad Hoc Do Box, enter the following code, then click Do:

    log encodeText("my password")

  2. Copy the encoded password from the Log pane.

  3. Open the Settings tab and paste the encoded password into a Value field in the Suite Variables section. Enter a name for the password variable in the corresponding Key field.

  4. To override the password property in an API test using a suite variable, use the decodeText function in an API script or a SenseTalk script:

    put decodetext(MyPwd) into myPassword
    ApiTest1(password: myPassword)
Last updated on