pytest-allure-host 0.1.1__py3-none-any.whl

pytest_allure_host/utils.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def default_run_id() -> str:
+    from datetime import datetime
+
+    return datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+
+
+def build_s3_keys(
+    prefix: str,
+    project: str,
+    branch: str,
+    run_id: str,
+) -> dict[str, str]:
+    base = f"{prefix.rstrip('/')}/{project}/{branch}"
+    return {"run": f"{base}/{run_id}/", "latest": f"{base}/latest/"}
+
+
+def branch_root(prefix: str, project: str, branch: str) -> str:
+    return f"{prefix.rstrip('/')}/{project}/{branch}"
+
+
+def cache_control_for_key(key: str) -> str:
+    if key.endswith("index.html"):
+        return "no-cache"
+    # widgets optional no-cache could be configurable later
+    if "/widgets/" in key:
+        return "no-cache"
+    return "public, max-age=31536000, immutable"
+
+
+def guess_content_type(path: Path) -> str | None:
+    ctype, _ = mimetypes.guess_type(str(path))
+    # Common overrides if needed later
+    return ctype or None
+
+
+@dataclass
+class PublishConfig:
+    bucket: str
+    prefix: str
+    project: str
+    branch: str
+    run_id: str
+    cloudfront_domain: str | None = None
+    ttl_days: int | None = None
+    max_keep_runs: int | None = None
+    s3_endpoint: str | None = None  # custom S3 endpoint (e.g. LocalStack)
+    # optional link to change context (e.g. Jira ticket / work item)
+    context_url: str | None = None
+
+    @property
+    def s3_run_prefix(self) -> str:
+        keys = build_s3_keys(
+            self.prefix,
+            self.project,
+            self.branch,
+            self.run_id,
+        )
+        return keys["run"]
+
+    @property
+    def s3_latest_prefix(self) -> str:
+        keys = build_s3_keys(
+            self.prefix,
+            self.project,
+            self.branch,
+            self.run_id,
+        )
+        return keys["latest"]
+
+    def url_run(self) -> str | None:
+        if not self.cloudfront_domain:
+            return None
+        base = (
+            f"{self.cloudfront_domain.rstrip('/')}/{self.prefix}/"
+            f"{self.project}/{self.branch}/{self.run_id}/"
+        )
+        return base
+
+    def url_latest(self) -> str | None:
+        if not self.cloudfront_domain:
+            return None
+        base = (
+            f"{self.cloudfront_domain.rstrip('/')}/{self.prefix}/"
+            f"{self.project}/{self.branch}/latest/"
+        )
+        return base
+
+
+def compute_dir_size(path: Path) -> int:
+    total = 0
+    for p in path.rglob("*"):
+        if p.is_file():
+            total += p.stat().st_size
+    return total
+
+
+def merge_manifest(existing: dict | None, new_entry: dict) -> dict:
+    base = existing or {
+        "schema": 1,
+        "project": new_entry.get("project"),
+        "branch": new_entry.get("branch"),
+        "updated": 0,
+        "runs": [],
+    }
+    runs = [r for r in base.get("runs", []) if r.get("run_id") != new_entry["run_id"]]
+    runs.append(new_entry)
+    runs.sort(key=lambda r: r.get("time", 0), reverse=True)
+    base["runs"] = runs
+    from time import time
+
+    base["updated"] = int(time())
+    return base

pytest_allure_host-0.1.1.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: pytest-allure-host
+Version: 0.1.1
+Summary: Publish Allure static reports to private S3 behind CloudFront with history preservation
+License-Expression: MIT
+License-File: LICENSE
+Keywords: allure,pytest,aws,s3,cloudfront,reporting
+Author: Allure Hosting Maintainers
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Pytest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Requires-Dist: PyYAML (>=6,<7)
+Requires-Dist: boto3 (>=1.28,<2.0)
+Project-URL: Bug Tracker, https://github.com/darrenrabbs/allurehosting/issues
+Project-URL: Changelog, https://github.com/darrenrabbs/allurehosting/releases
+Project-URL: Documentation, https://github.com/darrenrabbs/allurehosting#readme
+Project-URL: Homepage, https://github.com/darrenrabbs/allurehosting
+Project-URL: Repository, https://github.com/darrenrabbs/allurehosting
+Description-Content-Type: text/markdown
+
+# pytest-allure-host
+
+![CI](https://github.com/darrenrabbs/allurehosting/actions/workflows/ci.yml/badge.svg)
+![CodeQL](https://github.com/darrenrabbs/allurehosting/actions/workflows/codeql.yml/badge.svg)
+![PyPI - Version](https://img.shields.io/pypi/v/pytest-allure-host.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+
+Publish Allure static reports to private S3 behind CloudFront with history preservation and SPA-friendly routing.
+
+See `docs/architecture.md` and `.github/copilot-instructions.md` for architecture and design constraints.
+
+## Features
+
+- Generate Allure static report from `allure-results`
+- Preserve history by pulling `latest/history` before generation
+- Upload to S3 under `<project>/<branch>/<run_id>/` and update `<project>/<branch>/latest/`
+- Two-phase latest update: upload to `latest_tmp/`, swap into `latest/`, write `LATEST_READY` marker
+- Optional retention: keep only N newest runs (`--max-keep-runs`)
+- Correct caching headers: `index.html` and `widgets/` → `no-cache`; assets → immutable
+- Optional TTL tagging on objects (`--ttl-days`) for S3 lifecycle policies
+- Optional summary JSON output for CI
+- Best-effort manifest at `runs/index.json` with new run metadata
+- Lightweight pointer file `latest.json` (branch root)
+- Human-friendly HTML index at `runs/index.html` for navigating past runs
+  - Columns: Run ID, raw epoch, UTC Time (human readable), Size (pretty units), P/F/B (passed/failed/broken counts), links to the immutable run and the moving latest
+  - Newest run highlighted with a star (★) and soft background
+
+## Requirements
+
+- Python 3.9+
+- AWS credentials with S3 access to the target bucket
+- Allure commandline available on PATH (e.g., via Allure CLI or allure-pytest)
+
+## S3 layout and caching
+
+- Keys:
+  - `s3://<bucket>/<prefix>/<project>/<branch>/<run_id>/...`
+  - `s3://<bucket>/<prefix>/<project>/<branch>/latest/...`
+  - `s3://<bucket>/<prefix>/<project>/<branch>/runs/index.json` (manifest)
+  - `s3://<bucket>/<prefix>/<project>/<branch>/runs/index.html` (HTML index)
+  - `s3://<bucket>/<prefix>/<project>/<branch>/latest.json` (pointer)
+- Two-phase swap writes a `LATEST_READY` marker file under `latest/` when ready.
+- Cache-Control:
+  - `index.html`: `no-cache`
+  - files under `widgets/`: `no-cache`
+  - everything else: `public, max-age=31536000, immutable`
+
+## CLI usage
+
+Install locally for development:
+
+```bash
+pip install -e .[dev]
+```
+
+Run the publisher after tests generate `allure-results`:
+
+```bash
+publish-allure \
+  --bucket your-bucket \
+  --prefix reports \
+  --project demo \
+  --branch main \
+  --cloudfront https://reports.example.com \
+  --ttl-days 30 \
+  --max-keep-runs 10
+```
+
+Flags (CLI):
+
+- `--bucket` (required): S3 bucket name
+- `--prefix` (default: `reports`): Root prefix
+- `--project` (required): Project name
+- `--branch` (default: `$GIT_BRANCH` or `main`)
+- `--run-id` (default: `$ALLURE_RUN_ID` or `YYYYMMDD-HHMMSS`)
+- `--cloudfront` (optional; default: `$ALLURE_CLOUDFRONT`)
+- `--results` (default: `allure-results`): Input directory
+- `--report` (default: `allure-report`): Output directory
+- `--ttl-days` (optional): Add `ttl-days=<N>` object tag
+- `--max-keep-runs` (optional): Keep N newest run prefixes, delete older
+- `--summary-json <path>`: Write machine-readable summary
+- `--check`: Preflight validation (AWS access, allure, inputs)
+- `--dry-run`: Print planned prefixes and sample headers, no upload
+- `--s3-endpoint`: Custom S3 endpoint (e.g. `http://localhost:4566` for LocalStack)
+
+Environment fallbacks:
+
+- `GIT_BRANCH` → `--branch` default
+- `ALLURE_RUN_ID` → `--run-id` default
+- `ALLURE_CLOUDFRONT` → `--cloudfront` default
+- `ALLURE_S3_ENDPOINT` → `--s3-endpoint` default (LocalStack / custom S3)
+
+## Pytest plugin usage
+
+Run tests and publish during terminal summary:
+
+```bash
+pytest \
+  --allure-bucket your-bucket \
+  --allure-prefix reports \
+  --allure-project demo \
+  --allure-branch main \
+  --allure-cloudfront https://reports.example.com \
+  --allure-ttl-days 30 \
+  --allure-max-keep-runs 10
+```
+
+Flags (pytest):
+
+- `--allure-bucket` (required)
+- `--allure-prefix` (default: `reports`)
+- `--allure-project` (required)
+- `--allure-branch` (default: `$GIT_BRANCH` or `main`)
+- `--allure-run-id` (default: `$ALLURE_RUN_ID` or `YYYYMMDD-HHMMSS`)
+- `--allure-cloudfront` (optional; default: `$ALLURE_CLOUDFRONT`)
+- `--allure-ttl-days` (optional)
+- `--allure-max-keep-runs` (optional)
+- `--allure-summary-json <path>` (optional)
+- `--allure-check` / `--allure-dry-run` (optional)
+
+## Preflight and dry-run
+
+- `--check`/`--allure-check` verifies:
+  - S3 bucket reachability (HeadBucket/List)
+  - `allure-results` exists and is non-empty
+  - Allure CLI exists on PATH
+- `--dry-run`/`--allure-dry-run` prints planned prefixes and sample headers; no uploads occur.
+
+## Outputs
+
+- S3 prefixes: run and latest
+- Optional CDN URLs (if `--cloudfront` provided)
+- `runs/index.json` manifest updated with new run entry
+- `runs/index.html` HTML table of recent runs (newest first) with columns: Run ID, Epoch, UTC Time, Size, P/F/B, Run, Latest (newest row highlighted with ★)
+- `latest.json` pointer to current run (simple machine-readable metadata)
+- Optional `--summary-json` with sizes, file counts, and destination URLs
+- `latest/LATEST_READY` marker indicates the swap is complete
+
+## Security
+
+See `SECURITY.md` for how to report vulnerabilities. Never open a public issue containing sensitive details.
+
+## Badges / Status
+
+- CI: multi-version test matrix + lint/security
+- CodeQL: static code analysis
+
+## Contributing
+
+See `CONTRIBUTING.md` and follow the pre-commit hooks (`pre-commit install`).
+
+## Release
+
+Tagged versions (`vX.Y.Z`) are published to PyPI automatically via GitHub OIDC.
+
+## CI examples
+
+GitHub Actions (CLI):
+
+```yaml
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install .[dev]
+      - run: pytest -q
+      - name: Publish Allure
+        env:
+          AWS_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          GIT_BRANCH: ${{ github.ref_name }}
+        run: >-
+          publish-allure --bucket $BUCKET --prefix reports --project demo
+          --branch "$GIT_BRANCH" --cloudfront https://reports.example.com
+          --ttl-days 30 --max-keep-runs 10
+```
+
+Pytest-driven (plugin):
+
+```yaml
+- run: pytest -q \
+    --allure-bucket $BUCKET \
+    --allure-prefix reports \
+    --allure-project demo \
+    --allure-branch "$GIT_BRANCH" \
+    --allure-cloudfront https://reports.example.com \
+    --allure-ttl-days 30 \
+    --allure-max-keep-runs 10
+```
+
+## Troubleshooting
+
+- Missing Allure binary: ensure the Allure CLI is installed and on PATH.
+- Access denied: verify AWS credentials and bucket IAM for Put/Get/List/Delete.
+- SPA routing 403/404: configure CloudFront error mapping to `/index.html`.
+
+## Development
+
+- Install with Poetry: `poetry install`
+- Run tests: `poetry run pytest -q`
+- Lint (security quick): `poetry run bandit -r pytest_allure_host`
+- Unified lint helper (mirrors CI):
+  ```bash
+  scripts/lint.sh           # check mode (ruff lint+format check, bandit, pip-audit)
+  scripts/lint.sh --fix     # apply ruff fixes + format
+  scripts/lint.sh pre-commit  # also run pre-commit hooks on all files
+  ```
+
+## Quick local trial (macOS)
+
+This section walks you through a minimal end-to-end run locally.
+
+1. Prereqs
+
+- AWS credentials configured (via `AWS_PROFILE` or access keys); set `AWS_REGION`.
+- Allure CLI installed on PATH:
+  ```bash
+  brew install allure
+  ```
+- Python deps installed:
+  ```bash
+  poetry install
+  # or
+  pip install -e .[dev]
+  ```
+
+2. Generate Allure results
+
+- Create a tiny test (optional example):
+  ```bash
+  mkdir -p tests
+  cat > tests/test_sample.py <<'PY'
+  def test_ok():
+      assert True
+  PY
+  ```
+- Run pytest to emit results:
+  ```bash
+  poetry run pytest --alluredir=allure-results
+  ```
+
+3. Preflight and dry-run
+
+```bash
+poetry run publish-allure \
+  --bucket <bucket> \
+  --prefix reports \
+  --project demo \
+  --branch $(git rev-parse --abbrev-ref HEAD) \
+  --cloudfront https://<cloudfront_domain> \
+  --check \
+  --dry-run
+```
+
+4. Publish
+
+```bash
+poetry run publish-allure \
+  --bucket <bucket> \
+  --prefix reports \
+  --project demo \
+  --branch $(git rev-parse --abbrev-ref HEAD) \
+  --cloudfront https://<cloudfront_domain> \
+  --ttl-days 30 \
+  --max-keep-runs 5
+```
+
+5. Verify
+
+- S3: `reports/demo/<branch>/<run_id>/...` and `reports/demo/<branch>/latest/` with `LATEST_READY`.
+- CDN: open printed `run_url` / `latest_url`.
+

pytest_allure_host-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pytest_allure_host/__init__.py,sha256=Us3L46Kd1Rh1FM9e74PJB7TN4G37WkM12edi8GnGhgc,130
+pytest_allure_host/__main__.py,sha256=1dzo3_74YYjXLo4xf_OjbmayOAzDdTlIgCVX00tHdoU,99
+pytest_allure_host/cli.py,sha256=spAuHeyykEa7Dnm6eNsommVZI-0ovKZvGnajgySdpYc,3541
+pytest_allure_host/config.py,sha256=2I3qGLU_L6urayLIwGVin3Mp3nLRTyzJ1NzHiNnpAwc,3850
+pytest_allure_host/plugin.py,sha256=zLiu7qbUU-jN1QLglO1bAlX2UQRPiwLtN8JS4ui8kA8,4933
+pytest_allure_host/publisher.py,sha256=bSgE5dULYXSpDoXNEkaDDjcEaVDErcsrMcT6fasbjpo,26437
+pytest_allure_host/utils.py,sha256=0nPzsViqKSV7Wwx9bbMvPVMZBzwD_i439GltyGXKbLQ,3104
+pytest_allure_host-0.1.1.dist-info/METADATA,sha256=g9Yfx_igtu1U4AW8kJOjPTYq_qSpR-f89K6BUQ1kz-k,10044
+pytest_allure_host-0.1.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+pytest_allure_host-0.1.1.dist-info/entry_points.txt,sha256=PWnSY4aqAumEX4-dc1TkNHfju5VTKPUHfYPv1SdAlIA,119
+pytest_allure_host-0.1.1.dist-info/licenses/LICENSE,sha256=jcHN7r3njxuM4ilSLkK0fuuQAGMMkqzvYL27CYZGnWs,1084
+pytest_allure_host-0.1.1.dist-info/RECORD,,

pytest_allure_host-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_allure_host-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+publish-allure=pytest_allure_host.cli:main
+
+[pytest11]
+pytest_allure_host=pytest_allure_host.plugin
+

pytest_allure_host-0.1.1.dist-info/licenses/LICENSE

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