tessl/pypi-tavern

Simple testing of RESTful APIs

Overview

Eval results

Files

Core Test Execution

Name: tessl/pypi-tavern
Author: tessl

Primary interface for running Tavern tests programmatically, providing comprehensive control over test execution, configuration, and backend selection.

Capabilities

Programmatic Test Runner

The main entry point for executing Tavern tests from Python code, offering full control over test configuration and execution parameters.

def run(
    in_file: str,
    tavern_global_cfg: Union[dict, str, None] = None,
    tavern_mqtt_backend: Union[str, None] = None,
    tavern_http_backend: Union[str, None] = None,
    tavern_grpc_backend: Union[str, None] = None,
    tavern_strict: Union[bool, None] = None,
    pytest_args: Union[list, None] = None,
) -> Union[ExitCode, int]:
    """
    Run all tests contained in a file using pytest.main()

    Parameters:
    - in_file: Path to the test file to run
    - tavern_global_cfg: Global configuration as dict or path to config file
    - tavern_mqtt_backend: MQTT plugin backend name (default: "paho-mqtt")
    - tavern_http_backend: HTTP plugin backend name (default: "requests")
    - tavern_grpc_backend: gRPC plugin backend name (default: "grpc")
    - tavern_strict: Strictness level for response validation
    - pytest_args: Additional arguments to pass to pytest

    Returns:
    ExitCode or int: 0 if all tests passed, non-zero otherwise
    """

Usage Examples:

from tavern.core import run

# Basic usage
exit_code = run("tests/api_tests.tavern.yaml")

# With global configuration file
exit_code = run(
    "tests/api_tests.tavern.yaml",
    tavern_global_cfg="config/global.yaml"
)

# With global configuration as dictionary
global_config = {
    "variables": {
        "base_url": "https://api.staging.example.com",
        "api_key": "test-key-123"
    }
}
exit_code = run(
    "tests/api_tests.tavern.yaml",
    tavern_global_cfg=global_config
)

# With custom backends and strict validation
exit_code = run(
    "tests/api_tests.tavern.yaml",
    tavern_http_backend="requests",
    tavern_strict=True,
    pytest_args=["-v", "--tb=short"]
)

# Check test results
if exit_code == 0:
    print("All tests passed successfully!")
else:
    print(f"Tests failed with exit code: {exit_code}")

Global Configuration Processing

Internal function for processing global configuration from various sources.

def _get_or_wrap_global_cfg(
    stack: ExitStack, 
    tavern_global_cfg: Union[dict, str]
) -> str:
    """
    Parse global configuration from file path or dictionary.

    Parameters:
    - stack: Context stack for temporary file management
    - tavern_global_cfg: Configuration as file path or dictionary

    Returns:
    str: Path to configuration file

    Raises:
    InvalidSettingsError: If configuration format is invalid or file doesn't exist
    """

Configuration Examples

Global Configuration File Format

# global_config.yaml
variables:
  base_url: "https://api.example.com"
  api_version: "v1"
  auth_token: "{env:API_TOKEN}"

stages:
  - name: "setup"
    request:
      url: "{base_url}/auth"
      method: POST
      json:
        token: "{auth_token}"
    response:
      status_code: 200
      save:
        json:
          session_token: token

# Available in all tests as {session_token}

Backend Selection

# Use different HTTP backend
exit_code = run(
    "tests/api_tests.tavern.yaml",
    tavern_http_backend="custom_http_plugin"
)

# Use custom MQTT backend
exit_code = run(
    "tests/mqtt_tests.tavern.yaml",
    tavern_mqtt_backend="custom_mqtt_plugin"
)

# Use custom gRPC backend  
exit_code = run(
    "tests/grpc_tests.tavern.yaml",
    tavern_grpc_backend="custom_grpc_plugin"
)

Strictness Control

# Strict validation (exact key matching)
exit_code = run(
    "tests/api_tests.tavern.yaml",
    tavern_strict=True
)

# Relaxed validation (allow extra keys)
exit_code = run(
    "tests/api_tests.tavern.yaml",
    tavern_strict=False
)

Integration with Pytest Arguments

# Pass pytest-specific arguments
exit_code = run(
    "tests/api_tests.tavern.yaml",
    pytest_args=[
        "-v",              # Verbose output
        "--tb=short",      # Short traceback format
        "-x",              # Stop on first failure
        "--maxfail=3",     # Stop after 3 failures
        "-k", "user_api",  # Run only tests matching pattern
        "--durations=10"   # Show 10 slowest tests
    ]
)

Types

from typing import Union, Optional
from contextlib import ExitStack
from _pytest.config import ExitCode

InvalidSettingsError = "tavern._core.exceptions.InvalidSettingsError"

Install with Tessl CLI