pytest-verifies 1.1.0__tar.gz

pytest_verifies-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/**'
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint-and-typecheck:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Synchronise environment
+        run: uv sync --all-groups
+
+      - name: Run Ruff linter
+        run: uv run ruff check .
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Run Mypy type checker
+        run: uv run mypy src
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Synchronise environment
+        run: uv sync --all-groups --python ${{ matrix.python-version }}
+
+      - name: Run test suite with pytest
+        run: uv run pytest -v
+
+  docs-check:
+    name: Verify Documentation Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Synchronise documentation dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation in strict mode
+        run: uv run --group docs mkdocs build --strict
+
+  package-check:
+    name: Verify Package Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build distribution artefacts
+        run: uv build

pytest_verifies-1.1.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy-docs:
+    name: Build & Deploy Documentation
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Synchronise documentation dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run --group docs mkdocs build
+
+      - name: Set up GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artefact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

pytest_verifies-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pytest-verifies
+    permissions:
+      id-token: write  # Mandatory for PyPA Trusted Publishing (OIDC)
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build distribution packages
+        run: uv build
+
+      - name: Publish package distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pytest_verifies-1.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test and lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.verifies/
+*.jsonl
+
+# Documentation & coverage builds
+site/
+.coverage
+htmlcov/

pytest_verifies-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# See https://pre-commit.com for more information
+# Uses pre-commit-uv under the hood for accelerated environment creation via uv
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pytest>=7.0
+          - pyyaml>=6.0
+          - types-PyYAML

pytest_verifies-1.1.0/.python-version

@@ -0,0 +1 @@
+3.12

pytest_verifies-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dale Collison
+
+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.

pytest_verifies-1.1.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.5
+Name: pytest-verifies
+Version: 1.1.0
+Summary: Enterprise requirements traceability plugin for pytest
+Author-email: Dale Collison <dale.a.collison@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7.0
+Description-Content-Type: text/markdown
+
+# pytest-verifies
+
+[![CI](https://img.shields.io/badge/pytest--verifies-v1.0.0-blue.svg)](https://github.com/your-org/pytest-verifies)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Standards](https://img.shields.io/badge/compliance-ISO%2026262%20%7C%20IEC%2062304%20%7C%20DO--178C%20%7C%20SOC2-orange.svg)](#standards-compliance)
+
+**Enterprise Requirements Traceability Plugin for Pytest.**
+
+`pytest-verifies` seamlessly links automated test suites to formal engineering requirements (such as ISO 26262, IEC 62304, DO-178C, and SOC2) and produces audit-ready Requirements Traceability Matrix (RTM) artefacts.
+
+---
+
+## 1. Core Philosophy & Key Features
+
+1. **Standard Pytest Assertions Only:**
+   No custom assertion wrappers. Use native Python `assert` statements inside `with verifies(...)` or on functions decorated with `@verifies(...)`. Pytest's AST assertion rewriting and rich diff diagnostics are 100% preserved.
+2. **Unified API:**
+   A single callable, `verifies`, functions interchangeably as a function/class decorator, context manager, and parametrised mark (`pytest.param(..., marks=verifies(...))`).
+3. **Soft Assertions & Objective Evidence:**
+   Support for non-fatal assertions (`soft=True` or `--verifies-soft`) enables tests to evaluate multiple requirements sequentially before reporting consolidated failures. Dynamically attach objective runtime evidence (`ctx.attach("telemetry", value)` or `ctx.record_evidence(dict)`).
+4. **`pytest-xdist` Concurrency Safe:**
+   Workers never write directly to shared report files or depend on inter-process locks. Verification records are serialised onto `report.user_properties` and transmitted to the controller node.
+5. **Multi-Run Shard Consolidation:**
+   Modelled after `coverage.py`. Distinct test invocations across disparate execution environments or CI stages (e.g. `unit`, `integration`, `system`) write atomic `.jsonl` shards. The standalone `pytest-verifies combine` CLI merges shards against baseline requirement manifests.
+6. **Multi-Format Artefact Generation:**
+   Generates structured **JSON**, tabular **CSV**, GitHub/GitLab step summary **Markdown**, and interactive single-file **HTML5** reports with zero external runtime JavaScript or CSS dependencies.
+7. **Strict Quality Gates:**
+   Enforce requirement coverage thresholds (`--verifies-fail-under`), disallow orphaned requirement IDs (`--verifies-disallow-orphans`), and fail pipelines when known defects or unverified requirements are detected.
+
+---
+
+## 2. Installation
+
+Install using `uv` (recommended):
+
+```bash
+uv add pytest-verifies
+```
+
+Or using standard Python package managers:
+
+```bash
+pip install pytest-verifies
+```
+
+---
+
+## 3. Quick Start & Python API
+
+### 3.1 Decorator Usage
+
+Decorate test functions or classes to associate them with one or more requirements:
+
+```python
+from pytest_verifies import verifies
+
+
+@verifies("REQ-DOG-001", "REQ-DOG-002", description="Dogs must be friendly and able to bark")
+def test_dog_attributes():
+    dog = {"name": "Buster", "species": "Canis familiaris", "barks": True}
+    assert dog["barks"] is True
+```
+
+### 3.2 Single-Line Context Manager
+
+Verify fine-grained inline statements while preserving full assertion diffs:
+
+```python
+from pytest_verifies import verifies
+
+
+def test_cat_purring():
+    cat = {"name": "Whiskers", "purring": True}
+    with verifies("REQ-CAT-001"):
+        assert cat["purring"] is True
+```
+
+### 3.3 Soft Assertions & Objective Evidence
+
+Evaluate multiple requirements within a single test execution without early termination on the first failure:
+
+```python
+from pytest_verifies import verifies
+
+
+def test_dog_health_and_energy():
+    dog = {"name": "Buster", "happy": True, "tail_wags_per_min": 120}
+
+    # Block 1: Soft assertion with static objective evidence
+    with verifies(
+        "REQ-DOG-002",
+        description="Dogs must wag their tails when happy",
+        soft=True,
+        evidence={"dog_name": dog["name"], "happy": dog["happy"]},
+    ):
+        assert dog["happy"] is True
+
+    # Block 2: Execution continues even if Block 1 fails
+    with verifies("REQ-DOG-003", soft=True) as ctx:
+        ctx.attach("tail_wags_per_min", dog["tail_wags_per_min"])
+        ctx.record_evidence({"breed": "Golden Retriever"})
+        assert dog["tail_wags_per_min"] > 60
+```
+
+### 3.4 Parametrised Tests
+
+Attach requirement tags to specific test parameters:
+
+```python
+import pytest
+from pytest_verifies import verifies
+
+
+@pytest.mark.parametrize(
+    "animal,sound",
+    [
+        pytest.param("dog", "woof", marks=verifies("REQ-DOG-001")),
+        pytest.param("cat", "meow", marks=verifies("REQ-CAT-001")),
+        pytest.param("puppy", "yip", marks=verifies("REQ-DOG-001")),
+    ],
+)
+def test_pet_sounds(animal, sound):
+    pet_sounds = {"dog": "woof", "cat": "meow", "puppy": "yip"}
+    assert pet_sounds[animal] == sound
+```
+
+### 3.5 Test Procedure Steps & Action Steps
+
+Test protocols often require tracking discrete step IDs (`STEP-01`, `1.1`), including **Action Steps** (preparing state) and **Verification Steps** (checking requirements):
+
+```python
+from pytest_verifies import step, verifies
+
+
+def test_puppy_training_routine():
+    # Action step: Prepare treat and call puppy
+    with step("STEP-01", description="Fill treat pouch and call puppy"):
+        puppy = {"name": "Buster", "tricks": []}
+
+    # Verification step: Directly validates REQ-DOG-004
+    with step("STEP-02", description="Verify puppy sits on command", verifies="REQ-DOG-004"):
+        puppy["tricks"].append("sit")
+        assert "sit" in puppy["tricks"]
+
+    # Verification step with verifies(..., step=...)
+    with verifies("REQ-DOG-002", step="STEP-03", description="Verify puppy wags tail after treat"):
+        tail_wagging = True
+        assert tail_wagging is True
+```
+
+---
+
+## 4. Pytest Command-Line & Configuration Options
+
+| Option | Ini Configuration | Description |
+| :--- | :--- | :--- |
+| `--req="PATTERN"` | — | Comma-separated requirement IDs or glob patterns to filter tests (e.g. `--req="REQ-DOG-*,REQ-CAT-001"`). |
+| `--verifies-out=DIR` | `verifies_out = DIR` | Directory to output `.jsonl` execution shards. |
+| `--verifies-stage=NAME` | `verifies_stage = NAME` | Stage label for execution shard (default: `"default"`). |
+| `--verifies-baseline=PATH` | `verifies_baseline = PATH` | Path to baseline requirement manifest (`.json`, `.csv`, `.yaml`). |
+| `--verifies-soft` | `verifies_soft = true` | Enable soft verification mode globally across all `verifies` blocks. |
+| `--verifies-disallow-orphans`| — | Fail collection/session if tests reference IDs not present in baseline. |
+| `--verifies-fail-under=NUM` | — | Fail session if verified requirement coverage % is below threshold (0–100). |
+| `--verifies-json=PATH` | — | Direct output file for structured JSON RTM report. |
+| `--verifies-csv=PATH` | — | Direct output file for tabular CSV RTM report. |
+| `--verifies-md=PATH` | — | Direct output file for Markdown summary report. |
+| `--verifies-html=PATH` | — | Direct output file for interactive single-file HTML5 report. |
+
+---
+
+## 5. Baseline Requirement Manifests
+
+Baseline manifests declare formal specifications against which automated tests are verified. Baseline requirements need only an `id` and a requirement statement `text` (or `description`).
+
+### JSON Manifest (`requirements.json`)
+```json
+{
+  "requirements": [
+    {
+      "id": "REQ-DOG-001",
+      "text": "Dogs must be able to bark"
+    },
+    {
+      "id": "REQ-CAT-001",
+      "text": "Cats must be able to purr when content"
+    }
+  ]
+}
+```
+
+### CSV Manifest (`requirements.csv`)
+```csv
+id,text
+REQ-DOG-001,Dogs must be able to bark
+REQ-CAT-001,Cats must be able to purr when content
+```
+
+### YAML Manifest (`requirements.yaml`)
+```yaml
+requirements:
+  - id: REQ-DOG-001
+    text: Dogs must be able to bark
+  - id: REQ-CAT-001
+    text: Cats must be able to purr when content
+```
+
+---
+
+## 6. Multi-Run Shard Consolidation Workflow
+
+In distributed CI pipelines, different test tiers (unit, integration, end-to-end) run in isolated containers. `pytest-verifies` enables merging these shards into a single consolidated matrix:
+
+### Step 1: Run Stage Test Suites
+```bash
+# Unit test tier
+uv run pytest tests/unit --verifies-out=.verifies --verifies-stage=unit
+
+# Integration test tier
+uv run pytest tests/integration --verifies-out=.verifies --verifies-stage=integration
+
+# End-to-end / System test tier
+uv run pytest tests/system --verifies-out=.verifies --verifies-stage=system
+```
+
+### Step 2: Combine Shards via CLI
+```bash
+uv run pytest-verifies combine .verifies/ \
+  --baseline requirements.json \
+  --disallow-orphans \
+  --fail-under 100.0 \
+  --json rtm.json \
+  --csv rtm.csv \
+  --md rtm.md \
+  --html rtm.html
+```
+
+### Quality Gate Exit Codes
+- **`0`**: Success. All quality gates met (100% of tested requirements verified, coverage threshold met, no orphaned IDs).
+- **`1`**: Quality gate failure. One or more requirements failed, orphaned IDs were detected, or verified requirement coverage is below `--fail-under`.
+
+---
+
+## 7. Reporting Artefacts
+
+### Interactive HTML5 Report
+Self-contained, responsive, single-file HTML5 document with zero external network dependencies:
+- **Metric Cards:** Total Requirements, Verified %, Failed %, Unverified %, Orphan Count.
+- **Dynamic Filtering:** Instant filtering by status (`All`, `Verified`, `Failed`, `Unverified`, `Orphans`).
+- **Live Search:** Fast search by Requirement ID, title, test nodeid, or file location.
+- **Diagnostic Expansion:** Interactive `<details>` sections displaying execution trace, attached objective evidence, and failure tracebacks.
+
+### GitHub / GitLab Markdown Summary
+Designed directly for `$GITHUB_STEP_SUMMARY` and merge request comments:
+- Summary Scorecard Table with clean status indicators (`VERIFIED`, `FAILED`, `PARTIAL`, `UNVERIFIED`, `[ORPHAN]`).
+- Requirements Traceability Table detailing stage coverage and verification tests.
+- Collapsible diagnostics with assertion tracebacks and formatted JSON evidence.
+
+### Tabular CSV Export
+Standardised format for enterprise PLM / ALM tools (e.g. Jira, Jama, Polarion):
+```csv
+req_id,title,status,in_baseline,stages,verified_by_tests,evidence,failure_messages
+```
+
+---
+
+## 8. Standards Compliance
+
+| Standard | Applicable Clauses | How `pytest-verifies` Supports Compliance |
+| :--- | :--- | :--- |
+| **ISO 26262** | Part 6, Section 9 & 10 | Provides bidirectional requirements-to-test traceability and verification evidence for ASIL A–D. |
+| **IEC 62304** | Section 5.7 & 5.8 | Establishes automated software verification records and RTM reports for Class A–C medical software. |
+| **DO-178C** | Section 6.4.4 | Demonstrates verification of software requirements and records objective test execution results. |
+| **SOC2 / ISO 27001** | CC7.1, CC7.4 | Auditable proof that automated security controls and regression tests verify baseline control specifications. |
+
+---
+
+## 9. Licence
+
+Distributed under the terms of the **MIT** licence.