Tavern

Since version 0.11.0, you can use marks in your Tavern YAML files to interact with Pytest. Marks allow you to:

• Filter tests via CLI: Select specific tests to run using py.test -m "<mark_name>" or exclude them using py.test -m "not <mark_name>".
• Skip tests: Use the skip mark to always skip a test.
• Mark expected failures: Use xfail to mark a test that is expected to fail (e.g., a known bug or a temporary issue).

Marks are applied to the entire test, not to individual stages (except for the skip keyword, which can be applied to stages).

test_name: Get server info from slow endpoint
marks:
  - slow

stages:
  - name: Get info
    request:
      url: "{host}/get-info-slow"
      method: GET

Because curly braces {} are automatically interpreted for string formatting in Tavern, sending literal braces in a string can cause errors or unexpected behavior. To send a string containing literal braces without triggering the formatter, use the !raw tag. This tag effectively escapes the braces (e.g., converting { to {{) so they are treated as plain text.

request:
  json:
    # Sent as {"raw_braces": "{not_escaped}"}
    raw_braces: !raw "{not_escaped}"

You can use YAML anchors to partially reuse a request and then override or extend specific fields using the merge key (<<: *anchor_name). This is useful when a request is mostly identical to another but requires a different URL, method, or expected response.

---
# Define a base request
- &base_request
  url: http://api.example.com/user
  method: GET
  headers:
    Authorization: "Bearer {token}"

# Reuse and extend the base request
- name: Get User Profile
  request:
    <<: *base_request
    url: http://api.example.com/profile  # Overwrites the URL
  response:
    status_code: 200

Tavern uses a plugin system to define how requests are made and how responses are verified. This allows you to override default behaviors (like using requests for HTTP) to test against local servers (e.g., using tavern-flask for Flask or tavern-fastapi for FastAPI) or use different protocols entirely.

Core components of a plugin include:

• Entry Points: Registered via setuptools to tell Tavern which module or class handles specific protocols (e.g., tavern_http or tavern_mqtt).
• Session: A class managing the lifecycle of a connection (e.g., a requests.Session or an MQTT client).
• Request: A class that encapsulates the logic for executing a specific request type.
• Response Verifier: A class that inherits from tavern.response.base.BaseResponse to validate the results of a request.

To avoid duplicating repetitive steps like authentication or common requests, you can use YAML anchors.

In standard YAML, anchors (&name) are only valid within a single document (separated by ---). However, Tavern overrides this default behavior to allow anchors to be preserved and reused across different documents within the same file. This allows you to define a login stage once and reference it in multiple test documents.

---
test_name: Test One
stages:
  - &login_anchor
    name: Login
    request:
      url: http://api.example.com/login
      method: POST
    response:
      status_code: 200

---
test_name: Test Two
stages:
  - *login_anchor  # Reuses the entire login stage
  - name: Next Step
    request:
      url: http://api.example.com/data
      method: GET

Tavern supports testing gRPC services using three distinct approaches for handling protobuf definitions. You can choose the method that best fits your workflow:

1. Pre-compiled: Use a protobuf that has been compiled ahead of time. Tavern imports the generated Python module directly.
2. Runtime compilation: Provide the .proto source file. Tavern compiles it at test time using the source key within a proto block.
3. Server reflection: No local .proto files are required. Tavern discovers the service schema by querying the server's reflection API.

# Example conceptual structure for the three approaches

# 1. Pre-compiled (importing a module)
# (Requires the generated module to be in the python path)

# 2. Runtime compilation
proto:
  source: path/to/helloworld_v2_compiled.proto

# 3. Server reflection
proto:
  reflection: true

Tavern allows you to extend its functionality by implementing custom backends. A custom backend enables you to define new types of request and response handling logic that can be used within Tavern test stages.

In a Tavern test stage, you can specify a custom request type (e.g., touch_file) and a custom response type (e.g., file_exists). The backend plugin maps these names to specific Python logic that executes the action and verifies the outcome.

stages:
  - name: My custom stage
    custom_request_name:
      param: value
    custom_response_name:
      param: value

You can perform complex validations on responses using the $ext key. This allows you to call external Python functions (like tavern.helpers:validate_jwt) and pass them arguments via extra_kwargs. This is useful for verifying things like JWT signatures or complex data structures that standard JSON matching cannot handle.

    response:
      status_code: 200
      json:
        $ext:
          function: tavern.helpers:validate_jwt
          extra_kwargs:
            jwt_key: "token"
            key: CGQgaG7GYvTcpaQZqosLy4
            options:
              verify_signature: true
              verify_aud: false