auto-api-test 0.1.0__py3-none-any.whl

auto_api_test/__init__.py

@@ -0,0 +1,3 @@
+"""auto-api-test: YAML DSL API testing framework based on pytest and requests."""
+
+__version__ = "0.1.0"

auto_api_test/assertions.py

@@ -0,0 +1,158 @@
+"""Assertion engine with expression prefix support."""
+
+import re
+from typing import Any
+
+
+class AssertionError_(Exception):
+    """Custom assertion error with expected/actual detail."""
+
+    def __init__(self, field: str, expected: Any, actual: Any, operator: str = "="):
+        self.field = field
+        self.expected = expected
+        self.actual = actual
+        self.operator = operator
+        super().__init__(
+            f"Assertion failed on '{field}': expected {operator} {expected!r}, got {actual!r}"
+        )
+
+
+def _numeric_eq(a: Any, b: Any) -> bool:
+    """Try numeric coercion for string vs number comparison."""
+    try:
+        return float(a) == float(b)
+    except (ValueError, TypeError):
+        return False
+
+
+def _resolve_field(data: Any, field_path: str) -> Any:
+    """Resolve a dotted field path against data. Supports .len for length."""
+    parts = field_path.split(".")
+    current = data
+    for part in parts:
+        if part == "len":
+            if isinstance(current, (list, str, dict)):
+                current = len(current)
+            else:
+                raise AssertionError_(field_path, "list/str/dict", type(current).__name__, ".len")
+        elif isinstance(current, dict):
+            if part not in current:
+                raise AssertionError_(field_path, "key exists", f"key '{part}' missing")
+            current = current[part]
+        elif isinstance(current, list) and part.isdigit():
+            idx = int(part)
+            if idx >= len(current):
+                raise AssertionError_(field_path, f"index {idx} exists", f"list length {len(current)}")
+            current = current[idx]
+        else:
+            raise AssertionError_(field_path, "resolvable path", f"cannot resolve '{part}' in {type(current).__name__}")
+    return current
+
+
+def _check_numeric_expr(actual: Any, expr: str, field: str) -> None:
+    """Check numeric comparison expressions like >0, >=1, <100."""
+    m = re.match(r"^(>=|<=|>|<)\s*(-?\d+(?:\.\d+)?)$", expr)
+    if not m:
+        raise AssertionError_(field, "valid numeric expression", expr, "expression")
+    op, val_str = m.group(1), m.group(2)
+    expected = float(val_str)
+    actual_num = float(actual)
+
+    ops = {
+        ">": actual_num > expected,
+        ">=": actual_num >= expected,
+        "<": actual_num < expected,
+        "<=": actual_num <= expected,
+    }
+    if not ops[op]:
+        raise AssertionError_(field, f"{op}{expected}", actual_num, op)
+
+
+def _check_regex(actual: str, pattern: str, field: str) -> None:
+    """Check regex match."""
+    if not re.search(pattern, str(actual)):
+        raise AssertionError_(field, f"~={pattern}", actual, "regex")
+
+
+def _check_contains(actual: str, substring: str, field: str) -> None:
+    """Check string contains."""
+    if substring not in str(actual):
+        raise AssertionError_(field, f"contains:{substring}", actual, "contains")
+
+
+def assert_value(field: str, expected: Any, actual: Any) -> None:
+    """Assert a single field value against expected.
+
+    Expression prefixes:
+      >0, <100, >=1, <=999  - numeric comparison
+      ~=pattern             - regex match
+      contains:sub          - string contains
+      not_null              - value is not None
+      is_null               - value is None
+      is_true               - boolean truthy
+      is_false              - boolean falsy
+      (other)               - exact equality
+    """
+    if isinstance(expected, str):
+        if expected.startswith((">", "<")) and not expected.startswith("~="):
+            _check_numeric_expr(actual, expected, field)
+        elif expected.startswith("~="):
+            _check_regex(actual, expected[2:], field)
+        elif expected.startswith("contains:"):
+            _check_contains(actual, expected[len("contains:"):], field)
+        elif expected == "not_null":
+            if actual is None:
+                raise AssertionError_(field, "not None", None, "not_null")
+        elif expected == "is_null":
+            if actual is not None:
+                raise AssertionError_(field, None, actual, "is_null")
+        elif expected == "is_true":
+            if not actual:
+                raise AssertionError_(field, True, actual, "is_true")
+        elif expected == "is_false":
+            if actual:
+                raise AssertionError_(field, False, actual, "is_false")
+        else:
+            if actual != expected:
+                if _numeric_eq(expected, actual):
+                    return
+                raise AssertionError_(field, expected, actual)
+    else:
+        if actual != expected:
+            if _numeric_eq(expected, actual):
+                return
+            raise AssertionError_(field, expected, actual)
+
+
+def assert_json(json_expect: dict, response_json: Any) -> list[str]:
+    """Assert all fields in json_expect against response_json.
+
+    Returns a list of failure messages (empty if all pass).
+    """
+    failures = []
+    for field, expected in json_expect.items():
+        try:
+            actual = _resolve_field(response_json, field)
+            assert_value(field, expected, actual)
+        except AssertionError_ as e:
+            failures.append(str(e))
+    return failures
+
+
+def assert_status_code(expected: int, actual: int) -> str | None:
+    """Assert status code. Returns failure message or None."""
+    if expected != actual:
+        return f"Status code: expected {expected}, got {actual}"
+    return None
+
+
+def assert_headers(expected: dict, actual: dict) -> list[str]:
+    """Assert response headers. Returns list of failure messages."""
+    failures = []
+    for key, expected_val in expected.items():
+        actual_val = actual.get(key)
+        if actual_val is None:
+            failures.append(f"Header '{key}': expected '{expected_val}', not present")
+        elif expected_val not in actual_val:
+            failures.append(f"Header '{key}': expected contains '{expected_val}', got '{actual_val}'")
+    return failures

auto_api_test/cli.py

@@ -0,0 +1,142 @@
+"""CLI entry point for atr command."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import pytest
+
+from . import __version__
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="atr",
+        description="auto-api-test: YAML DSL API testing framework",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # run command
+    run_parser = subparsers.add_parser("run", help="Run API tests from YAML files")
+    run_parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="YAML file or directory to run (default: current directory)",
+    )
+    run_parser.add_argument(
+        "-o", "--report",
+        default=None,
+        help="Report output path (default: report.md alongside YAML file)",
+    )
+    run_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+    run_parser.add_argument(
+        "--env-file",
+        default=None,
+        help="Load environment variables from .env file",
+    )
+    run_parser.add_argument(
+        "--base-url",
+        default=None,
+        help="Override base_url for all tests",
+    )
+
+    # init command
+    init_parser = subparsers.add_parser("init", help="Create example YAML test file")
+    init_parser.add_argument(
+        "filename",
+        nargs="?",
+        default="test_api.yaml",
+        help="Output filename (default: test_api.yaml)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        return _run_tests(args)
+    elif args.command == "init":
+        return _init_project(args.filename)
+    else:
+        parser.print_help()
+        return 0
+
+
+def _run_tests(args):
+    """Execute tests via pytest.main()."""
+    path = Path(args.path)
+    if not path.exists():
+        print(f"Error: path '{args.path}' does not exist", file=sys.stderr)
+        return 1
+
+    pytest_args = [str(path)]
+
+    if args.report:
+        pytest_args.extend(["--report", args.report])
+    if args.env_file:
+        pytest_args.extend(["--env-file", args.env_file])
+    if args.base_url:
+        pytest_args.extend(["--base-url", args.base_url])
+    if args.verbose:
+        pytest_args.append("-v")
+
+    exit_code = pytest.main(pytest_args)
+    return exit_code
+
+
+def _init_project(filename):
+    """Create an example YAML test file."""
+    example = """\
+config:
+  base_url: "https://jsonplaceholder.typicode.com"
+  timeout: 30
+
+tests:
+  - name: "Get all posts"
+    request:
+      method: GET
+      url: /posts
+    expect:
+      status_code: 200
+      json:
+        0.id: "not_null"
+
+  - name: "Get first post"
+    request:
+      method: GET
+      url: /posts/1
+    expect:
+      status_code: 200
+      json:
+        userId: "not_null"
+        title: "not_null"
+
+  - name: "Create a post"
+    request:
+      method: POST
+      url: /posts
+      json:
+        title: "test post"
+        body: "test body"
+        userId: 1
+    expect:
+      status_code: 201
+      json:
+        id: "not_null"
+"""
+    path = Path(filename)
+    if path.exists():
+        print(f"Error: file '{filename}' already exists", file=sys.stderr)
+        return 1
+    path.write_text(example, encoding="utf-8")
+    print(f"Created example test file: {filename}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

auto_api_test/issue.py

@@ -0,0 +1,175 @@
+"""Issue backends for auto-creating bug tickets from test failures."""
+
+import os
+from abc import ABC, abstractmethod
+
+import requests
+
+
+class IssueBackend(ABC):
+    """Abstract base for git platform issue creation."""
+
+    def __init__(self, repo: str, token: str, base_url: str = ""):
+        self.repo = repo  # "owner/repo" format
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+
+    @abstractmethod
+    def create_issue(self, title: str, body: str, labels: list[str] | None = None) -> dict:
+        """Create an issue. Returns API response dict with at least 'url' key."""
+
+
+class GitHubBackend(IssueBackend):
+    """GitHub Issues API."""
+
+    def __init__(self, repo: str, token: str, base_url: str = "https://api.github.com"):
+        super().__init__(repo, token, base_url)
+
+    def create_issue(self, title: str, body: str, labels: list[str] | None = None) -> dict:
+        url = f"{self.base_url}/repos/{self.repo}/issues"
+        payload = {"title": title, "body": body}
+        if labels:
+            payload["labels"] = labels
+        resp = requests.post(
+            url,
+            json=payload,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Accept": "application/vnd.github+json",
+            },
+            timeout=30,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return {"url": data.get("html_url", ""), "number": data.get("number")}
+
+
+class GitLabBackend(IssueBackend):
+    """GitLab Issues API."""
+
+    def __init__(self, repo: str, token: str, base_url: str = "https://gitlab.com"):
+        super().__init__(repo, token, base_url)
+
+    def create_issue(self, title: str, body: str, labels: list[str] | None = None) -> dict:
+        project_id = self.repo.replace("/", "%2F")
+        url = f"{self.base_url}/api/v4/projects/{project_id}/issues"
+        payload = {"title": title, "description": body}
+        if labels:
+            payload["labels"] = ",".join(labels)
+        resp = requests.post(
+            url,
+            json=payload,
+            headers={"PRIVATE-TOKEN": self.token},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return {"url": data.get("web_url", ""), "number": data.get("iid")}
+
+
+class GiteaBackend(IssueBackend):
+    """Gitea Issues API."""
+
+    def __init__(self, repo: str, token: str, base_url: str = "http://localhost:3000"):
+        super().__init__(repo, token, base_url)
+
+    def create_issue(self, title: str, body: str, labels: list[str] | None = None) -> dict:
+        owner, name = self.repo.split("/", 1)
+        url = f"{self.base_url}/api/v1/repos/{owner}/{name}/issues"
+        payload = {"title": title, "body": body}
+        if labels:
+            payload["labels"] = labels
+        resp = requests.post(
+            url,
+            json=payload,
+            headers={"Authorization": f"token {self.token}"},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return {"url": data.get("html_url", ""), "number": data.get("number")}
+
+
+class GiteeBackend(IssueBackend):
+    """Gitee Issues API."""
+
+    def __init__(self, repo: str, token: str, base_url: str = "https://gitee.com"):
+        super().__init__(repo, token, base_url)
+
+    def create_issue(self, title: str, body: str, labels: list[str] | None = None) -> dict:
+        owner, repo_name = self.repo.split("/", 1)
+        url = f"{self.base_url}/api/v5/repos/{owner}/{repo_name}/issues"
+        payload = {"title": title, "body": body, "access_token": self.token}
+        if labels:
+            payload["labels"] = ",".join(labels)
+        resp = requests.post(url, json=payload, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+        return {"url": data.get("html_url", ""), "number": data.get("number")}
+
+
+_BACKENDS: dict[str, type[IssueBackend]] = {
+    "github": GitHubBackend,
+    "gitlab": GitLabBackend,
+    "gitea": GiteaBackend,
+    "gitee": GiteeBackend,
+}
+
+
+def create_backend(platform: str, repo: str, token: str, base_url: str = "") -> IssueBackend:
+    """Factory: create an IssueBackend by platform name."""
+    cls = _BACKENDS.get(platform.lower())
+    if cls is None:
+        raise ValueError(f"Unsupported platform: {platform!r}. Choose from: {', '.join(_BACKENDS)}")
+    kwargs = {"repo": repo, "token": token}
+    if base_url:
+        kwargs["base_url"] = base_url
+    return cls(**kwargs)
+
+
+def create_issues_from_failures(
+    failures: list[dict],
+    platform: str,
+    repo: str,
+    base_url: str = "",
+    labels: list[str] | None = None,
+) -> list[dict]:
+    """Create one issue per failure. Returns list of created issue info."""
+    token = os.environ.get("git_token", "")
+    if not token:
+        raise ValueError("Environment variable 'git_token' is not set")
+
+    backend = create_backend(platform, repo, token, base_url)
+    created = []
+
+    for fail in failures:
+        title = f"[API Test {fail['type']}] {fail['name']}"
+        lines = [
+            f"## {fail['name']}",
+            "",
+            f"- **Method:** {fail['method']}",
+            f"- **URL:** `{fail['url']}`",
+            f"- **Status:** {fail.get('status_code', '-')}",
+            f"- **Duration:** {fail['duration_ms']} ms",
+            "",
+            "### Detail",
+            "",
+            fail["detail"],
+        ]
+        if fail.get("response_body"):
+            lines.extend([
+                "",
+                "<details><summary>Response Body</summary>",
+                "",
+                "```json",
+                fail["response_body"],
+                "```",
+                "",
+                "</details>",
+            ])
+        body = "\n".join(lines)
+
+        result = backend.create_issue(title, body, labels)
+        created.append(result)
+
+    return created

auto_api_test/parser.py

@@ -0,0 +1,118 @@
+"""YAML DSL parser with variable substitution."""
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ValidationError(Exception):
+    """Raised when YAML DSL structure is invalid."""
+
+    def __init__(self, message: str, path: str = "", line: int = 0):
+        self.path = path
+        self.line = line
+        detail = f"[{path}:{line}] " if path else ""
+        super().__init__(f"{detail}{message}")
+
+
+_VAR_PATTERN = re.compile(r"\$\{(\w+)\}")
+
+
+def resolve_vars(obj: Any, variables: dict[str, str]) -> Any:
+    """Recursively substitute ${VAR} placeholders in strings."""
+    if isinstance(obj, str):
+        def _replace(m: re.Match) -> str:
+            key = m.group(1)
+            val = variables.get(key)
+            if val is None:
+                val = os.environ.get(key)
+            if val is None:
+                return m.group(0)
+            return str(val)
+
+        return _VAR_PATTERN.sub(_replace, obj)
+    if isinstance(obj, dict):
+        return {k: resolve_vars(v, variables) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [resolve_vars(item, variables) for item in obj]
+    return obj
+
+
+def _validate_config(config: dict | None, path: str) -> dict:
+    if config is None:
+        return {}
+    if not isinstance(config, dict):
+        raise ValidationError("config must be a mapping", path, 0)
+    return config
+
+
+def _validate_test(test: Any, path: str, index: int) -> dict:
+    if not isinstance(test, dict):
+        raise ValidationError(f"tests[{index}] must be a mapping", path)
+    if "name" not in test:
+        raise ValidationError(f"tests[{index}] missing 'name'", path)
+    if "request" not in test:
+        raise ValidationError(f"tests[{index}] missing 'request'", path)
+    req = test["request"]
+    if not isinstance(req, dict):
+        raise ValidationError(f"tests[{index}].request must be a mapping", path)
+    if "method" not in req:
+        raise ValidationError(f"tests[{index}].request missing 'method'", path)
+    if "url" not in req:
+        raise ValidationError(f"tests[{index}].request missing 'url'", path)
+    return test
+
+
+def load_yaml(path: str | Path) -> dict:
+    """Load and validate a YAML DSL file. Returns parsed dict with variables resolved."""
+    path = Path(path)
+    if not path.exists():
+        raise ValidationError(f"File not found: {path}")
+
+    with open(path, encoding="utf-8") as f:
+        try:
+            data = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ValidationError(f"YAML parse error: {e}", str(path))
+
+    if not isinstance(data, dict):
+        raise ValidationError("Root must be a mapping", str(path))
+
+    config = _validate_config(data.get("config"), str(path))
+    tests = data.get("tests")
+    if not isinstance(tests, list) or len(tests) == 0:
+        raise ValidationError("'tests' must be a non-empty list", str(path))
+
+    for i, test in enumerate(tests):
+        _validate_test(test, str(path), i)
+
+    # Collect extract variables defined in config (if any)
+    variables = {}
+    env_file = config.get("env_file")
+    if env_file:
+        from dotenv import load_dotenv
+        load_dotenv(env_file)
+
+    # First pass: collect all extract definitions for variable resolution context
+    for test in tests:
+        extract = test.get("extract", {})
+        if isinstance(extract, dict):
+            variables.update({k: "" for k in extract})
+
+    # Resolve config-level variables
+    config = resolve_vars(config, variables)
+
+    return {"config": config, "tests": tests, "variables": variables}
+
+
+def get_config(data: dict) -> dict:
+    """Extract config section."""
+    return data.get("config", {})
+
+
+def get_tests(data: dict) -> list[dict]:
+    """Extract tests list."""
+    return data.get("tests", [])