Working with tests in code view

Edit online

With YAML-based test authoring, tests can be defined systematically to validate API behavior under different conditions. Structured test configurations help check API responses, confirm data integrity, and validate business logic.

The following sections outline how to create and run API tests to verify the reliability and correctness of deployed APIs.

Test authoring

Tests are configured by using YAML-based authoring. To create a test, define a YAML file with kind: test. In this file, specify the API methods to be tested, provide input data, define expected responses, and set up assertions to verify API behavior. This structured format supports automation and repeatability, contributing to long-term API quality.

Test authoring considerations

  • Each test file maps to only one API.
  • You can configure multiple test cases for different methods, such as GET and POST, within the same file.
  • You can add multiple assertions for a single response model.
  • You can reference environment variables from another kind or add them directly as variables in the test file.

You can define API test cases using kind: test, specify assertions using kind: assertion, and configure environments using kind: environment.

  • kind: test. Defines test cases for the API.
  • kind: environment. Configures environment variables and request parameters.
  • kind: assertion. Defines conditions to validate API responses.

Templates and samples for each kind

kind: test

To define test cases in API Studio, use the test kind to specify expected API behavior and validate functionality.

Test configuration template

kind: test
metadata:
  name: TestName                # example: TestPayments
  version: Version              # example: 1.0.0
  tags:
    - Tag1                      # example: functional
    - Tag2
  namespace: Namespace          # example: default

spec:
  api:
    $ref: Namespace:APIName:APIVersion  # example: default:PaymentAPI:1.0.1

  environment:
    $ref: Namespace:EnvironmentName:EnvironmentVersion  # example: default:testEnvironment:1.0.0
    variables:
      - key: "VariableKey1"     # example: "name"
        value: "Value1"         # example: "Tom"
        isSecret: true/false    # example: false
      - key: "VariableKey2"     # example: "password"
        value: ${VariableReference} # Reference value (prompts if isSecret is true)
        isSecret: true/false    # example: true

  request:
    - method: HTTPMethod        # example: GET
      resource: ResourcePath    # example: /pet/${petid}
      headers:
        - key: "HeaderKey1"     # example: "Content-Type"
          value: "HeaderValue1" # example: "application/json"
        - key: "HeaderKey2"
          value: ${HeaderVariableReference}  # Reference to the value

      parameters:
        - key: "ParameterKey1"  # example: "petid"
          value: ${ParameterReference}  # Reference to the value

      auth:
        noauth: true/false      # example: true
        basicAuth:
          userName: "Username"  # if using basicAuth
          password: "Password"
        bearerToken: "Token"

      payload:
        json: |
          {
            "Key": "Value",     # example: "name": "Adam"
            "Key2": Boolean     # example: "notify": true
          }
      settings:
        sslVerification: true/false   # example: true
        encodeURL: true/false     # example: true
  assertions:
    $ref: Namespace:AssertionName:AssertionVersion

In the template:

  • Replace placeholder text, such as TestName, Version, Namespace, with specific values relevant to your test.
  • Replace reference configurations such as Namespace:EnvironmentName:EnvironmentVersion, Namespace:AssertionName:AssertionVersion with specific values relevant to your test.
Category Field Description
kind   Defines the type of configuration. In this case, it specifies that this configuration is for test.
metadata.

Identifies and organizes the test with essential tags and identifiers.

 name Names the test, serving as its unique identifier.
version Specifies the version of the test configuration.
tags Labels the test for categorization.
namespace Group the test into a logical category to manage test environments and resources.
spec.

Configures the test case, specifying the API endpoint, environment setup, request parameters, payload types, and assertions.

 api Links the test to the API under examination, pointing to an existing API definition. You can do this by referencing an existing API definition by using the $ref parameter or $endpoint parameter:
  1. Using $ref parameter:

    Use the $ref parameter to point to an API definition in the format:

    $ref: Namespace:APIName:APIVersion

    For example:

    $ref: default:PaymentAPI:1.0.1
  2. Using $endpoint parameter:

    Alternatively, you can provide a direct URL for the API by using the $endpoint parameter in the format:

    $endpoint: endpoint

    For example:

    $endpoint: https://petstore.swagger.io/v2
environment Provides the reference to the environment configuration file. This configuration includes environment-specific variables, such as apiKey, that the test can dynamically use. To reference the environment variables, use the $ref parameter in the following format:

$ref: Namespace:EnvironmentName:​EnvironmentVersion

For example: default:testEnvironment:1.0.0
request Defines the HTTP request details, including:
  • method. The HTTP method to use. For example:GET, POST.
  • resource. The specific API endpoint, which can include dynamic parameters. For example:/pet/${petid}.
  • headers. Defines request headers in a list of key-value pairs.
  • parameters. Defines query, form, or path parameters in a list of key-value pairs.
  • auth. Authentication options, including no-auth, basicAuth, and bearerToken.
  • payload. Specifies different payload types that the test sends. For example: formData, json, and xml. Only one payload type is typically used per request.
  • settings. Defines how API requests are processed in API Studio, including parameters for handling SSL verification and URL encoding:
    • sslVerification. Enables or disables SSL certificate verification for API requests. When set to true, the system verifies SSL certificates to secure the connection, making it ideal for production environments. Setting it to false bypasses this check, which can be helpful in testing or development environments where SSL certificates might be self-signed or not required.
    • encodeURL. Controls whether URLs are automatically encoded before request transmission. When true, URLs are encoded to maintain proper formatting and transmission. When false, URLs are sent as-is.
assertions Validates the API response based on specified criteria. To reference the test assertion, use the $ref parameter in the following format: Namespace:AssertionName:​AssertionVersion

For example: default:testAssertion:1.0.0

A sample configuration for test kind is as follows:

kind: test
metadata:
  name: TestPayments
  version: 1.0.0
  tags:
    - functional
  namespace: default
spec:
  api:
    $ref: default:PaymentAPI:1.0.1
  environment:
   $ref: default:testEnvironment:1.0.0
  request:
    - method: GET
      resource: /pet/${petid}
      headers:
        - key: "Content-Type"
          value: "application/json"
        - key: "X-Gateway-APIKey"
          value: ${apiKey}
      auth:
        noauth: true
      payload:
        json: |
         {
          'name':'Adam',
          'notify': true
         }
      settings:
        sslVerification: false
        encodeURL: true
      assertions:
         $ref: default:testAssertion:1.0.0

In this example:

  • Metadata uniquely identifies the test as TestPayments with version 1.0.0.
  • Request configuration sends a GET request to /pet/${petid} using headers and JSON payload.

kind: environment

To define environment settings for tests, configure the necessary parameters.

Environment variable configuration template

kind: environment
metadata:
  name: Environment_Name # Unique name for the environment configuration
  version: Version # Version of the environment configuration
  tags:
    - Tag1  # Add relevant tags for categorization
    - Tag2
  namespace: Namespace # Logical grouping for managing test resources

spec:
  variables:
    - key: Variable_Key  # Specify the key for the variable
      value: "${Variable_Name}"  # Reference the environment variable
      isSecret: true/false # Indicates if the variable is sensitive

In the template:

Replace Environment_Name, Version, Tag1, Tag2, Namespace, Variable_Key, and Variable_Name with the appropriate values for your specific configuration.

Category Field Description
kind   Defines the type of configuration. In this case, it specifies that this configuration is for an environment.
metadata.

Contains essential identifiers and organizational tags for the environment.

 name Specifies a name for the environment configuration. Use a meaningful name that clearly identifies its purpose.
version Indicates the version of the environment configuration. Update this field whenever you change the environment setup.
tags Lists relevant tags for categorization.
namespace Defines the logical grouping for managing test resources. This field helps organize environments within a specific scope.
spec.

Contains environment-specific settings, such as variables needed during API tests. Each variable can be set as a nonsecret or secret, depending on security needs.

 variables Contains a list of key-value pairs that define the environment variables that are used in your tests.

key. Specifies the key for each variable. Use a clear and descriptive name to identify its purpose. For example: apiKey

value. Specifies the actual value that is associated with the key, which can reference an environment variable. If you do not specify a value, the system prompts you to enter it in real time.

isSecret. Indicates whether the variable is sensitive. Currently, only false is supported, which means the variable value is not encoded and is accessible in its plain form.

A sample configuration for environment kind is as follows:

kind: environment
metadata:
  name: testEnvironment
  version: 1.0.0
  tags:
    - payEnv
  namespace: default
spec:
  variables:
    - key: "petid"
      value: "13"
      isSecret: false
    - key: "apiKey"
      value: '453-0002837546'
      isSecret: false

In this example:

  • Metadata provides an identifier for this environment configuration as testEnvironment, with version 1.0.0.
  • Variables section defines two variables: petid with a value of 13 and apiKey with a value of 453-0002837546. Both variables have isSecret marked as false, meaning that their values are not encoded and are accessible in plain text.

kind: assertion

To define validation criteria for test responses, specify the expected conditions for successful validation.

Assertion configuration template

kind: assertion
metadata:
  name: Assertion_Name          # Unique name for the assertion
  version: Version             # Version of the assertion configuration
  tags:
    - Tag1                     # Relevant tags for categorization 
    - Tag2
  namespace: Namespace         # Logical grouping for managing resources

spec:
  - name: "Assertion_Description" # Assertion description 
    key: Key_Name                # Key for the value being asserted
    value: Expected_Value         # Indicate the expected value for comparison
    action: Comparison_Action     # Define the action for the comparison

In the template:

  • Replace Assertion_Name, Version, Tag1, Tag2, Namespace, Assertion_Description, Key_Name, Expected_Value, and Comparison_Action with relevant values based on your specific assertion needs.
  • Make sure that the action is appropriate for the type of validation you are performing. For example: lessThan, greaterThan, equals, and other actions.
Category Field Description
kind   Specifies the type of configuration, which is assertion in this case, indicating that this file defines validation criteria for test responses.
metadata.

Contains essential identifiers and organizational tags for the assertions.

 name Specifies a name for the assertion. Use a meaningful name that clearly identifies its purpose.
version Indicates the version of the assertion configuration. Update this field whenever you change the assertion setup.
tags Lists relevant tags for categorization.
namespace Defines the logical grouping for managing assertions. This field helps organize assertions within specific projects or environments.
spec.

Configures the specifications for validating test responses.

 Name Specifies the name of the validation. For example: Validate the response code.
Key Identifies the attribute of the response to validate.
Value Sets the target value against which the response attribute must be validated.
Action Defines the validation action or condition. For more information, see Supported assertions and syntax.

A sample configuration for assertion kind is as follows:

kind: assertion
metadata:
  name: testAssertion
  version: '1.0.0'
  namespace: default
  tags:
    - basicAssertions
spec:
  - name: "Validate the response status"
    key: "code"
    value: 200
    action: "equals" 
  - name: "Less Than the response Time"
    key: "responseTime"
    value: 1000
    action: "lessThan"

In this example, the assertion verifies that the response status code is 200 and that the response time for the test is less than 1000 milliseconds.