aomaker API Automation Testing Framework

aomaker provides a comprehensive toolchain for enterprise-grade API automation:

• Declarative Modeling: Uses attrs for clear, type-safe API definitions.
• Doc-Driven Development: Automatic model generation from OpenAPI/Swagger.
• Automatic JSON Schema Validation: Automatically validates response structures against the defined model after every request.
• Middleware System: Allows custom logic (logging, retries, performance stats) before/after requests.
• Authentication Management: Supports multiple auth methods and dynamic header overrides.
• Parallel Testing: Supports multi-threading and multi-processing with various task distribution strategies.
• Storage & Cache: Built-in SQLite-based management for config, cache, schema, and statistics.
• Ecosystem Tools:
  • Mock Server: For local testing and debugging.
  • Dashboard: Web UI for monitoring execution and logs.
  • CLI: For scaffolding, running tests, and generating models.
  • Reporting: Optimized Allure and aomaker-specific reports.

aomaker uses a SQLite database (aomaker.db) for lightweight, thread-safe storage of configurations, caches, and schemas. It contains four core tables:

Global Config Usage

from aomaker.storage import config

def test_env_config():
    current_env = config.get("env")
    test_host = config.get("host")

Cache Usage

from aomaker.storage import cache

def setup():
    cache.set("auth_token", "Bearer xxxxx")

def test_api_call():
    headers = {"Authorization": cache.get("auth_token")}

aomaker uses a declarative, object-oriented modeling approach to define APIs. Instead of hardcoding URLs and parameters, you define each API as a Python class using the attrs library. This allows you to structure path parameters, query parameters, request bodies, and response bodies into typed objects, providing full IDE autocomplete and type checking.

Key components of an API model include:

• PathParams: A nested class defining variables in the URL path.
• QueryParams: A nested class defining URL query parameters.
• Response Model: A type hint (often using BaseAPIObject[ResponseClass]) that defines the expected structure of the API response.
• router: A decorator used to bind the class to a specific HTTP method and path.

from attrs import define, field 
from aomaker.core.router import router
from aomaker.core.api_object import BaseAPIObject

@define(kw_only=True)  
@router.get("/api/{namespace}/containers")  
class GetContainersAPI(BaseAPIObject[ContainersResponse]):  
    """Get container list"""
  
    @define  
    class PathParams:  
        namespace: str = field()  
  
    @define  
    class QueryParams:  
        offset: Optional[int] = field(default=0)  
        limit: Optional[int] = field(default=10)  
        name: Optional[str] = field(  
            default=None, metadata={"description": "Container name, fuzzy search"}  
        )  
  
    path_params: PathParams  
    query_params: QueryParams = field(factory=QueryParams)  
    response: Optional[ContainersResponse] = field(  
        default=ContainersResponse  
    )

If your API documentation's request format (URL/Body) differs from the actual live network traffic (e.g., due to a Microservice Gateway, Encryption/Signing, or required Public Parameters), you can use a RequestConverter to translate the interface model into the required format.

How to use:

1. Inherit from RequestConverter: Override the post_prepare hook to transform the PreparedRequest.
2. Define a Base API Class: Create a class inheriting from BaseAPIObject[T] and set the converter field to your custom class.
3. Inherit from the Base API: All specific API implementations should inherit from your custom base class.

This ensures 100% fidelity to real traffic and allows you to maintain gateway rules in a single location.

# 1. Inherit RequestConverter
@define
class GatewayConverter(RequestConverter):
    def post_prepare(self, req: PreparedRequest) -> PreparedRequest:
        body = {"params": json.dumps(req.request_body or {}), "method": req.method}
        return PreparedRequest(
            method="POST",
            url=f"{self.base_url}/global_api/",
            params={"action": self.route},
            request_body=body,
            headers=req.headers,
        )

# 2. Declare a base class
@define
class GatewayAPI(BaseAPIObject[T]):
    converter = field(default=GatewayConverter)

# 3. All interfaces inherit GatewayAPI
class GetContainersAPI(GatewayAPI[ContainersResp]): 
    ...

You can inject custom logic (logging, mocking, retries, performance monitoring) into the "request → response" lifecycle using middleware.

Key Concepts:

• Pluggable: Any callable with the signature callable(request, next) -> response can be a middleware.
• Configurable: Use middlewares/middleware.yaml to enable, disable, or reorder middleware without changing code.
• Execution Order: When running arun, the framework scans the middlewares/ directory and executes them based on their priority and options.

Implementation Steps:

1. Define the middleware using the @middleware decorator.
2. Configure the middleware in middlewares/middleware.yaml.

Common Use Cases:

• Structured Logging: Use the built-in logging_middleware.
• Mocking: Intercept specific URLs to return a CachedResponse.
• Performance Monitoring: Record time differences and alert on slow thresholds using options: {slow_threshold: 1.0}.
• Retries: Catch exceptions or specific status codes to retry the next call.

# middlewares/retry.py
from aomaker.core.middlewares.registry import middleware, registry

@middleware(name="retry", priority=800, enabled=True,
            options={"max_retries": 3, "codes": [500, 502, 503]})
def retry_mw(request, call_next):
    for _ in range(registry.middleware_configs["retry"].options["max_retries"]):
        resp = call_next(request)
        if resp.status_code not in registry.middleware_configs["retry"].options["codes"]:
            return resp   # Success
    return resp            # Failed after retries

# middlewares/middleware.yaml
logging_middleware: # Built-in
  enabled: true
  priority: 900

retry:         # Name must match the decorator name
  enabled: true
  priority: 800
  options:
    max_retries: 3
    codes: [500, 502, 503]