marionette-test 0.1.0__tar.gz

marionette_test-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

marionette_test-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-19
+
+### Added
+- Initial package skeleton: `marionette.test` namespace, typer-based CLI with
+  `init` / `config` / `doctor` / `run` / `serve` subcommands.
+- `marionette.test.action` public API: `@action` decorator, in-process registry,
+  and `Context` / `RequestView` / `ResponseView` dataclasses for user-authored hooks.
+- Pydantic v2 model layer for `FeatureUnit` / `Sheet` / `Case` / `Endpoint` /
+  `TableInsert` / `SqlStatement` with consistency validators.
+- Round-trip YAML I/O (`storage/yaml_io.py`) using ruamel.yaml so user edits keep
+  comments and key order.
+- Workspace configuration loader (`config/env.py`) reading `config/env.yml`,
+  resolving secrets from env vars.
+- Execution engine: variable substitution (`engine/vars.py`), assertion engine
+  with JSONPath body rules (`engine/assertion.py`), synchronous HTTP client wrapper
+  (`engine/http_client.py`), and PostgreSQL baseline + clone + insert pipeline
+  (`engine/db_executor.py`).
+- Custom action loader (`engine/action_loader.py`) that imports `actions/*.py` and
+  action runtime (`engine/action_runtime.py`) with fail-fast / best-effort hook
+  policies at four timings.
+- Runner (`engine/runner.py`) iterating Feature → Sheet → Case with all 4 action
+  hooks, depends_on gating, evidence directory provisioning, and JSON `RunReport`
+  output (`engine/report_writer.py`).
+- Swagger fetcher + parser ($ref expansion) + endpoint-level diff
+  (`swagger/{fetcher,parser,diff}.py`).
+- FastAPI server (`api/server.py`) with `/api/features`, `/api/swagger`, `/api/runs`
+  routes and optional static UI mount from `web_dist/`.
+- React + Vite frontend in `web/` covering Features list/edit, Swagger endpoints,
+  Run history, Run detail.
+- Workspace initializer (`engine/workspace_init.py`) and read-only doctor
+  (`engine/doctor.py`) with six checks.
+- CI (`.github/workflows/ci.yml`) and tag-driven release pipeline
+  (`.github/workflows/release.yml`) plus `scripts/bump_version.py`.
+- 68 unit tests covering models, YAML I/O, variable substitution, assertions,
+  action runtime, runner, Swagger parsing/diff, workspace init, doctor, FastAPI
+  feature routes, and `bump_version`.

marionette_test-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luvMagi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marionette_test-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: marionette-test
+Version: 0.1.0
+Summary: Automated API testing tool for Spring projects, with custom action hooks and Essay-compatible evidence layout
+Project-URL: Homepage, https://pypi.org/project/marionette-test/
+Project-URL: Repository, https://github.com/luvmagi/marionette-test
+Project-URL: Changelog, https://github.com/luvmagi/marionette-test/blob/main/CHANGELOG.md
+Author-email: luvmagi <luvmagi@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonpath-ng>=1.6
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: pydantic>=2.6
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.27
+Provides-Extra: dev
+Requires-Dist: hatch>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# marionette-test
+
+Automated API testing tool for Spring projects, with custom action hooks and an
+Essay-compatible evidence layout.
+
+> Alpha — V1 backend-API surface is implemented and tested. See
+> `docs/marionette-test/` for the design specs and `docs/guides/` for user-facing
+> documentation.
+
+## Install
+
+```bash
+pip install marionette-test
+```
+
+## Quick start
+
+```bash
+cd <your-project>
+marionette-test init                  # scaffold workspace
+$EDITOR config/env.yml                # point at your backend + DB
+export DB_PASSWORD=... API_BEARER_TOKEN=...
+marionette-test doctor                # six read-only checks
+marionette-test run                   # execute every FeatureUnit
+marionette-test serve                 # FastAPI + UI on :8765
+```
+
+A complete walk-through is in [docs/guides/01-getting-started.md](docs/guides/01-getting-started.md).
+
+## User guides
+
+| Guide                                                                       | What it covers                                  |
+| --------------------------------------------------------------------------- | ----------------------------------------------- |
+| [01 — Getting Started](docs/guides/01-getting-started.md)                   | Install, scaffold, write & run your first test |
+| [02 — Writing FeatureUnits](docs/guides/02-feature-units.md)                | Full YAML schema reference                     |
+| [03 — Custom Actions](docs/guides/03-custom-actions.md)                     | `@action`, `Context`, 4 hook timings           |
+| [04 — Database Baseline](docs/guides/04-database-baseline.md)               | `pg_dump` / `pg_restore` / clone lifecycle     |
+| [05 — CLI Reference](docs/guides/05-cli-reference.md)                       | Every subcommand and flag                      |
+| [06 — Variables & Assertions](docs/guides/06-variables-and-assertions.md)   | `${...}` grammar, `expect.*` rule grammar      |
+
+## Develop locally
+
+This repo uses [uv](https://github.com/astral-sh/uv) for environment management.
+
+```bash
+uv sync                         # create .venv and install runtime + dev deps
+uv run marionette-test --version
+uv run pytest                   # full test suite
+uv run ruff check src/ tests/
+```
+
+Build a wheel locally:
+
+```bash
+uv run hatch build              # produces dist/*.whl + *.tar.gz
+```
+
+Build the React UI (output lands inside the Python package so the wheel ships
+it):
+
+```bash
+cd web
+npm install
+npm run build                   # → src/marionette/test/web_dist/
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

marionette_test-0.1.0/README.md

@@ -0,0 +1,69 @@
+# marionette-test
+
+Automated API testing tool for Spring projects, with custom action hooks and an
+Essay-compatible evidence layout.
+
+> Alpha — V1 backend-API surface is implemented and tested. See
+> `docs/marionette-test/` for the design specs and `docs/guides/` for user-facing
+> documentation.
+
+## Install
+
+```bash
+pip install marionette-test
+```
+
+## Quick start
+
+```bash
+cd <your-project>
+marionette-test init                  # scaffold workspace
+$EDITOR config/env.yml                # point at your backend + DB
+export DB_PASSWORD=... API_BEARER_TOKEN=...
+marionette-test doctor                # six read-only checks
+marionette-test run                   # execute every FeatureUnit
+marionette-test serve                 # FastAPI + UI on :8765
+```
+
+A complete walk-through is in [docs/guides/01-getting-started.md](docs/guides/01-getting-started.md).
+
+## User guides
+
+| Guide                                                                       | What it covers                                  |
+| --------------------------------------------------------------------------- | ----------------------------------------------- |
+| [01 — Getting Started](docs/guides/01-getting-started.md)                   | Install, scaffold, write & run your first test |
+| [02 — Writing FeatureUnits](docs/guides/02-feature-units.md)                | Full YAML schema reference                     |
+| [03 — Custom Actions](docs/guides/03-custom-actions.md)                     | `@action`, `Context`, 4 hook timings           |
+| [04 — Database Baseline](docs/guides/04-database-baseline.md)               | `pg_dump` / `pg_restore` / clone lifecycle     |
+| [05 — CLI Reference](docs/guides/05-cli-reference.md)                       | Every subcommand and flag                      |
+| [06 — Variables & Assertions](docs/guides/06-variables-and-assertions.md)   | `${...}` grammar, `expect.*` rule grammar      |
+
+## Develop locally
+
+This repo uses [uv](https://github.com/astral-sh/uv) for environment management.
+
+```bash
+uv sync                         # create .venv and install runtime + dev deps
+uv run marionette-test --version
+uv run pytest                   # full test suite
+uv run ruff check src/ tests/
+```
+
+Build a wheel locally:
+
+```bash
+uv run hatch build              # produces dist/*.whl + *.tar.gz
+```
+
+Build the React UI (output lands inside the Python package so the wheel ships
+it):
+
+```bash
+cd web
+npm install
+npm run build                   # → src/marionette/test/web_dist/
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

marionette_test-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "marionette-test"
+version = "0.1.0"
+description = "Automated API testing tool for Spring projects, with custom action hooks and Essay-compatible evidence layout"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "luvmagi", email = "luvmagi@outlook.com" },
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+    "httpx>=0.27",
+    "ruamel.yaml>=0.18",
+    "jsonschema>=4.21",
+    "jsonpath-ng>=1.6",
+    "psycopg2-binary>=2.9",
+    "pydantic>=2.6",
+    "typer>=0.12",
+    "rich>=13.7",
+    "questionary>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+    "hatch>=1.9",
+    "twine>=5.0",
+]
+
+[project.scripts]
+marionette-test = "marionette.test.cli:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/marionette-test/"
+Repository = "https://github.com/luvmagi/marionette-test"
+Changelog = "https://github.com/luvmagi/marionette-test/blob/main/CHANGELOG.md"
+
+# ---- hatchling build configuration ----
+
+[tool.hatch.build.targets.wheel]
+# Ship the whole `marionette` PEP 420 namespace; only the `test` subpackage exists for now.
+packages = ["src/marionette"]
+
+# Embed the Vite build output into the wheel. Re-enable from M5 onward, when web/dist exists.
+# [tool.hatch.build.targets.wheel.force-include]
+# "web/dist" = "marionette/test/web_dist"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/marionette",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+]
+
+# ---- tooling ----
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

marionette_test-0.1.0/src/marionette/test/__init__.py

@@ -0,0 +1,7 @@
+"""marionette.test — automated API testing toolkit.
+
+Public surface kept intentionally small at the package root; CLI lives in `marionette.test.cli`,
+custom action API lives in `marionette.test.action`.
+"""
+
+__version__ = "0.1.0"

marionette_test-0.1.0/src/marionette/test/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m marionette.test` to dispatch to the CLI."""
+
+from marionette.test.cli import main
+
+if __name__ == "__main__":
+    main()

marionette_test-0.1.0/src/marionette/test/action.py

@@ -0,0 +1,97 @@
+"""Public API for user-authored custom actions.
+
+Users put `.py` files under `<workspace>/actions/` and decorate functions with `@action`.
+At runtime `marionette.test.engine.action_loader` imports those modules, which causes
+`@action` to register each function in a module-level registry. The runner then dispatches
+by name on the four hook points (pre_feature / post_feature / pre / post).
+
+Actions are pure side-effect functions — return values are ignored. Outputs should be
+written under `ctx.evidence_dir` so the Essay module can pick them up.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+# --- registry ---------------------------------------------------------------------------------
+
+_REGISTRY: dict[str, Callable[..., None]] = {}
+
+
+def action(fn: Callable[..., None]) -> Callable[..., None]:
+    """Register *fn* in the global action registry.
+
+    The function is returned untouched so it can still be imported and called directly
+    (handy for unit tests of action logic).
+    """
+    name = fn.__name__
+    if name in _REGISTRY and _REGISTRY[name] is not fn:
+        raise ValueError(
+            f"action name conflict: '{name}' is already registered "
+            f"by {_REGISTRY[name].__module__}"
+        )
+    _REGISTRY[name] = fn
+    return fn
+
+
+def get_registry() -> dict[str, Callable[..., None]]:
+    """Return a *copy* of the current registry — engine uses this as a snapshot."""
+    return dict(_REGISTRY)
+
+
+def reset_registry() -> None:
+    """Drop every registered action. Used by the reload endpoint and tests."""
+    _REGISTRY.clear()
+
+
+# --- runtime context --------------------------------------------------------------------------
+
+
+@dataclass
+class RequestView:
+    """Read-only snapshot of the rendered HTTP request, exposed to actions."""
+
+    method: str = ""
+    url: str = ""
+    path: dict[str, Any] = field(default_factory=dict)
+    query: dict[str, Any] = field(default_factory=dict)
+    header: dict[str, str] = field(default_factory=dict)
+    body: Any = None
+
+
+@dataclass
+class ResponseView:
+    """Read-only snapshot of the HTTP response, exposed to `post_actions`."""
+
+    status: int = 0
+    header: dict[str, str] = field(default_factory=dict)
+    body: Any = None
+    elapsed_ms: float = 0.0
+
+
+@dataclass
+class Context:
+    """Runtime context passed as the first positional argument of every action.
+
+    Feature-level hooks (`pre_feature_actions` / `post_feature_actions`) see the feature-scoped
+    fields only; the per-case fields (`sheet`, `case_id`, `evidence_dir`, `request`, `response`)
+    stay at their defaults.
+    """
+
+    feature_id: str
+    workspace_dir: Path
+    vars: dict[str, Any]
+    db: Any = None  # psycopg2 connection (autocommit) to the cloned work DB
+
+    # Case-scoped — defaults make these safe to access in feature-level hooks too.
+    sheet: str = ""
+    sheet_name: str = ""
+    case_id: str = ""
+    evidence_dir: Optional[Path] = None
+    request: Optional[RequestView] = None
+    response: Optional[ResponseView] = None
+
+    logger: Any = None

marionette_test-0.1.0/src/marionette/test/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI routers consumed by the React UI."""

marionette_test-0.1.0/src/marionette/test/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API route modules."""