pyprodtest 0.1.0__tar.gz

pyprodtest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jaydan Cowell
+
+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.

pyprodtest-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: pyprodtest
+Version: 0.1.0
+Summary: Pytest plugin for production testing
+Author: Jaydan Cowell
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jaydanc/pyprodtest
+Project-URL: Documentation, https://github.com/jaydanc/pyprodtest#readme
+Project-URL: Issues, https://github.com/jaydanc/pyprodtest/issues
+Project-URL: Repository, https://github.com/jaydanc/pyprodtest.git
+Keywords: production-testing,pytest,test-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=3.1.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: pytest>=8.4.2
+Requires-Dist: reportlab>=5.0.1
+Dynamic: license-file
+
+# PyProdTest
+
+PyProdTest is an early-stage pytest plugin for running production tests. It adds
+test metadata, operator prompts, a live browser view, ordered test plans, and
+HTML, JSON, CSV, and PDF reports.
+
+See the [architecture notes](doc/design.md) for the current design and known
+diagram gaps. The earlier prototype is available on the
+[`prototype` branch](https://github.com/jaydanc/pyprodtest/tree/prototype).
+
+## Add to a uv project
+
+From an existing Python 3.13+ uv project, add the published package:
+
+```powershell
+uv add pyprodtest
+uv run pytest
+```
+
+pytest discovers the installed plugin through its `pytest11` entry point, so no
+extra plugin flag is needed. Until the first PyPI release, add a checkout
+directly instead:
+
+```powershell
+uv add "pyprodtest @ git+https://github.com/jaydanc/pyprodtest.git"
+```
+
+The live operator page opens automatically at `http://127.0.0.1:8765`. At the
+end of the run, PyProdTest writes timestamped HTML, JSON, CSV, and PDF reports.
+
+## Add production-test metadata
+
+Decorators are optional and may be combined:
+
+```python
+from pyprodtest import info, req, step
+
+
+@info("Status light", "Confirm the device is ready")
+@req("REQ-42")
+@step("Check that the status light is green")
+def test_status_light(input) -> None:
+    assert input("Is the status light green?", bool)
+```
+
+Use `input(prompt)` for text or `input(prompt, bool)` for a yes/no response.
+The live UI handles prompts when enabled; otherwise PyProdTest uses the
+console.
+
+## Configure a run
+
+Create `pyprodtest.yaml` in the pytest project root:
+
+```yaml
+name: Device acceptance
+
+ui:
+  enabled: true
+  host: 127.0.0.1
+  port: 8765
+
+reports:
+  output: reports/device-acceptance
+  html: true
+  json: true
+  csv: false
+  pdf: true
+
+tests:
+  - test/integration/serial_test.py
+  - test/integration/status_light_test.py
+```
+
+`tests` accepts file paths and pytest node IDs. Only matching tests run, in the
+listed order; an unmatched entry is an error. Use
+`uv run pytest --collect-only -q` to inspect node IDs.
+
+The extensionless `reports.output` value receives a session timestamp and each
+enabled report extension. Set `ui.port` to `0` to choose a free port, or set
+`ui.enabled` to `false` for console-only operation.
+
+## Adjust reporting from a test
+
+The session-scoped `report` fixture can change the destination or disable all
+reports for the current run:
+
+```python
+def test_identify_device(input, report) -> None:
+    serial = input("Device serial number")
+    report.path = f"reports/{serial}"
+    report.name = "acceptance"
+    report.enabled = True
+```
+
+The final fixture values are used when the session ends. Set
+`report.enabled = False` to suppress report generation; the YAML format toggles
+still select which formats are enabled.
+
+PyProdTest also streams log messages at `INFO` and above. pytest's
+`--log-cli-level=LEVEL` option overrides that default.
+
+## Development
+
+Clone the repository and use its locked `uv` environment:
+
+```powershell
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run pytest -p pyprodtest
+```
+
+To test a local checkout from another uv project, use
+`uv add --editable ../pyprodtest`. Maintainers can create the source and wheel
+distributions with `uv build --no-sources`; publishing requires a configured
+PyPI project and `uv publish` credentials.

pyprodtest-0.1.0/README.md

@@ -0,0 +1,116 @@
+# PyProdTest
+
+PyProdTest is an early-stage pytest plugin for running production tests. It adds
+test metadata, operator prompts, a live browser view, ordered test plans, and
+HTML, JSON, CSV, and PDF reports.
+
+See the [architecture notes](doc/design.md) for the current design and known
+diagram gaps. The earlier prototype is available on the
+[`prototype` branch](https://github.com/jaydanc/pyprodtest/tree/prototype).
+
+## Add to a uv project
+
+From an existing Python 3.13+ uv project, add the published package:
+
+```powershell
+uv add pyprodtest
+uv run pytest
+```
+
+pytest discovers the installed plugin through its `pytest11` entry point, so no
+extra plugin flag is needed. Until the first PyPI release, add a checkout
+directly instead:
+
+```powershell
+uv add "pyprodtest @ git+https://github.com/jaydanc/pyprodtest.git"
+```
+
+The live operator page opens automatically at `http://127.0.0.1:8765`. At the
+end of the run, PyProdTest writes timestamped HTML, JSON, CSV, and PDF reports.
+
+## Add production-test metadata
+
+Decorators are optional and may be combined:
+
+```python
+from pyprodtest import info, req, step
+
+
+@info("Status light", "Confirm the device is ready")
+@req("REQ-42")
+@step("Check that the status light is green")
+def test_status_light(input) -> None:
+    assert input("Is the status light green?", bool)
+```
+
+Use `input(prompt)` for text or `input(prompt, bool)` for a yes/no response.
+The live UI handles prompts when enabled; otherwise PyProdTest uses the
+console.
+
+## Configure a run
+
+Create `pyprodtest.yaml` in the pytest project root:
+
+```yaml
+name: Device acceptance
+
+ui:
+  enabled: true
+  host: 127.0.0.1
+  port: 8765
+
+reports:
+  output: reports/device-acceptance
+  html: true
+  json: true
+  csv: false
+  pdf: true
+
+tests:
+  - test/integration/serial_test.py
+  - test/integration/status_light_test.py
+```
+
+`tests` accepts file paths and pytest node IDs. Only matching tests run, in the
+listed order; an unmatched entry is an error. Use
+`uv run pytest --collect-only -q` to inspect node IDs.
+
+The extensionless `reports.output` value receives a session timestamp and each
+enabled report extension. Set `ui.port` to `0` to choose a free port, or set
+`ui.enabled` to `false` for console-only operation.
+
+## Adjust reporting from a test
+
+The session-scoped `report` fixture can change the destination or disable all
+reports for the current run:
+
+```python
+def test_identify_device(input, report) -> None:
+    serial = input("Device serial number")
+    report.path = f"reports/{serial}"
+    report.name = "acceptance"
+    report.enabled = True
+```
+
+The final fixture values are used when the session ends. Set
+`report.enabled = False` to suppress report generation; the YAML format toggles
+still select which formats are enabled.
+
+PyProdTest also streams log messages at `INFO` and above. pytest's
+`--log-cli-level=LEVEL` option overrides that default.
+
+## Development
+
+Clone the repository and use its locked `uv` environment:
+
+```powershell
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run pytest -p pyprodtest
+```
+
+To test a local checkout from another uv project, use
+`uv add --editable ../pyprodtest`. Maintainers can create the source and wheel
+distributions with `uv build --no-sources`; publishing requires a configured
+PyPI project and `uv publish` credentials.

pyprodtest-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "pyprodtest"
+version = "0.1.0"
+description = "Pytest plugin for production testing"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Jaydan Cowell" },
+]
+keywords = ["production-testing", "pytest", "test-automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "flask>=3.1.2",
+    "jinja2>=3.1.6",
+    "pyyaml>=6.0.2",
+    "pytest>=8.4.2",
+    "reportlab>=5.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/jaydanc/pyprodtest"
+Documentation = "https://github.com/jaydanc/pyprodtest#readme"
+Issues = "https://github.com/jaydanc/pyprodtest/issues"
+Repository = "https://github.com/jaydanc/pyprodtest.git"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.12.12",
+]
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.setuptools.package-data]
+"_pyprodtest.observers.html_report" = ["templates/*.html"]
+"_pyprodtest.web_assets" = ["*.css"]
+"_pyprodtest.observers.web_ui" = ["templates/*.html", "static/*.js"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pyprodtest*", "_pyprodtest*"]
+
+[project.entry-points.pytest11]
+pyprodtest = "_pyprodtest.hooks"

pyprodtest-0.1.0/setup.cfg

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

pyprodtest-0.1.0/src/_pyprodtest/config.py

@@ -0,0 +1,163 @@
+"""Load and validate project configuration from pyprodtest.yaml."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pytest
+import yaml
+
+DEFAULT_UI_NAME = "Production test execution"
+
+
+@dataclass(frozen=True)
+class UiConfig:
+    """Configuration for the live operator UI."""
+
+    enabled: bool = True
+    host: str = "127.0.0.1"
+    port: int = 8765
+
+
+@dataclass(frozen=True)
+class ReportsConfig:
+    """Configuration shared by the final report observers."""
+
+    output: str = "pyprodtest-report"
+    html: bool = True
+    json: bool = True
+    csv: bool = True
+    pdf: bool = True
+
+
+@dataclass(frozen=True)
+class PyProdTestConfig:
+    """Validated settings for one PyProdTest session."""
+
+    name: str = DEFAULT_UI_NAME
+    tests: list[str] | None = None
+    ui: UiConfig = field(default_factory=UiConfig)
+    reports: ReportsConfig = field(default_factory=ReportsConfig)
+
+
+def load_config(rootpath: Path) -> PyProdTestConfig:
+    """Load pyprodtest.yaml from the pytest project root."""
+    config_path = rootpath / "pyprodtest.yaml"
+    if not config_path.exists():
+        return PyProdTestConfig()
+
+    try:
+        document = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as error:
+        raise pytest.UsageError(
+            f"Invalid PyProdTest configuration {config_path}: {error}"
+        ) from error
+    if not isinstance(document, dict):
+        raise pytest.UsageError(
+            f"PyProdTest configuration {config_path} must contain a YAML mapping"
+        )
+
+    name = _non_empty_string(document.get("name", DEFAULT_UI_NAME), "name")
+    tests = _load_tests(document.get("tests"))
+    ui = _mapping(document.get("ui", {}), "ui")
+    reports = _mapping(document.get("reports", {}), "reports")
+    return PyProdTestConfig(
+        name=name,
+        tests=tests,
+        ui=UiConfig(
+            enabled=_boolean(ui.get("enabled", True), "ui.enabled"),
+            host=_non_empty_string(ui.get("host", "127.0.0.1"), "ui.host"),
+            port=_port(ui.get("port", 8765)),
+        ),
+        reports=ReportsConfig(
+            output=_non_empty_string(
+                reports.get("output", "pyprodtest-report"), "reports.output"
+            ),
+            html=_boolean(reports.get("html", True), "reports.html"),
+            json=_boolean(reports.get("json", True), "reports.json"),
+            csv=_boolean(reports.get("csv", True), "reports.csv"),
+            pdf=_boolean(reports.get("pdf", True), "reports.pdf"),
+        ),
+    )
+
+
+def apply_test_plan(
+    config: pytest.Config, items: list[pytest.Item], plan: list[str] | None
+) -> None:
+    """Select and order collected items using the configured test plan."""
+    if plan is None:
+        return
+
+    ranked = [(item, _selection_index(item.nodeid, plan)) for item in items]
+    matched = {plan[index] for _, index in ranked if index < len(plan)}
+    unmatched = [selection for selection in plan if selection not in matched]
+    if unmatched:
+        formatted = "\n  - ".join(unmatched)
+        raise pytest.UsageError(
+            f"PyProdTest plan entries matched no tests:\n  - {formatted}"
+        )
+
+    ranked.sort(key=lambda entry: entry[1])
+    selected = [item for item, index in ranked if index < len(plan)]
+    deselected = [item for item, index in ranked if index == len(plan)]
+    items[:] = selected
+    if deselected:
+        config.hook.pytest_deselected(items=deselected)
+
+
+def _load_tests(value: object) -> list[str] | None:
+    if value is None:
+        return None
+    if not isinstance(value, list) or not all(
+        isinstance(selection, str) and selection for selection in value
+    ):
+        raise pytest.UsageError(
+            "PyProdTest configuration 'tests' must be a list of paths or node IDs"
+        )
+    return [selection.replace("\\", "/") for selection in value]
+
+
+def _mapping(value: object, setting: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise pytest.UsageError(
+            f"PyProdTest configuration '{setting}' must be a mapping"
+        )
+    return value
+
+
+def _boolean(value: object, setting: str) -> bool:
+    if not isinstance(value, bool):
+        raise pytest.UsageError(
+            f"PyProdTest configuration '{setting}' must be true or false"
+        )
+    return value
+
+
+def _non_empty_string(value: object, setting: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise pytest.UsageError(
+            f"PyProdTest configuration '{setting}' must be a non-empty string"
+        )
+    return value.strip()
+
+
+def _port(value: object) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 0 <= value <= 65535:
+        raise pytest.UsageError(
+            "PyProdTest configuration 'ui.port' must be an integer from 0 to 65535"
+        )
+    return value
+
+
+def _selection_index(nodeid: str, plan: list[str]) -> int:
+    return next(
+        (index for index, selection in enumerate(plan) if _matches(nodeid, selection)),
+        len(plan),
+    )
+
+
+def _matches(nodeid: str, selection: str) -> bool:
+    return (
+        nodeid == selection
+        or nodeid.startswith(f"{selection}::")
+        or nodeid.startswith(f"{selection}[")
+    )

pyprodtest-0.1.0/src/_pyprodtest/decorator.py

@@ -0,0 +1,47 @@
+"""
+Additional decorators for PyProdTest tests.
+These decorators add metadata to test functions and are optional.
+"""
+
+
+def info(name, desc):
+    """
+    Adds name and description metadata to a test function.
+    """
+
+    def wrapper(fn):
+        fn.test_meta = getattr(fn, "test_meta", {})
+        fn.test_meta["name"] = name
+        fn.test_meta["desc"] = desc
+        return fn
+
+    return wrapper
+
+
+def req(*reqs):
+    """
+    Adds requirement IDs to the metadata.
+    """
+
+    def wrapper(fn):
+        fn.test_meta = getattr(fn, "test_meta", {})
+        fn.test_meta["requirements"] = list(reqs)
+        return fn
+
+    return wrapper
+
+
+def step(*steps):
+    """
+    Adds step metadata to the metadata
+    """
+
+    def wrapper(fn):
+        fn.test_meta = getattr(fn, "test_meta", {})
+        existing_steps = fn.test_meta.get("steps", [])
+        # Decorators are applied from the bottom upwards, so prepend each
+        # group to retain the order in which stacked decorators are written.
+        fn.test_meta["steps"] = [*steps, *existing_steps]
+        return fn
+
+    return wrapper