pytest-nexus 0.2.4__py3-none-any.whl

pytest_nexus/__init__.py

@@ -0,0 +1,5 @@
+"""pytest-nexus: send pytest results to Nexus for Jira."""
+
+from .plugin import VERSION as __version__
+
+__all__ = ["__version__"]

pytest_nexus/plugin.py

@@ -0,0 +1,484 @@
+"""pytest plugin: send the session's JUnit XML to Nexus for Jira when the run ends.
+
+Enabled when a Nexus URL is configured (``--nexus-url`` or ``NEXUS_URL``); otherwise it
+does nothing. If ``--junitxml`` is not given, the plugin writes its own report to a
+temporary file. Upload problems only warn unless ``--nexus-fail-on-upload-error`` is set.
+The API key is read from ``NEXUS_API_KEY`` (or ``--nexus-api-key``) and never printed.
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Callable, Mapping, Optional
+
+import pytest
+
+__all__ = [
+    "NexusConfig",
+    "resolve_config",
+    "config_problem",
+    "transport_problem",
+    "build_request_url",
+    "transport_body",
+    "post_results",
+    "ci_build_url",
+    "new_idempotency_key",
+]
+
+VERSION = "0.2.4"
+# 0.2.4 (10/10/2026): first PyPI release (`pip install pytest-nexus`); MIT licence. No behaviour change.
+# 0.2.3 (28/09/2026, parity with the other reporters):
+# - every upload carries an ``Idempotency-Key`` (docs/api-contracts.md section 1 "Durable
+#   deliveries"), the same on every resend of that report (continuations, retries and the
+#   raw-XML fallback), so Nexus treats all the sends as one delivery however late the last
+#   one arrives. ``--nexus-idempotency-key`` / NEXUS_IDEMPOTENCY_KEY sets it (16-128 of
+#   A-Z a-z 0-9 . _ : -, as for the nexus-upload CLI); otherwise ``pytest-nexus-<uuid>``,
+#   new for each run.
+# - ``&buildUrl=``: the CI job's page, shown on each run as "Open CI job"
+#   (``--nexus-build-url`` / NEXUS_BUILD_URL, else the CI system's own variables: GitHub
+#   Actions, GitLab, Azure Pipelines, Jenkins, Bitbucket Pipelines, CircleCI). https only.
+# 0.2.2 (28/09/2026, automation e2e F1): the JUnit XML is sent inside a JSON envelope,
+# {"format": "junit-xml", "encoding": "base64", "content": ...} (or "encoding": "text" when
+# base64 would pass the 5 MB cap), because raw line breaks in an XML body did not reach
+# Nexus and stack traces lost their lines. Against an older Nexus (400 to the envelope,
+# nothing recorded) the raw XML is sent once instead.
+# 0.2.1 (28/09/2026, SEC27-M4 transport): the Nexus URL must be https; plain http is
+# refused before the key or the report is sent, except to localhost/127.0.0.1/::1 when
+# NEXUS_ALLOW_INSECURE_LOCALHOST=1 (local tests only). Redirects are never followed, so
+# the bearer key is never re-sent to another address.
+# 0.2.0 (27/09/2026, ingestion idempotency): a report that reaches Nexus's time limit
+# part-way is sent again until Nexus has recorded all of it. Nexus remembers what each
+# upload already recorded, so a resend never records a result twice; a 202 whose body
+# says "partial", a 500, a 502/503/504 and a network error are all resent.
+MAX_ATTEMPTS = 8
+MAX_RETRY_DELAY = 15.0
+_RESEND_STATUSES = (500, 502, 503, 504)
+MAX_BODY_BYTES = 5 * 1024 * 1024
+PROJECT_KEY = re.compile(r"^[A-Z][A-Z0-9_]+$")
+ISSUE_KEY = re.compile(r"^[A-Z][A-Z0-9_]+-\d+$")
+INSECURE_LOCALHOST_ENV = "NEXUS_ALLOW_INSECURE_LOCALHOST"
+_LOOPBACK_HOSTS = ("localhost", "127.0.0.1", "::1")
+# Nexus's rule for the Idempotency-Key header (docs/api-contracts.md section 1 "Replay protection").
+IDEMPOTENCY_KEY = re.compile(r"^[A-Za-z0-9._:-]{16,128}$")
+MAX_BUILD_URL_CHARS = 500
+
+# option dest -> environment variable
+_ENV = {
+    "url": "NEXUS_URL",
+    "api_key": "NEXUS_API_KEY",
+    "project": "NEXUS_PROJECT",
+    "environment": "NEXUS_ENVIRONMENT",
+    "test_set": "NEXUS_TEST_SET",
+    "build": "NEXUS_BUILD",
+    "commit": "NEXUS_COMMIT",
+    "component": "NEXUS_COMPONENT",
+    "build_url": "NEXUS_BUILD_URL",
+    "idempotency_key": "NEXUS_IDEMPOTENCY_KEY",
+}
+_CI_BUILD = ("GITHUB_RUN_ID", "CI_PIPELINE_IID", "BUILD_BUILDNUMBER", "BITBUCKET_BUILD_NUMBER", "BUILD_NUMBER")
+_CI_COMMIT = ("GITHUB_SHA", "CI_COMMIT_SHA", "BUILD_SOURCEVERSION", "BITBUCKET_COMMIT", "GIT_COMMIT")
+
+_STATUS_HINT = {
+    400: "the report was not accepted (or the test set names nothing in this project)",
+    401: 'unauthorized: wrong, revoked or other-project key, or the key lacks the "ingest" scope',
+    413: "the report is over 5 MB or 500 results",
+    500: "Nexus stopped before the end (time limit) or had an unexpected error; see the delivery log in Project Settings > CI",
+}
+
+_STATE_KEY = pytest.StashKey["_NexusState"]()
+
+
+@dataclass
+class NexusConfig:
+    url: Optional[str] = None
+    api_key: Optional[str] = None
+    project: Optional[str] = None
+    environment: Optional[str] = None
+    test_set: Optional[str] = None
+    build: Optional[str] = None
+    commit: Optional[str] = None
+    component: Optional[str] = None
+    build_url: Optional[str] = None
+    idempotency_key: Optional[str] = None
+    fail_on_upload_error: bool = False
+    timeout: float = 60.0
+    # Test switch only: allow plain http to this machine (NEXUS_ALLOW_INSECURE_LOCALHOST=1).
+    allow_insecure_localhost: bool = False
+
+
+@dataclass
+class _NexusState:
+    config: NexusConfig
+    xml_path: str
+    temp_dir: Optional[str] = None
+    lines: list = field(default_factory=list)
+
+
+def _clean(value: object) -> Optional[str]:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _first(env: Mapping[str, str], names) -> Optional[str]:
+    for name in names:
+        value = _clean(env.get(name))
+        if value:
+            return value
+    return None
+
+
+def _https_url(value: Optional[str]) -> Optional[str]:
+    """``value`` when it is a plain https URL of at most 500 characters, else None."""
+    if not value or len(value) > MAX_BUILD_URL_CHARS or any(ch.isspace() for ch in value):
+        return None
+    try:
+        parsed = urllib.parse.urlsplit(value)
+        hostname = parsed.hostname
+    except ValueError:
+        return None
+    if parsed.scheme != "https" or not hostname or parsed.username is not None or parsed.password is not None:
+        return None
+    return value
+
+
+def ci_build_url(env: Mapping[str, str]) -> Optional[str]:
+    """The CI job's own page from the CI system's standard variables (0.2.3, ``&buildUrl=``),
+    https only, else None. Same order as the nexus-upload CLI and the Playwright reporter:
+    GitHub Actions, GitLab, Azure Pipelines, Jenkins, Bitbucket Pipelines, CircleCI."""
+
+    def v(name: str) -> Optional[str]:
+        return _clean(env.get(name))
+
+    candidates = []
+    if v("GITHUB_SERVER_URL") and v("GITHUB_REPOSITORY") and v("GITHUB_RUN_ID"):
+        server = v("GITHUB_SERVER_URL").rstrip("/")
+        candidates.append(f"{server}/{v('GITHUB_REPOSITORY')}/actions/runs/{v('GITHUB_RUN_ID')}")
+    candidates.append(v("CI_JOB_URL"))
+    if v("SYSTEM_TEAMFOUNDATIONCOLLECTIONURI") and v("SYSTEM_TEAMPROJECT") and v("BUILD_BUILDID"):
+        collection = v("SYSTEM_TEAMFOUNDATIONCOLLECTIONURI").rstrip("/")
+        project = urllib.parse.quote(v("SYSTEM_TEAMPROJECT"), safe="!*'()")
+        build_id = urllib.parse.quote(v("BUILD_BUILDID"), safe="!*'()")
+        candidates.append(f"{collection}/{project}/_build/results?buildId={build_id}")
+    candidates.append(v("BUILD_URL"))
+    if v("BITBUCKET_REPO_FULL_NAME") and v("BITBUCKET_BUILD_NUMBER"):
+        candidates.append(f"https://bitbucket.org/{v('BITBUCKET_REPO_FULL_NAME')}/pipelines/results/{v('BITBUCKET_BUILD_NUMBER')}")
+    candidates.append(v("CIRCLE_BUILD_URL"))
+    for candidate in candidates:
+        url = _https_url(candidate)
+        if url:
+            return url
+    return None
+
+
+def new_idempotency_key() -> str:
+    """A new retry key for one report upload (0.2.3)."""
+    return f"pytest-nexus-{uuid.uuid4()}"
+
+
+def resolve_config(options: Mapping[str, object], env: Mapping[str, str]) -> NexusConfig:
+    """CLI options over NEXUS_* env vars over the CI system's own build/commit/job-page variables."""
+    values = {name: _clean(options.get(name)) or _clean(env.get(var)) for name, var in _ENV.items()}
+    values["build"] = values["build"] or _first(env, _CI_BUILD)
+    values["commit"] = values["commit"] or _first(env, _CI_COMMIT)
+    # As in the Playwright reporter: a given value that is not https is dropped and the CI
+    # system's own job page is used instead.
+    values["build_url"] = _https_url(values["build_url"]) or ci_build_url(env)
+    return NexusConfig(
+        **values,
+        fail_on_upload_error=bool(options.get("fail_on_upload_error")),
+        allow_insecure_localhost=env.get(INSECURE_LOCALHOST_ENV) == "1",
+    )
+
+
+def transport_problem(cfg: NexusConfig) -> Optional[str]:
+    """Why the key must not be sent to ``cfg.url``, or None: https always; http only to
+    localhost/127.0.0.1/::1 and only with NEXUS_ALLOW_INSECURE_LOCALHOST=1 (tests)."""
+    parsed = urllib.parse.urlparse(cfg.url or "")
+    if not parsed.netloc:
+        return "NEXUS_URL is not a valid https URL"
+    if parsed.scheme == "https":
+        return None
+    if parsed.scheme == "http" and cfg.allow_insecure_localhost and (parsed.hostname or "").lower() in _LOOPBACK_HOSTS:
+        return None
+    return "NEXUS_URL is not a valid https URL (plain http would expose the API key)"
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Never follow a redirect: urllib would copy the Authorization header onto it."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def _open(request, timeout):
+    return _OPENER.open(request, timeout=timeout)
+
+
+def config_problem(cfg: NexusConfig) -> Optional[str]:
+    if not cfg.url:
+        return "NEXUS_URL is not set"
+    problem = transport_problem(cfg)
+    if problem:
+        return problem
+    if not cfg.api_key:
+        return "NEXUS_API_KEY is not set"
+    if not cfg.project:
+        return "NEXUS_PROJECT is not set"
+    if not PROJECT_KEY.match(cfg.project):
+        return f'"{cfg.project}" is not a Jira project key'
+    if cfg.test_set and not ISSUE_KEY.match(cfg.test_set):
+        return f'"{cfg.test_set}" is not an issue key (e.g. NEX-25)'
+    if cfg.idempotency_key and not IDEMPOTENCY_KEY.match(cfg.idempotency_key):
+        return 'the idempotency key takes 16-128 letters, digits, ".", "_", ":" or "-"'
+    return None
+
+
+def build_request_url(cfg: NexusConfig) -> str:
+    parts = urllib.parse.urlsplit(cfg.url)
+    query = urllib.parse.parse_qsl(parts.query, keep_blank_values=True)
+    params = {
+        "project": cfg.project,
+        "format": "junit-xml",
+        "environment": cfg.environment,
+        "testSet": cfg.test_set,
+        "build": cfg.build,
+        "commit": cfg.commit,
+        "component": cfg.component,
+        "buildUrl": cfg.build_url,
+    }
+    names = set(params)
+    query = [(k, v) for k, v in query if k not in names] + [(k, v) for k, v in params.items() if v]
+    return urllib.parse.urlunsplit(parts._replace(query=urllib.parse.urlencode(query)))
+
+
+def _redact(text: str, key: Optional[str]) -> str:
+    return text.replace(key, "***") if key else text
+
+
+def _is_partial(body: bytes) -> bool:
+    """A 2xx body saying {"status": "partial"}: Nexus recorded part of the upload."""
+    try:
+        parsed = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return False
+    return isinstance(parsed, dict) and parsed.get("status") == "partial"
+
+
+def transport_body(body: bytes) -> tuple:
+    """(data, content_type, encoding) for one JUnit XML report (0.2.2, docs/api-contracts.md
+    section 1 "Transport: the upload envelope"): base64-wrapped in JSON so its line breaks
+    survive; the plain JSON-string form when base64 would pass the 5 MB cap; the raw XML
+    only when even that would."""
+    for encoding in ("base64", "text"):
+        if encoding == "base64":
+            content = base64.b64encode(body).decode("ascii")
+        else:
+            content = body.decode("utf-8", errors="replace")
+        wrapped = json.dumps({"format": "junit-xml", "encoding": encoding, "content": content}).encode("utf-8")
+        if len(wrapped) <= MAX_BODY_BYTES:
+            return wrapped, "application/json", encoding
+    return body, "application/xml", "none"
+
+
+def post_results(
+    cfg: NexusConfig,
+    body: bytes,
+    opener: Callable = _open,
+    retry_delay: float = 2.0,
+    max_attempts: int = MAX_ATTEMPTS,
+    sleep: Callable = time.sleep,
+) -> tuple:
+    """POST the JUnit XML. Returns (ok, message). Sends the same upload again until Nexus
+    has recorded all of it: after a 202 "partial", a 500 (time limit reached part-way), a
+    502/503/504 or a network error, up to ``max_attempts`` sends with a pause doubling
+    from ``retry_delay`` to 15 s. Safe: Nexus never records a result of one upload twice."""
+    problem = transport_problem(cfg)
+    if problem:
+        return False, problem
+    last = ""
+    data, content_type, encoding = transport_body(body)
+    # 0.2.2: a Nexus older than 28/09/2026 does not know the envelope and answers 400
+    # (nothing recorded); the raw XML is then sent once instead.
+    fell_back = encoding == "none"
+    # 0.2.3: one key for this upload, repeated on every send below.
+    idempotency_key = cfg.idempotency_key or new_idempotency_key()
+    attempt = 0
+    while attempt < max_attempts:
+        attempt += 1
+        request = urllib.request.Request(
+            build_request_url(cfg),
+            data=data,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {cfg.api_key}",
+                "Content-Type": content_type,
+                "Idempotency-Key": idempotency_key,
+                "User-Agent": f"pytest-nexus/{VERSION}",
+            },
+        )
+        try:
+            with opener(request, timeout=cfg.timeout) as response:
+                status = response.status
+                text = response.read()
+            if not _is_partial(text or b""):
+                return True, f"HTTP {status}"
+            last = f"HTTP {status} (Nexus recorded part of the report)"
+        except urllib.error.HTTPError as err:
+            status = err.code
+            if 300 <= status < 400:
+                return False, (
+                    f"HTTP {status} (a redirect, not followed so the API key is never sent elsewhere; "
+                    "copy the Results URL again from Project Settings > CI)"
+                )
+            hint = _STATUS_HINT.get(status)
+            last = f"HTTP {status}" + (f" ({hint})" if hint else "")
+            if status == 400 and not fell_back:
+                fell_back = True
+                data, content_type = body, "application/xml"
+                attempt -= 1
+                continue
+            if status not in _RESEND_STATUSES:
+                return False, last
+        except (urllib.error.URLError, OSError) as err:
+            reason = getattr(err, "reason", err)
+            last = f"network error: {_redact(str(reason), cfg.api_key)}"
+        if attempt < max_attempts:
+            sleep(min(retry_delay * 2 ** (attempt - 1), MAX_RETRY_DELAY))
+    return False, f"{last} (gave up after {max_attempts} sends)"
+
+
+# --------------------------------------------------------------------------- hooks
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup("nexus", "send results to Nexus for Jira")
+    group.addoption("--nexus-url", dest="nexus_url", help="Results URL from Project Settings > CI (default: NEXUS_URL)")
+    group.addoption("--nexus-api-key", dest="nexus_api_key", help="API key with the ingest scope; prefer the NEXUS_API_KEY env var")
+    group.addoption("--nexus-project", dest="nexus_project", help="Jira project key (default: NEXUS_PROJECT)")
+    group.addoption("--nexus-environment", dest="nexus_environment", help="Environment label (default: NEXUS_ENVIRONMENT)")
+    group.addoption("--nexus-test-set", dest="nexus_test_set", help="Test Set (cycle) key, e.g. NEX-25 (default: NEXUS_TEST_SET)")
+    group.addoption("--nexus-build", dest="nexus_build", help="Build id (default: NEXUS_BUILD, else the CI build number)")
+    group.addoption("--nexus-commit", dest="nexus_commit", help="Commit (default: NEXUS_COMMIT, else the CI commit SHA)")
+    group.addoption("--nexus-component", dest="nexus_component", help="Component label (default: NEXUS_COMPONENT)")
+    group.addoption(
+        "--nexus-build-url",
+        dest="nexus_build_url",
+        help="CI job page, https (default: NEXUS_BUILD_URL, else the CI system's own variables)",
+    )
+    group.addoption(
+        "--nexus-idempotency-key",
+        dest="nexus_idempotency_key",
+        help="Retry key sent on every send of the report, 16-128 of A-Z a-z 0-9 . _ : - (default: NEXUS_IDEMPOTENCY_KEY, else a new one per run)",
+    )
+    group.addoption(
+        "--nexus-fail-on-upload-error",
+        dest="nexus_fail_on_upload_error",
+        action="store_true",
+        default=False,
+        help="Fail the pytest run when the upload fails (default: warn only)",
+    )
+    group.addoption("--no-nexus", dest="nexus_disabled", action="store_true", default=False, help="Do not send results to Nexus")
+
+
+def _options(config) -> dict:
+    return {
+        name: config.getoption(f"nexus_{name}")
+        for name in (
+            "url",
+            "api_key",
+            "project",
+            "environment",
+            "test_set",
+            "build",
+            "commit",
+            "component",
+            "build_url",
+            "idempotency_key",
+            "fail_on_upload_error",
+        )
+    }
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_configure(config):
+    """Runs before the junitxml plugin's own configure, so a missing --junitxml can be
+    pointed at a temporary file."""
+    if config.getoption("nexus_disabled") or hasattr(config, "workerinput"):
+        return
+    cfg = resolve_config(_options(config), os.environ)
+    if not cfg.url:
+        return  # not configured: stay out of the way
+    temp_dir = None
+    xml_path = config.option.xmlpath
+    if not xml_path:
+        temp_dir = tempfile.mkdtemp(prefix="pytest-nexus-")
+        xml_path = os.path.join(temp_dir, "results.xml")
+        config.option.xmlpath = xml_path
+    config.stash[_STATE_KEY] = _NexusState(config=cfg, xml_path=os.path.abspath(xml_path), temp_dir=temp_dir)
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_sessionfinish(session, exitstatus):
+    """Runs after the junitxml plugin has written its file."""
+    config = session.config
+    state = config.stash.get(_STATE_KEY, None)
+    if state is None:
+        return
+    cfg = state.config
+    ok, message = _send(state)
+    say = f"nexus: {_redact(message, cfg.api_key)}"
+    state.lines.append(say)
+    if not ok and cfg.fail_on_upload_error and session.exitstatus == 0:
+        session.exitstatus = pytest.ExitCode.TESTS_FAILED
+
+
+def _send(state: _NexusState) -> tuple:
+    cfg = state.config
+    problem = config_problem(cfg)
+    if problem:
+        return False, f"results not sent: {problem}."
+    try:
+        size = os.path.getsize(state.xml_path)
+    except OSError:
+        return False, "results not sent: no JUnit XML was written."
+    if size > MAX_BODY_BYTES:
+        return False, "results not sent: the JUnit XML is over 5 MB. Split the run."
+    with open(state.xml_path, "rb") as handle:
+        body = handle.read()
+    host = urllib.parse.urlparse(cfg.url).netloc
+    ok, detail = post_results(cfg, body)
+    if ok:
+        return True, f"sent results to project {cfg.project} at {host} ({detail}). See Project Settings > CI for the delivery log."
+    return False, f"results not sent to {host}: {detail}"
+
+
+def pytest_terminal_summary(terminalreporter, exitstatus, config):
+    state = config.stash.get(_STATE_KEY, None)
+    if state is None:
+        return
+    for line in state.lines:
+        terminalreporter.write_line(line)
+
+
+def pytest_unconfigure(config):
+    state = config.stash.get(_STATE_KEY, None)
+    if state is not None and state.temp_dir:
+        import shutil
+
+        shutil.rmtree(state.temp_dir, ignore_errors=True)

pytest_nexus-0.2.4.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: pytest-nexus
+Version: 0.2.4
+Summary: pytest plugin that sends each run's JUnit XML results to Nexus for Jira.
+Project-URL: Homepage, https://nexus.resync.nz
+Project-URL: Documentation, https://nexus.resync.nz/docs/automation/
+Author: Resync Consulting Limited
+License: MIT
+License-File: LICENSE
+Keywords: jira,junit,nexus,pytest,test management
+Classifier: Framework :: Pytest
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Requires-Dist: pytest>=7.0
+Description-Content-Type: text/markdown
+
+# pytest-nexus
+
+A pytest plugin that sends each run's results to **Nexus** for Jira. When the session
+ends it posts the JUnit XML report to your project's Nexus results URL, where each test is
+matched to a Test Case by its Automation Key.
+
+Standard library only (plus pytest 7 or later). Python 3.8+.
+
+## Install
+
+From PyPI:
+
+```sh
+pip install pytest-nexus
+```
+
+The same wheel and source archive are also on
+[nexus.resync.nz/integrations](https://nexus.resync.nz/integrations/), with checksums in
+[SHA256SUMS.txt](https://nexus.resync.nz/downloads/SHA256SUMS.txt).
+
+The plugin loads automatically. It does nothing until a Nexus URL is configured.
+
+## Configure
+
+In Jira, open **Project Settings → Nexus → CI**, create an API key with the
+**ingest** scope and copy the results URL. Store both as CI secrets:
+
+| Environment variable | CLI option | Meaning |
+|---|---|---|
+| `NEXUS_URL` | `--nexus-url` | Results URL (required) |
+| `NEXUS_API_KEY` | `--nexus-api-key` | API key (required; prefer the env var) |
+| `NEXUS_PROJECT` | `--nexus-project` | Jira project key, e.g. `NEX` (required) |
+| `NEXUS_ENVIRONMENT` | `--nexus-environment` | Environment label, e.g. `staging` |
+| `NEXUS_TEST_SET` | `--nexus-test-set` | Test Set (cycle) to record into, e.g. `NEX-25` |
+| `NEXUS_BUILD` | `--nexus-build` | Build id. Default: the CI system's build number |
+| `NEXUS_COMMIT` | `--nexus-commit` | Commit. Default: the CI system's commit SHA |
+| `NEXUS_COMPONENT` | `--nexus-component` | Component label, e.g. `api` |
+| `NEXUS_BUILD_URL` | `--nexus-build-url` | CI job page (https), shown on each run as "Open CI job". Default: the CI system's own job page (0.2.3) |
+| `NEXUS_IDEMPOTENCY_KEY` | `--nexus-idempotency-key` | Retry key, 16-128 of `A-Z a-z 0-9 . _ : -`. Default: a new random key per run (0.2.3) |
+
+Other options:
+
+- `--nexus-fail-on-upload-error`: fail the pytest run (exit code 1) when the upload
+  fails. By default an upload problem only prints a warning and the exit code is
+  whatever your tests produced.
+- `--no-nexus`: turn the plugin off for one run.
+
+Build, commit and the CI job page are filled automatically on GitHub Actions, GitLab,
+Azure Pipelines, Bitbucket Pipelines and Jenkins (the job page also on CircleCI). A job page
+that is not https is never sent.
+
+## Name your tests with the Automation Key
+
+Put the Test Case's Automation Key in the test name. Python names cannot contain `-`, so
+use `_`; Nexus reads `NEX_11` as `NEX-11`:
+
+```python
+def test_NEX_11_valid_user_signs_in(driver):
+    ...
+```
+
+Results whose name carries no known key are listed as *unmatched* in the delivery log.
+
+## Example
+
+```sh
+export NEXUS_URL=...        # from your CI secret store
+export NEXUS_API_KEY=...
+pytest --nexus-project NEX --nexus-environment staging
+```
+
+If you already pass `--junitxml=path.xml`, that file is the one sent. Otherwise the
+plugin writes a temporary report and removes it afterwards. With pytest-xdist, only the
+controller sends.
+
+Output at the end of the run:
+
+```
+nexus: sent results to project NEX at <your-site>.atlassian-dev.net (HTTP 202). See Project Settings > CI for the delivery log.
+```
+
+Nexus answers `202` with `{"status":"accepted"}` only after it has processed every
+result of the report (SEC27-H9, 28/09/2026: nothing is left running in the background
+behind an "accepted"); the per-test outcome (matched, unmatched, skipped) is in the delivery
+log on the CI page. A `{"status":"partial"}` answer means Nexus holds the report and what it
+recorded so far and finishes the rest itself; the reporter sends it again to confirm.
+The API key is never printed. Reports over 5 MB or 500 results must be split.
+A report that reaches Nexus's time limit part-way (a 202 whose body says "partial", or a
+500), a 502/503/504 or a network error is sent again, up to 8 sends, until Nexus has
+recorded all of it; a resend never records a result twice (0.2.0, 27/09/2026). Since 0.2.3
+every send of one report carries the same `Idempotency-Key` header, so Nexus treats a late
+resend as the same delivery, never as a new run.
+
+## Develop
+
+```sh
+python -m pytest        # from this folder; uses a local fake Nexus, no network
+```
+
+## Licence
+
+MIT. © 2026 Resync Consulting Limited. See `LICENSE`.

pytest_nexus-0.2.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+pytest_nexus/__init__.py,sha256=KR3NPPtg2OoKtfUI4fr1UJF3qhO6OhJTTbasN94LKiE,130
+pytest_nexus/plugin.py,sha256=2RFBVzrETP6sluqgM8p1-JFRU_JNkJHKBalZfJq_ioI,20009
+pytest_nexus-0.2.4.dist-info/METADATA,sha256=0PaeM0AqQscqfnO_SjrEdKi-CBVVXT6CqZ-xEL7Cdj8,4924
+pytest_nexus-0.2.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pytest_nexus-0.2.4.dist-info/entry_points.txt,sha256=WijT5HT1Z9gpB5F_bL3QvyNmaSVh-5eD-fMqXjAyedQ,39
+pytest_nexus-0.2.4.dist-info/licenses/LICENSE,sha256=XEkfIfI1uCrdzb_3NfYFYGmV3qMFygQvL35QxkAWVNE,1082
+pytest_nexus-0.2.4.dist-info/RECORD,,

pytest_nexus-0.2.4.dist-info/WHEEL

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

pytest_nexus-0.2.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+nexus = pytest_nexus.plugin

pytest_nexus-0.2.4.dist-info/licenses/LICENSE

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