seekret.apitest 0.3.0.dev0

Seekret's library for API testing runtime

Seekret API testing runtime

The seekret.apitest package contains runtime functions and tools intended to ease API testing.

The seekret.apitest package is not used directly, but is referenced within tavern tests generated by Seekret.

Quickstart

First, install tavern and seekret.apitest: pip install tavern seekret.apitest

Now, in order to run a test:

1. Store one or more generated tavern tests from the Seekret website in a directory.
2. Copy the configuration file you received from Seekret to the same directory.

Your test directory should look like this:

/testdir
|-- test_1.tavern.yaml
|-- test_2.tavern.yaml
|-- ...
|-- config.yaml

After your test directory is set up, run pytest --tavern-global-cfg config.yaml.

Tavern will collect all test_*.tavern.yaml files and run the described tests.

Understanding the configuration and generated tests

Tavern tests generated by Seekret use common variables which are expected to be set using an external configuration. This currently includes the host of the target servers and the authorization settings.

Example generated test file:

# test_1.tavern.yaml

stages:
  - name: POST /user
    request:
      headers:
        $ext:
          function: seekret.apitest:add_auth_in_headers
          # This section defines that the headers are extended with
          # the result of the `add_auth_in_headers` function.
          # The `add_auth_in_headers` function uses Seekret-format
          # authorization settings defined in the configuration file
          # in the "user" variable.
          extra_args:
            - !force_format_include "{seekret-runtime.v1}"
      json:
        # Randomized body values, created during test generation.
        email: [e-mail]
        name: vrdyin
        photo: https://hernandez.biz/
      method: POST
      url: '{host}/user' # The "host" variable from the configuration file.
    response:
      save:
        json:
          # Later tests can use the `userId` value from this response
          # by specifying this variable name.
          saved_0_responseBody_userId: userId
      status_code:
        - 200

Example configuration file:

name: Global test configuration
description: |
  Global configuration for running the tavern tests.

variables:
  seekret:
    v1:
      target_server: http://example.com
      users:
        user:
          auth:
            type: bearer
            data:
              token: <Preconfigured API token for the test user>

Adding authentication using a custom request

To extend the authentication capabilities, Seekret allows adding an authentication stage to the test in the configuration file.

Here's an example of a configuration file that uses custom request authentication:

# ...
variables:
  seekret:
    v1:
      # ...
      users:
        user:
          auth:
            type: custom-request
            data:
              auth_stage_id: my-custom-auth-stage # Optional, defaults to "auth"

stages:
  - id: my-custom-auth-stage
    name: My custom auth stage
    request:
    # ...
    response:
      save:
        $ext:
          function: seekret.apitest:save_authorization
          extra_kwargs:
            # This will take the X-Auth-Token header from the response and put it in the header
            # of future test stages.
            headers: '"X-Auth-Token"' # This is a JMESPath expression, thus the quoting.
            type: header
            data:
              target_header: X-Auth-Token

Before running a tavern test, the Seekret library will prepend the custom authentication stage to the test, so it executes prior to the test stages defined in the test file.

The stage is in your full control, but you must save the authorization values using the seekret.apitest:save_authorization extension function.

seekret.apitest:save_authorization

save_authorization is a tavern extension function, intended to use in authentication requests. The function saves the authorization tokens so that later stages can use the authorization values.

You can use the following "kwargs" to specify the wanted behaviour:

Argument Name	Description
type	Type of authorization method (currently supported: header, bearer).
data	Additional data for the authorization method. See the next table for expected values.
headers	JMESPath to the response header to take the authorization token from. Can't be used with json.
json	JMESPath to the authorization token in the JSON content of the response. Can't be used with headers.

type value	data fields
header	target_header - the name of the header to set to the authorization token
bearer	Not applicable for bearer authorization

Example: Login with credentials and get bearer token

This example describes the authorization stage of a login requests that generates a bearer token.

variables:
  seekret:
    v1:
      target_server: http://example.com
      users:
        user:
          auth:
            type: custom-request
            data:
              auth_stage_id: login
              username: Seekret
              password: isAwesome!

stages:
  - id: login
    name: Login
    request:
      method: POST
      url: /login
      json:
        username: '{seekret.v1.users.auth.data.username}'
        password: '{seekret.v1.users.auth.data.password}'
    response:
      status_code:
        - 201
      save:
        $ext:
          function: seekret.apitest:save_authorization
          extra_kwargs:
            json: data.token
            type: bearer