pytest-allure-host 0.1.2__tar.gz → 2.0.0__tar.gz

{pytest_allure_host-0.1.2 → pytest_allure_host-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-allure-host
-Version: 0.1.2
+Version: 2.0.0
 Summary: Publish Allure static reports to private S3 behind CloudFront with history preservation
 License-Expression: MIT
 License-File: LICENSE
@@ -17,6 +17,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Testing
 Classifier: Framework :: Pytest
 Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Dist: PyYAML (>=6,<7)
 Requires-Dist: boto3 (>=1.28,<2.0)
@@ -34,9 +35,12 @@ Description-Content-Type: text/markdown
 ![PyPI - Version](https://img.shields.io/pypi/v/pytest-allure-host.svg)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 [![Docs](https://img.shields.io/badge/docs-site-blue)](https://darrenrabbs.github.io/allurehosting/)
+[![CDK Stack](https://img.shields.io/badge/CDK%20Stack-repo-blueviolet)](https://github.com/darrenrabbs/allurehosting-cdk)
 
 Publish Allure static reports to private S3 behind CloudFront with history preservation and SPA-friendly routing.
 
+Optional infrastructure (AWS CDK stack to provision the private S3 bucket + CloudFront OAC distribution) lives externally: https://github.com/darrenrabbs/allurehosting-cdk
+
 See `docs/architecture.md` and `.github/copilot-instructions.md` for architecture and design constraints.
 
 ## Documentation
@@ -63,6 +67,39 @@ The README intentionally stays lean—refer to the site for detailed guidance.
   - 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
 
+## Quick start
+
+```bash
+# Install the publisher
+pip install pytest-allure-host
+
+# Run your test suite and produce allure-results/
+pytest --alluredir=allure-results
+
+# Plan (no uploads) – shows what would be published
+publish-allure \
+  --bucket my-allure-bucket \
+  --project myproj \
+  --branch main \
+  --dry-run --summary-json plan.json
+
+# Real publish (requires AWS creds: env vars, profile, or OIDC)
+publish-allure \
+  --bucket my-allure-bucket \
+  --project myproj \
+  --branch main
+```
+
+Notes:
+
+- `--prefix` defaults to `reports`; omit unless you need a different root.
+- `--branch` defaults to `$GIT_BRANCH` or `main` if unset.
+- Add `--cloudfront https://reports.example.com` to print CDN URLs.
+- Use `--check` to preflight (AWS / allure binary / inputs) before a real run.
+- Add `--context-url https://jira.example.com/browse/PROJ-123` to link a change ticket in the runs index.
+- Use `--dry-run` + `--summary-json` in CI for a planning stage artifact.
+- Provide `--ttl-days` and/or `--max-keep-runs` for lifecycle & cost controls.
+
 ## Requirements
 
 - Python 3.9+
@@ -230,6 +267,56 @@ Pytest-driven (plugin):
     --allure-max-keep-runs 10
 ```
 
+### Minimal publish-only workflow
+
+Create `.github/workflows/allure-publish.yml` for a lightweight pipeline that runs tests, generates the report, and publishes it (using secrets for the bucket and AWS credentials):
+
+```yaml
+name: allure-publish
+on: [push, pull_request]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install deps (minimal)
+        run: pip install pytest pytest-allure-host allure-pytest
+      - name: Run tests
+        run: pytest --alluredir=allure-results -q
+      - name: Publish Allure report (dry-run on PRs)
+        env:
+          AWS_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          ALLURE_BUCKET: ${{ secrets.ALLURE_BUCKET }}
+        run: |
+          EXTRA=""
+          if [ "${{ github.event_name }}" = "pull_request" ]; then EXTRA="--dry-run"; fi
+          publish-allure \
+            --bucket "$ALLURE_BUCKET" \
+            --project myproj \
+            --branch "${{ github.ref_name }}" \
+            --summary-json summary.json $EXTRA
+      - name: Upload publish summary (always)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: allure-summary
+          path: summary.json
+```
+
+Notes:
+
+- Add `--cloudfront https://reports.example.com` if you have a CDN domain.
+- Add `--context-url ${{ github.server_url }}/${{ github.repository }}/pull/${{ github.event.pull_request.number }}` inside PRs to link the run to its PR.
+- Use `--max-keep-runs` / `--ttl-days` to manage storage costs.
+- For LocalStack-based tests, set `--s3-endpoint` and export `ALLURE_S3_ENDPOINT` in `env:`.
+
 ## Troubleshooting
 
 - Missing Allure binary: ensure the Allure CLI is installed and on PATH.

{pytest_allure_host-0.1.2 → pytest_allure_host-2.0.0}/README.md

@@ -5,9 +5,12 @@
 ![PyPI - Version](https://img.shields.io/pypi/v/pytest-allure-host.svg)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 [![Docs](https://img.shields.io/badge/docs-site-blue)](https://darrenrabbs.github.io/allurehosting/)
+[![CDK Stack](https://img.shields.io/badge/CDK%20Stack-repo-blueviolet)](https://github.com/darrenrabbs/allurehosting-cdk)
 
 Publish Allure static reports to private S3 behind CloudFront with history preservation and SPA-friendly routing.
 
+Optional infrastructure (AWS CDK stack to provision the private S3 bucket + CloudFront OAC distribution) lives externally: https://github.com/darrenrabbs/allurehosting-cdk
+
 See `docs/architecture.md` and `.github/copilot-instructions.md` for architecture and design constraints.
 
 ## Documentation
@@ -34,6 +37,39 @@ The README intentionally stays lean—refer to the site for detailed guidance.
   - 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
 
+## Quick start
+
+```bash
+# Install the publisher
+pip install pytest-allure-host
+
+# Run your test suite and produce allure-results/
+pytest --alluredir=allure-results
+
+# Plan (no uploads) – shows what would be published
+publish-allure \
+  --bucket my-allure-bucket \
+  --project myproj \
+  --branch main \
+  --dry-run --summary-json plan.json
+
+# Real publish (requires AWS creds: env vars, profile, or OIDC)
+publish-allure \
+  --bucket my-allure-bucket \
+  --project myproj \
+  --branch main
+```
+
+Notes:
+
+- `--prefix` defaults to `reports`; omit unless you need a different root.
+- `--branch` defaults to `$GIT_BRANCH` or `main` if unset.
+- Add `--cloudfront https://reports.example.com` to print CDN URLs.
+- Use `--check` to preflight (AWS / allure binary / inputs) before a real run.
+- Add `--context-url https://jira.example.com/browse/PROJ-123` to link a change ticket in the runs index.
+- Use `--dry-run` + `--summary-json` in CI for a planning stage artifact.
+- Provide `--ttl-days` and/or `--max-keep-runs` for lifecycle & cost controls.
+
 ## Requirements
 
 - Python 3.9+
@@ -201,6 +237,56 @@ Pytest-driven (plugin):
     --allure-max-keep-runs 10
 ```
 
+### Minimal publish-only workflow
+
+Create `.github/workflows/allure-publish.yml` for a lightweight pipeline that runs tests, generates the report, and publishes it (using secrets for the bucket and AWS credentials):
+
+```yaml
+name: allure-publish
+on: [push, pull_request]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install deps (minimal)
+        run: pip install pytest pytest-allure-host allure-pytest
+      - name: Run tests
+        run: pytest --alluredir=allure-results -q
+      - name: Publish Allure report (dry-run on PRs)
+        env:
+          AWS_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          ALLURE_BUCKET: ${{ secrets.ALLURE_BUCKET }}
+        run: |
+          EXTRA=""
+          if [ "${{ github.event_name }}" = "pull_request" ]; then EXTRA="--dry-run"; fi
+          publish-allure \
+            --bucket "$ALLURE_BUCKET" \
+            --project myproj \
+            --branch "${{ github.ref_name }}" \
+            --summary-json summary.json $EXTRA
+      - name: Upload publish summary (always)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: allure-summary
+          path: summary.json
+```
+
+Notes:
+
+- Add `--cloudfront https://reports.example.com` if you have a CDN domain.
+- Add `--context-url ${{ github.server_url }}/${{ github.repository }}/pull/${{ github.event.pull_request.number }}` inside PRs to link the run to its PR.
+- Use `--max-keep-runs` / `--ttl-days` to manage storage costs.
+- For LocalStack-based tests, set `--s3-endpoint` and export `ALLURE_S3_ENDPOINT` in `env:`.
+
 ## Troubleshooting
 
 - Missing Allure binary: ensure the Allure CLI is installed and on PATH.

{pytest_allure_host-0.1.2 → pytest_allure_host-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "pytest-allure-host"
-version = "0.1.2"
+version = "2.0.0"
 description = "Publish Allure static reports to private S3 behind CloudFront with history preservation"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,7 @@ classifiers = [
     "Topic :: Software Development :: Testing",
     "Framework :: Pytest",
     "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent"
 ]
 
@@ -47,6 +48,9 @@ pip-audit = ">=2.7,<3.0"
 black = ">=24,<26"
 mkdocs = ">=1.5,<2.0"
 mkdocs-material = ">=9.5,<10.0"
+playwright = ">=1.44,<2.0"  # optional UI interaction tests (RUN_UI=1)
+beautifulsoup4 = "^4.12.3"
+Pillow = ">=10,<11"  # for webp conversion in screenshot helper
 
 [project.scripts]
 publish-allure = "pytest_allure_host.cli:main"
@@ -63,17 +67,45 @@ Changelog = "https://darrenrabbs.github.io/allurehosting/changelog/"
 
 # Package include (PEP 621 doesn't specify this; still handled by Poetry configuration)
 [tool.poetry]
+# Duplicate minimal metadata for backward compatibility with Poetry 1.x commands; primary metadata is under [project].
+name = "pytest-allure-host"
+version = "2.0.0"
+description = "Publish Allure static reports to private S3 behind CloudFront with history preservation"
+authors = ["Allure Hosting Maintainers"]
+license = "MIT"
+readme = "README.md"
 packages = [{ include = "pytest_allure_host" }]
-# PEP 621 is authoritative; legacy duplicate metadata removed (require Poetry 2.2.1+)
+# Limit published artifacts strictly to the runtime package; exclude development & generated dirs.
+exclude = [
+    "tests",
+    "docs",
+    "infra",
+    "reports",
+    "allure-results",
+    "allure-report",
+    "demo_run",
+    "scripts/*.sh",
+    "*.iml",
+]
+# Both PEP 621 ([project]) and minimal [tool.poetry] are present; [project] is the source of truth.
 
 [tool.poetry.dependencies]
-# Retained only for Poetry's internal processing of the runtime dependency group.
+# Retained for Poetry 1.x compatibility
 python = ">=3.9,<4.0"
 
 
 [tool.ruff]
 line-length = 100
 target-version = "py39"
+extend-exclude = [
+    "dev/**",
+    "docs/**",
+    "site/**",
+    "site-internal/**",
+    ".lh/**",
+    ".history/**",
+    "scripts/**",
+]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "S", "W", "C90"]

pytest_allure_host-2.0.0/pytest_allure_host/__init__.py

@@ -0,0 +1,14 @@
+from importlib import metadata as _md
+
+from .utils import PublishConfig, default_run_id  # re-export key types
+
+try:  # runtime version (works inside installed env)
+    __version__ = _md.version("pytest-allure-host")
+except Exception:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "PublishConfig",
+    "default_run_id",
+    "__version__",
+]

pytest_allure_host-2.0.0/pytest_allure_host/cli.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from . import __version__
+from .config import load_effective_config
+from .publisher import plan_dry_run, preflight, publish
+from .utils import PublishConfig, default_run_id
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser("publish-allure")
+    p.add_argument(
+        "--version",
+        action="store_true",
+        help="Print version and exit",
+    )
+    p.add_argument("--config", help="Path to YAML config (optional)")
+    p.add_argument("--bucket")
+    p.add_argument("--prefix", default=None)
+    p.add_argument("--project")
+    p.add_argument("--branch", default=os.getenv("GIT_BRANCH", "main"))
+    p.add_argument(
+        "--run-id",
+        default=os.getenv("ALLURE_RUN_ID", default_run_id()),
+    )
+    p.add_argument("--cloudfront", default=os.getenv("ALLURE_CLOUDFRONT"))
+    p.add_argument(
+        "--results",
+        "--results-dir",
+        dest="results",
+        default=os.getenv("ALLURE_RESULTS_DIR", "allure-results"),
+        help="Path to allure-results directory (alias: --results-dir)",
+    )
+    p.add_argument(
+        "--report",
+        default=os.getenv("ALLURE_REPORT_DIR", "allure-report"),
+        help="Output directory for generated Allure static report",
+    )
+    p.add_argument("--ttl-days", type=int, default=None)
+    p.add_argument("--max-keep-runs", type=int, default=None)
+    p.add_argument(
+        "--sse",
+        default=os.getenv("ALLURE_S3_SSE"),
+        help="Server-side encryption algorithm (AES256 or aws:kms)",
+    )
+    p.add_argument(
+        "--sse-kms-key-id",
+        default=os.getenv("ALLURE_S3_SSE_KMS_KEY_ID"),
+        help="KMS Key ID / ARN when --sse=aws:kms",
+    )
+    p.add_argument(
+        "--s3-endpoint",
+        default=os.getenv("ALLURE_S3_ENDPOINT"),
+        help=("Custom S3 endpoint URL (e.g. http://localhost:4566)"),
+    )
+    p.add_argument("--summary-json", default=None)
+    p.add_argument(
+        "--context-url",
+        default=os.getenv("ALLURE_CONTEXT_URL"),
+        help="Optional hyperlink giving change context (e.g. Jira ticket)",
+    )
+    p.add_argument(
+        "--meta",
+        action="append",
+        default=[],
+        metavar="KEY=VAL",
+        help=(
+            "Attach arbitrary metadata (repeatable). Example: --meta "
+            "jira=PROJ-123 --meta env=staging. Adds dynamic columns to "
+            "runs index & manifest."
+        ),
+    )
+    p.add_argument("--dry-run", action="store_true", help="Plan only")
+    p.add_argument(
+        "--check",
+        action="store_true",
+        help="Run preflight checks (AWS, allure, inputs)",
+    )
+    p.add_argument(
+        "--verbose-summary",
+        action="store_true",
+        help="Print extended summary (CDN prefixes, manifest path, metadata)",
+    )
+    p.add_argument(
+        "--allow-duplicate-prefix-project",
+        action="store_true",
+        help=(
+            "Bypass guard preventing prefix==project duplication. "
+            "Only use if you intentionally want that folder layout."
+        ),
+    )
+    p.add_argument(
+        "--upload-workers",
+        type=int,
+        default=None,
+        help="Parallel upload worker threads (auto if unset)",
+    )
+    p.add_argument(
+        "--copy-workers",
+        type=int,
+        default=None,
+        help="Parallel copy worker threads for latest promotion",
+    )
+    p.add_argument(
+        "--archive-run",
+        action="store_true",
+        help="Also produce a compressed archive of the run (tar.gz)",
+    )
+    p.add_argument(
+        "--archive-format",
+        choices=["tar.gz", "zip"],
+        default="tar.gz",
+        help="Archive format when --archive-run is set",
+    )
+    return p.parse_args()
+
+
+def _parse_metadata(pairs: list[str]) -> dict | None:
+    if not pairs:
+        return None
+    meta: dict[str, str] = {}
+    for raw in pairs:
+        if "=" not in raw:
+            continue
+        k, v = raw.split("=", 1)
+        k = k.strip()
+        v = v.strip()
+        if not k:
+            continue
+        safe_k = k.lower().replace("-", "_")
+        if safe_k and v:
+            meta[safe_k] = v
+    return meta or None
+
+
+def _build_cli_overrides(args: argparse.Namespace) -> dict:
+    return {
+        "bucket": args.bucket,
+        "prefix": args.prefix,
+        "project": args.project,
+        "branch": args.branch,
+        "cloudfront": args.cloudfront,
+        "run_id": args.run_id,
+        "ttl_days": args.ttl_days,
+        "max_keep_runs": args.max_keep_runs,
+        "s3_endpoint": args.s3_endpoint,
+        "context_url": args.context_url,
+        "sse": args.sse,
+        "sse_kms_key_id": args.sse_kms_key_id,
+    }
+
+
+def _effective_config(args: argparse.Namespace) -> tuple[dict, PublishConfig]:
+    overrides = _build_cli_overrides(args)
+    effective = load_effective_config(overrides, args.config)
+    cfg_source = effective.get("_config_file")
+    if cfg_source:
+        print(f"[config] loaded settings from {cfg_source}")
+    missing = [k for k in ("bucket", "project") if not effective.get(k)]
+    if missing:
+        missing_list = ", ".join(missing)
+        raise SystemExit(
+            f"Missing required config values: {missing_list}. Provide via CLI, env, or YAML."
+        )
+    cfg = PublishConfig(
+        bucket=effective["bucket"],
+        prefix=effective.get("prefix") or "reports",
+        project=effective["project"],
+        branch=effective.get("branch") or args.branch,
+        run_id=effective.get("run_id") or args.run_id,
+        cloudfront_domain=effective.get("cloudfront"),
+        ttl_days=effective.get("ttl_days"),
+        max_keep_runs=effective.get("max_keep_runs"),
+        s3_endpoint=effective.get("s3_endpoint"),
+        context_url=effective.get("context_url"),
+        sse=effective.get("sse"),
+        sse_kms_key_id=effective.get("sse_kms_key_id"),
+        metadata=_parse_metadata(args.meta),
+        upload_workers=args.upload_workers,
+        copy_workers=args.copy_workers,
+        archive_run=args.archive_run,
+        archive_format=args.archive_format if args.archive_run else None,
+    )
+    # Guard against accidental duplication like prefix==project producing
+    # 'reports/reports/<branch>/...' paths. This is usually unintentional
+    # and makes report URLs longer / redundant. Fail fast so users can
+    # correct config explicitly (they can still deliberately choose this
+    # by changing either value slightly, e.g. prefix='reports',
+    # project='team-reports').
+    if cfg.prefix == cfg.project and not getattr(args, "allow_duplicate_prefix_project", False):
+        parts = [
+            "Invalid config: prefix and project are identical (",
+            f"'{cfg.project}'). ",
+            "This yields duplicated S3 paths (",
+            f"{cfg.prefix}/{cfg.project}/<branch>/...). ",
+            "Set distinct values (e.g. prefix='reports', project='payments').",
+        ]
+        raise SystemExit("".join(parts))
+    return effective, cfg
+
+
+def _write_json(path: str, payload: dict) -> None:
+    import json
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2)
+
+
+def _print_publish_summary(
+    cfg: PublishConfig,
+    out: dict,
+    verbose: bool = False,
+) -> None:
+    print("Publish complete")
+    if out.get("run_url"):
+        print(f"Run URL: {out['run_url']}")
+    if out.get("latest_url"):
+        print(f"Latest URL: {out['latest_url']}")
+    # Main aggregated runs index (HTML) at branch root if CDN configured
+    if cfg.cloudfront_domain:
+        branch_root = f"{cfg.prefix}/{cfg.project}/{cfg.branch}"
+        cdn_root = cfg.cloudfront_domain.rstrip("/")
+        runs_index_url = f"{cdn_root}/{branch_root}/runs/index.html"
+        print(f"Runs Index URL: {runs_index_url}")
+    run_prefix = out.get("run_prefix") or cfg.s3_run_prefix
+    latest_prefix = out.get("latest_prefix") or cfg.s3_latest_prefix
+    print(f"S3 run prefix: s3://{cfg.bucket}/{run_prefix}")
+    print(f"S3 latest prefix: s3://{cfg.bucket}/{latest_prefix}")
+    print(
+        "Report files: "
+        f"{out.get('report_files', '?')}  Size: "
+        f"{out.get('report_size_bytes', '?')} bytes"
+    )
+    if verbose and cfg.cloudfront_domain:
+        # Duplicate earlier lines but clarify this is the CDN-root mapping
+        print("CDN run prefix (index root):", cfg.url_run())
+        print("CDN latest prefix (index root):", cfg.url_latest())
+    if verbose:
+        # Manifest stored at branch root under runs/index.json
+        branch_root = f"{cfg.prefix}/{cfg.project}/{cfg.branch}"
+        manifest_key = f"{branch_root}/runs/index.json"
+        print("Manifest object:", f"s3://{cfg.bucket}/{manifest_key}")
+        if cfg.metadata:
+            print("Metadata keys:", ", ".join(sorted(cfg.metadata.keys())))
+        if cfg.sse:
+            print("Encryption:", cfg.sse, cfg.sse_kms_key_id or "")
+
+
+def main() -> int:  # noqa: C901 (reduced but keep guard just in case)
+    args = parse_args()
+    if args.version:
+        print(__version__)
+        return 0
+    effective, cfg = _effective_config(args)
+    # Construct explicit Paths honoring custom results/report dirs
+    paths = None
+    try:
+        mod = __import__("pytest_allure_host.publisher", fromlist=["Paths"])
+        paths = mod.publisher.Paths(
+            results=Path(args.results),
+            report=Path(args.report),
+        )
+    except Exception:  # pragma: no cover - defensive fallback
+        from .publisher import Paths  # type: ignore
+
+        paths = Paths(results=Path(args.results), report=Path(args.report))
+
+    if args.check:
+        checks = preflight(cfg, paths=paths)
+        print(checks)
+        if not all(checks.values()):
+            return 2
+    if args.dry_run:
+        plan = plan_dry_run(cfg, paths=paths)
+        print(plan)
+        if args.summary_json:
+            _write_json(args.summary_json, plan)
+        return 0
+    out = publish(cfg, paths=paths)
+    print(out)  # raw dict for backward compatibility
+    _print_publish_summary(cfg, out, verbose=args.verbose_summary)
+    if args.summary_json:
+        _write_json(args.summary_json, out)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())