mian-mohid-mockapi 0.1.0__tar.gz

mian_mohid_mockapi-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: mian-mohid-mockapi
+Version: 0.1.0
+Summary: A local HTTP mock API server driven by YAML specs
+Author: Mian Mohid
+License: MIT
+Project-URL: Homepage, https://github.com/mian-mohid/mockapi
+Keywords: mockapi,yaml,http,server,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# mockapi
+
+`mockapi` is a small YAML-driven HTTP mock server for local development and API simulation.
+
+The PyPI distribution name is `mian-mohid-mockapi`, while the CLI command remains `mockapi`.
+
+## Install
+
+```bash
+pip install mian-mohid-mockapi
+```
+
+## Usage
+
+```bash
+mockapi serve spec.yaml
+mockapi serve spec.yaml --port 3000
+mockapi validate spec.yaml
+```
+
+## Spec
+
+Supported endpoint fields:
+
+- `path`
+- `method`
+- `status_code`
+- `response`
+- `headers` optional
+- `delay` optional in milliseconds
+- `description` optional
+- `auth` optional, including `none`
+
+See [requirements/fr.md](requirements/fr.md) for the full functional requirements.

mian_mohid_mockapi-0.1.0/README.md

@@ -0,0 +1,34 @@
+# mockapi
+
+`mockapi` is a small YAML-driven HTTP mock server for local development and API simulation.
+
+The PyPI distribution name is `mian-mohid-mockapi`, while the CLI command remains `mockapi`.
+
+## Install
+
+```bash
+pip install mian-mohid-mockapi
+```
+
+## Usage
+
+```bash
+mockapi serve spec.yaml
+mockapi serve spec.yaml --port 3000
+mockapi validate spec.yaml
+```
+
+## Spec
+
+Supported endpoint fields:
+
+- `path`
+- `method`
+- `status_code`
+- `response`
+- `headers` optional
+- `delay` optional in milliseconds
+- `description` optional
+- `auth` optional, including `none`
+
+See [requirements/fr.md](requirements/fr.md) for the full functional requirements.

mian_mohid_mockapi-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mian-mohid-mockapi"
+version = "0.1.0"
+description = "A local HTTP mock API server driven by YAML specs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Mian Mohid" }
+]
+dependencies = [
+  "PyYAML>=6.0",
+]
+keywords = ["mockapi", "yaml", "http", "server", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+
+[project.urls]
+Homepage = "https://github.com/mian-mohid/mockapi"
+
+[project.scripts]
+mockapi = "mockapi.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

mian_mohid_mockapi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mian_mohid_mockapi-0.1.0/src/mian_mohid_mockapi.egg-info/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: mian-mohid-mockapi
+Version: 0.1.0
+Summary: A local HTTP mock API server driven by YAML specs
+Author: Mian Mohid
+License: MIT
+Project-URL: Homepage, https://github.com/mian-mohid/mockapi
+Keywords: mockapi,yaml,http,server,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# mockapi
+
+`mockapi` is a small YAML-driven HTTP mock server for local development and API simulation.
+
+The PyPI distribution name is `mian-mohid-mockapi`, while the CLI command remains `mockapi`.
+
+## Install
+
+```bash
+pip install mian-mohid-mockapi
+```
+
+## Usage
+
+```bash
+mockapi serve spec.yaml
+mockapi serve spec.yaml --port 3000
+mockapi validate spec.yaml
+```
+
+## Spec
+
+Supported endpoint fields:
+
+- `path`
+- `method`
+- `status_code`
+- `response`
+- `headers` optional
+- `delay` optional in milliseconds
+- `description` optional
+- `auth` optional, including `none`
+
+See [requirements/fr.md](requirements/fr.md) for the full functional requirements.

mian_mohid_mockapi-0.1.0/src/mian_mohid_mockapi.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/mian_mohid_mockapi.egg-info/PKG-INFO
+src/mian_mohid_mockapi.egg-info/SOURCES.txt
+src/mian_mohid_mockapi.egg-info/dependency_links.txt
+src/mian_mohid_mockapi.egg-info/entry_points.txt
+src/mian_mohid_mockapi.egg-info/requires.txt
+src/mian_mohid_mockapi.egg-info/top_level.txt
+src/mockapi/__init__.py
+src/mockapi/__main__.py
+src/mockapi/cli.py
+src/mockapi/config.py
+src/mockapi/server.py
+tests/test_mockapi.py

mian_mohid_mockapi-0.1.0/src/mian_mohid_mockapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mian_mohid_mockapi-0.1.0/src/mian_mohid_mockapi.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mockapi = mockapi.cli:main

mian_mohid_mockapi-0.1.0/src/mian_mohid_mockapi.egg-info/requires.txt

@@ -0,0 +1,4 @@
+PyYAML>=6.0
+
+[dev]
+pytest>=8.0

mian_mohid_mockapi-0.1.0/src/mian_mohid_mockapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+mockapi

mian_mohid_mockapi-0.1.0/src/mockapi/__init__.py

@@ -0,0 +1,7 @@
+"""mockapi package."""
+
+from .config import load_spec, validate_spec
+from .server import MockApiServer, serve_spec
+
+__all__ = ["MockApiServer", "load_spec", "serve_spec", "validate_spec"]
+__version__ = "0.1.0"

mian_mohid_mockapi-0.1.0/src/mockapi/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mian_mohid_mockapi-0.1.0/src/mockapi/cli.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .config import load_spec
+from .server import serve_spec
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mockapi", description="Serve YAML-defined mock APIs")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    serve_parser = subparsers.add_parser("serve", help="start the HTTP server")
+    serve_parser.add_argument("spec_path", type=Path, help="path to the YAML spec file")
+    serve_parser.add_argument("--port", type=int, default=7248, help="port to bind to")
+    serve_parser.add_argument("--host", type=str, default="127.0.0.1", help="host to bind to")
+
+    validate_parser = subparsers.add_parser("validate", help="validate the YAML spec without starting a server")
+    validate_parser.add_argument("spec_path", type=Path, help="path to the YAML spec file")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "validate":
+        load_spec(args.spec_path)
+        print(f"Spec is valid: {args.spec_path}")
+        return 0
+
+    if args.command == "serve":
+        spec = load_spec(args.spec_path)
+        print(f"Serving {args.spec_path} on http://{args.host}:{args.port}")
+        serve_spec(spec, host=args.host, port=args.port)
+        return 0
+
+    parser.error("Unknown command")
+    return 2

mian_mohid_mockapi-0.1.0/src/mockapi/config.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import base64
+import binascii
+import json
+import re
+import warnings
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+
+SUPPORTED_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE"}
+SUPPORTED_AUTH_TYPES = {"bearer", "api_key", "basic"}
+
+
+class SpecError(ValueError):
+    """Raised when the YAML spec cannot be parsed or validated."""
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    type: str
+    token: str | None = None
+    header: str | None = None
+
+
+@dataclass(frozen=True)
+class EndpointSpec:
+    path: str
+    method: str
+    status_code: int
+    response: Any
+    headers: dict[str, str] = field(default_factory=dict)
+    delay: int = 0
+    description: str | None = None
+    auth: AuthConfig | None = None
+    auth_disabled: bool = False
+
+    def route_regex(self) -> re.Pattern[str]:
+        if self.path == "/":
+            return re.compile(r"^/$")
+
+        parts: list[str] = []
+        for segment in self.path.strip("/").split("/"):
+            if segment.startswith(":"):
+                name = segment[1:]
+                if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+                    raise SpecError(f"Invalid path parameter name '{name}' in {self.path}")
+                parts.append(f"(?P<{name}>[^/]+)")
+            else:
+                parts.append(re.escape(segment))
+        return re.compile(r"^/" + "/".join(parts) + r"$")
+
+    def match(self, method: str, path: str) -> dict[str, str] | None:
+        if self.method != method:
+            return None
+        match = self.route_regex().match(path)
+        if not match:
+            return None
+        return match.groupdict()
+
+
+@dataclass(frozen=True)
+class Spec:
+    endpoints: list[EndpointSpec]
+    global_auth: AuthConfig | None = None
+
+    def find_route(self, method: str, path: str) -> tuple[EndpointSpec, dict[str, str]] | None:
+        for endpoint in self.endpoints:
+            params = endpoint.match(method, path)
+            if params is not None:
+                return endpoint, params
+        return None
+
+
+def load_spec(path: str | Path) -> Spec:
+    spec_path = Path(path)
+    try:
+        raw = yaml.safe_load(spec_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise SpecError(f"Unable to read spec file {spec_path}: {exc}") from exc
+    except yaml.YAMLError as exc:
+        raise SpecError(f"Invalid YAML in {spec_path}: {exc}") from exc
+
+    return validate_spec(raw)
+
+
+def validate_spec(raw: Any) -> Spec:
+    if not isinstance(raw, Mapping):
+        raise SpecError("Spec root must be a mapping")
+
+    endpoints_raw = raw.get("endpoints")
+    if not isinstance(endpoints_raw, list):
+        raise SpecError("Spec must include an 'endpoints' list")
+
+    global_auth = None
+    global_block = raw.get("global")
+    if isinstance(global_block, Mapping):
+        global_auth = _parse_auth(global_block.get("auth"), "global.auth", allow_none=True)
+    elif global_block is not None:
+        raise SpecError("'global' must be a mapping when provided")
+
+    endpoints: list[EndpointSpec] = []
+    seen_routes: set[tuple[str, str]] = set()
+    for index, endpoint_raw in enumerate(endpoints_raw):
+        endpoint = _parse_endpoint(endpoint_raw, index)
+        route_key = (endpoint.method, endpoint.path)
+        if route_key in seen_routes:
+            warnings.warn(f"Duplicate route detected for {endpoint.method} {endpoint.path}", stacklevel=2)
+        seen_routes.add(route_key)
+        endpoints.append(endpoint)
+
+    return Spec(endpoints=endpoints, global_auth=global_auth)
+
+
+def _parse_endpoint(endpoint_raw: Any, index: int) -> EndpointSpec:
+    if not isinstance(endpoint_raw, Mapping):
+        raise SpecError(f"Endpoint #{index + 1} must be a mapping")
+
+    required_fields = ("path", "method", "status_code", "response")
+    missing = [field for field in required_fields if field not in endpoint_raw]
+    if missing:
+        raise SpecError(f"Endpoint #{index + 1} missing required field(s): {', '.join(missing)}")
+
+    path = endpoint_raw["path"]
+    method = endpoint_raw["method"]
+    status_code = endpoint_raw["status_code"]
+    response = endpoint_raw["response"]
+
+    if not isinstance(path, str) or not path.startswith("/"):
+        raise SpecError(f"Endpoint #{index + 1} path must be a string starting with '/'")
+    if not isinstance(method, str):
+        raise SpecError(f"Endpoint #{index + 1} method must be a string")
+    method = method.upper()
+    if method not in SUPPORTED_METHODS:
+        raise SpecError(f"Endpoint #{index + 1} uses unsupported method '{method}'")
+    if not isinstance(status_code, int):
+        raise SpecError(f"Endpoint #{index + 1} status_code must be an integer")
+    if status_code < 100 or status_code > 599:
+        raise SpecError(f"Endpoint #{index + 1} status_code must be a valid HTTP status code")
+
+    headers_raw = endpoint_raw.get("headers") or {}
+    if not isinstance(headers_raw, Mapping):
+        raise SpecError(f"Endpoint #{index + 1} headers must be a mapping when provided")
+    headers = {str(key): str(value) for key, value in headers_raw.items()}
+
+    delay = endpoint_raw.get("delay", 0)
+    if not isinstance(delay, int) or delay < 0:
+        raise SpecError(f"Endpoint #{index + 1} delay must be a non-negative integer")
+
+    description = endpoint_raw.get("description")
+    if description is not None and not isinstance(description, str):
+        raise SpecError(f"Endpoint #{index + 1} description must be a string when provided")
+
+    auth_value = endpoint_raw.get("auth")
+    auth_disabled = auth_value == "none"
+    auth = None if auth_disabled else _parse_auth(auth_value, f"endpoint #{index + 1}.auth", allow_none=True)
+
+    try:
+        json.dumps(response)
+    except (TypeError, ValueError) as exc:
+        raise SpecError(f"Endpoint #{index + 1} response must be JSON-serializable") from exc
+
+    return EndpointSpec(
+        path=path,
+        method=method,
+        status_code=status_code,
+        response=response,
+        headers=headers,
+        delay=delay,
+        description=description,
+        auth=auth,
+        auth_disabled=auth_disabled,
+    )
+
+
+def _parse_auth(auth_raw: Any, label: str, *, allow_none: bool) -> AuthConfig | None:
+    if auth_raw is None:
+        return None
+    if allow_none and auth_raw == "none":
+        return None
+    if not isinstance(auth_raw, Mapping):
+        raise SpecError(f"{label} must be a mapping or 'none'")
+
+    auth_type = auth_raw.get("type")
+    token = auth_raw.get("token")
+    header = auth_raw.get("header")
+
+    if not isinstance(auth_type, str):
+        warnings.warn(f"{label} is missing an auth type", stacklevel=3)
+        auth_type = ""
+    auth_type = auth_type.lower()
+    if auth_type not in SUPPORTED_AUTH_TYPES:
+        warnings.warn(f"{label} uses unsupported auth type '{auth_type}'", stacklevel=3)
+
+    if token is None or token == "":
+        warnings.warn(f"{label} is missing a token", stacklevel=3)
+        token = None
+    elif not isinstance(token, str):
+        token = str(token)
+
+    if header is not None and not isinstance(header, str):
+        header = str(header)
+
+    return AuthConfig(type=auth_type, token=token, header=header)
+
+
+def expected_basic_token_value(token: str) -> str:
+    """Return the request header fragment that should match the configured basic token."""
+
+    if ":" in token:
+        encoded = base64.b64encode(token.encode("utf-8")).decode("ascii")
+        return f"Basic {encoded}"
+
+    try:
+        decoded = base64.b64decode(token, validate=True).decode("utf-8")
+    except (binascii.Error, UnicodeDecodeError):
+        decoded = ""
+
+    if ":" in decoded:
+        return f"Basic {token}"
+
+    encoded = base64.b64encode(token.encode("utf-8")).decode("ascii")
+    return f"Basic {encoded}"

mian_mohid_mockapi-0.1.0/src/mockapi/server.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+from urllib.parse import urlparse
+
+from .config import AuthConfig, EndpointSpec, Spec, expected_basic_token_value
+
+
+RESET = "\033[0m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+RED = "\033[31m"
+
+
+def serve_spec(spec: Spec, *, host: str = "127.0.0.1", port: int = 7248) -> None:
+    server = MockApiServer(spec, host=host, port=port)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.shutdown()
+
+
+class MockApiServer:
+    def __init__(self, spec: Spec, *, host: str = "127.0.0.1", port: int = 7248) -> None:
+        self.spec = spec
+        self._handler_class = self._build_handler_class()
+        self._server = ThreadingHTTPServer((host, port), self._handler_class)
+        self._server.mockapi_spec = spec  # type: ignore[attr-defined]
+        self._thread: threading.Thread | None = None
+
+    @property
+    def server_address(self) -> tuple[str, int]:
+        host, port = self._server.server_address
+        return str(host), int(port)
+
+    def serve_forever(self) -> None:
+        self._server.serve_forever()
+
+    def start_in_thread(self) -> threading.Thread:
+        thread = threading.Thread(target=self.serve_forever, daemon=True)
+        thread.start()
+        self._thread = thread
+        return thread
+
+    def shutdown(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=2)
+
+    def _build_handler_class(self) -> type[BaseHTTPRequestHandler]:
+        spec = self.spec
+
+        class MockApiRequestHandler(BaseHTTPRequestHandler):
+            protocol_version = "HTTP/1.1"
+            server_version = "mockapi/0.1"
+
+            def do_GET(self) -> None:  # noqa: N802
+                self._handle_request("GET")
+
+            def do_POST(self) -> None:  # noqa: N802
+                self._handle_request("POST")
+
+            def do_PUT(self) -> None:  # noqa: N802
+                self._handle_request("PUT")
+
+            def do_PATCH(self) -> None:  # noqa: N802
+                self._handle_request("PATCH")
+
+            def do_DELETE(self) -> None:  # noqa: N802
+                self._handle_request("DELETE")
+
+            def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+                return
+
+            def _handle_request(self, method: str) -> None:
+                started = time.perf_counter()
+                parsed_path = urlparse(self.path).path
+                routed = spec.find_route(method, parsed_path)
+
+                if routed is None:
+                    self._write_json_response(404, {"error": "Route not found"})
+                    elapsed = (time.perf_counter() - started) * 1000
+                    self._log_request(method, parsed_path, "unmatched", 404, elapsed)
+                    return
+
+                endpoint, params = routed
+                auth = endpoint.auth if endpoint.auth is not None else spec.global_auth
+                if not self._is_authorized(auth):
+                    self._write_json_response(
+                        401,
+                        {"error": "Unauthorized", "detail": "Missing or invalid auth token"},
+                    )
+                    elapsed = (time.perf_counter() - started) * 1000
+                    self._log_request(method, parsed_path, endpoint.path, 401, elapsed)
+                    return
+
+                if endpoint.delay:
+                    time.sleep(endpoint.delay / 1000)
+
+                response_body = _inject_path_params(endpoint.response, params)
+                self._write_json_response(endpoint.status_code, response_body, endpoint.headers)
+                elapsed = (time.perf_counter() - started) * 1000
+                self._log_request(method, parsed_path, endpoint.path, endpoint.status_code, elapsed)
+
+            def _is_authorized(self, auth: AuthConfig | None) -> bool:
+                if auth is None:
+                    return True
+                if not auth.type or not auth.token:
+                    return False
+
+                authorization = self.headers.get("Authorization", "")
+                if auth.type == "bearer":
+                    return authorization == f"Bearer {auth.token}"
+
+                if auth.type == "api_key":
+                    header_name = auth.header or "X-API-Key"
+                    return self.headers.get(header_name, "") == auth.token
+
+                if auth.type == "basic":
+                    return authorization == expected_basic_token_value(auth.token)
+
+                return False
+
+            def _write_json_response(
+                self,
+                status_code: int,
+                payload: Any,
+                headers: dict[str, str] | None = None,
+            ) -> None:
+                body = json.dumps(payload).encode("utf-8")
+                self.send_response(status_code)
+                if headers:
+                    for header_name, header_value in headers.items():
+                        self.send_header(header_name, header_value)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            def _log_request(
+                self,
+                method: str,
+                path: str,
+                matched_route: str,
+                status_code: int,
+                elapsed_ms: float,
+            ) -> None:
+                if 200 <= status_code < 300:
+                    color = GREEN
+                elif 300 <= status_code < 400:
+                    color = YELLOW
+                else:
+                    color = RED
+
+                print(
+                    f"{color}{method} {path} -> {matched_route} {status_code} {elapsed_ms:.1f}ms{RESET}",
+                    flush=True,
+                )
+
+        return MockApiRequestHandler
+
+
+def _inject_path_params(payload: Any, params: dict[str, str]) -> Any:
+    if isinstance(payload, dict):
+        return {key: _inject_path_params(value, params) for key, value in payload.items()}
+    if isinstance(payload, list):
+        return [_inject_path_params(value, params) for value in payload]
+    if isinstance(payload, tuple):
+        return tuple(_inject_path_params(value, params) for value in payload)
+    if isinstance(payload, str):
+        updated = payload
+        for name, value in params.items():
+            updated = updated.replace(f":{name}", value)
+        return updated
+    return payload

mian_mohid_mockapi-0.1.0/tests/test_mockapi.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import base64
+import json
+import time
+from pathlib import Path
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+import pytest
+
+from mockapi import MockApiServer, load_spec
+from mockapi.cli import main
+
+
+def _write_spec(tmp_path: Path, content: str) -> Path:
+    path = tmp_path / "spec.yaml"
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _run_server(spec_path: Path) -> MockApiServer:
+    spec = load_spec(spec_path)
+    server = MockApiServer(spec, port=0)
+    server.start_in_thread()
+    time.sleep(0.1)
+    return server
+
+
+def test_validate_spec_accepts_auth_and_path_params(tmp_path: Path) -> None:
+    spec_path = _write_spec(
+        tmp_path,
+        """
+global:
+  auth:
+    type: bearer
+    token: globaltoken
+endpoints:
+  - path: /users/:id
+    method: GET
+    status_code: 200
+    response:
+      id: :id
+      message: Hello :id
+""",
+    )
+
+    spec = load_spec(spec_path)
+    assert len(spec.endpoints) == 1
+    assert spec.endpoints[0].method == "GET"
+    assert spec.global_auth is not None
+
+
+def test_server_returns_path_params_and_headers(tmp_path: Path) -> None:
+    spec_path = _write_spec(
+        tmp_path,
+        """
+endpoints:
+  - path: /users/:id
+    method: GET
+    status_code: 200
+    headers:
+      X-Example: present
+    response:
+      id: :id
+      message: Hello :id
+""",
+    )
+
+    server = _run_server(spec_path)
+    host, port = server.server_address
+    try:
+        with urlopen(f"http://{host}:{port}/users/42") as response:
+            assert response.status == 200
+            assert response.headers["X-Example"] == "present"
+            body = json.loads(response.read().decode("utf-8"))
+            assert body == {"id": "42", "message": "Hello 42"}
+    finally:
+        server.shutdown()
+
+
+def test_server_enforces_bearer_auth(tmp_path: Path) -> None:
+    spec_path = _write_spec(
+        tmp_path,
+        """
+endpoints:
+  - path: /profile
+    method: GET
+    status_code: 200
+    auth:
+      type: bearer
+      token: secret-token
+    response:
+      ok: true
+""",
+    )
+
+    server = _run_server(spec_path)
+    host, port = server.server_address
+    try:
+        request = Request(f"http://{host}:{port}/profile")
+        with pytest.raises(HTTPError) as exc_info:
+            urlopen(request)
+        assert exc_info.value.code == 401
+
+        authed_request = Request(f"http://{host}:{port}/profile", headers={"Authorization": "Bearer secret-token"})
+        with urlopen(authed_request) as response:
+            assert response.status == 200
+            assert json.loads(response.read().decode("utf-8")) == {"ok": True}
+    finally:
+        server.shutdown()
+
+
+def test_basic_auth_accepts_raw_token(tmp_path: Path) -> None:
+    spec_path = _write_spec(
+        tmp_path,
+        """
+endpoints:
+  - path: /basic
+    method: GET
+    status_code: 200
+    auth:
+      type: basic
+      token: user:pass
+    response:
+      ok: true
+""",
+    )
+
+    server = _run_server(spec_path)
+    host, port = server.server_address
+    try:
+        encoded = base64.b64encode(b"user:pass").decode("ascii")
+        request = Request(f"http://{host}:{port}/basic", headers={"Authorization": f"Basic {encoded}"})
+        with urlopen(request) as response:
+            assert response.status == 200
+    finally:
+        server.shutdown()
+
+
+def test_404_fallback(tmp_path: Path) -> None:
+    spec_path = _write_spec(
+        tmp_path,
+        """
+endpoints:
+  - path: /known
+    method: GET
+    status_code: 200
+    response:
+      ok: true
+""",
+    )
+
+    server = _run_server(spec_path)
+    host, port = server.server_address
+    try:
+        with pytest.raises(HTTPError) as exc_info:
+            urlopen(f"http://{host}:{port}/missing")
+        assert exc_info.value.code == 404
+        assert json.loads(exc_info.value.read().decode("utf-8")) == {"error": "Route not found"}
+    finally:
+        server.shutdown()
+
+
+def test_cli_validate_returns_zero(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    spec_path = _write_spec(
+        tmp_path,
+        """
+endpoints:
+  - path: /ping
+    method: GET
+    status_code: 200
+    response:
+      ok: true
+""",
+    )
+
+    exit_code = main(["validate", str(spec_path)])
+    assert exit_code == 0
+    captured = capsys.readouterr()
+    assert "Spec is valid" in captured.out