Metadata-Version: 2.1
Name: seekret.apitest
Version: 0.3.0.dev0
Summary: Seekret's library for API testing runtime
Home-page: https://github.com/seek-ret/tests-rtl
Author: Seekret Software Ltd.
Author-email: info@seekret.com
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/seek-ret/tests-rtl/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: requests (<3,>=2)
Requires-Dist: PyYAML (<6,>=5)
Requires-Dist: jmespath
Requires-Dist: pytest (<7,>=6)
Requires-Dist: pykwalify (~=1.8)

# 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](https://app.seekret.com) in a directory.
2. Copy the configuration file you received from Seekret to the same directory.

Your test directory should look like this:

```text
/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:

```yaml
# 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: jenkinsjennifer@king.com
        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:

```yaml
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:

```yaml
# ...
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.

```yaml
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
```

