pytest-testpulse 1.0.0__tar.gz

pytest_testpulse-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Barayo
+
+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_testpulse-1.0.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: pytest-testpulse
+Version: 1.0.0
+Summary: Report pytest results into TestPulse via its JUnit-XML import API
+Author: TestPulse
+License: MIT
+Project-URL: Homepage, https://github.com/Barayo/pytest-testpulse
+Classifier: Framework :: Pytest
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest>=7.0
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: python-semantic-release>=9.0; extra == "dev"
+Dynamic: license-file
+
+# pytest-testpulse
+
+A pytest plugin that reports test results into [TestPulse](https://github.com/Barayo/TestPulse)
+via its JUnit-XML import API, matching each test to an existing case by key.
+
+## Install
+
+```bash
+pip install pytest-testpulse
+```
+
+## Usage
+
+Mark a test with the case key it corresponds to in TestPulse:
+
+```python
+import pytest
+
+@pytest.mark.testpulse("LOGIN-42", platform="linux", tags=["smoke"])
+def test_login_succeeds():
+    ...
+```
+
+Run with `--junitxml` — the plugin reads pytest's own JUnit XML output rather
+than generating it itself, so this flag is required whenever the marker (or
+`--testpulse-dry-run`) is in use:
+
+```bash
+pytest --junitxml=report.xml
+```
+
+At the end of the session, the plugin submits `report.xml` to
+`POST /api/v1/projects/{project}/imports` and prints a summary. A suite with
+no marked tests and no `--testpulse-dry-run` needs no configuration at all —
+the plugin does nothing.
+
+## Configuration
+
+Each setting resolves in this order: **CLI flag › environment variable ›
+`pytest.ini`/`pyproject.toml` option** — the first one present wins.
+
+| Setting | CLI flag | Env var | ini-option |
+|---|---|---|---|
+| API base URL | `--testpulse-url` | `TESTPULSE_URL` | `testpulse_url` |
+| API token | `--testpulse-token` | `TESTPULSE_TOKEN` | `testpulse_token` |
+| Project key | `--testpulse-project` | `TESTPULSE_PROJECT` | `testpulse_project` |
+| Fail on unmatched | `--testpulse-fail-on-unmatched` / `--testpulse-no-fail-on-unmatched` | `TESTPULSE_FAIL_ON_UNMATCHED` | `testpulse_fail_on_unmatched` |
+
+`TESTPULSE_URL`/`TESTPULSE_TOKEN` match the env var names TestPulse's own
+docs already use for the raw `conftest.py` snippet, so migrating from that
+snippet to this plugin doesn't require renaming CI secrets. Put your token in
+an env var or CI secret — not in a committed ini-option.
+
+`testpulse_fail_on_unmatched` (env var and ini-option) accepts
+`1`/`true`/`yes` (case-insensitive) as true; anything else, including unset,
+is false. `--testpulse-no-fail-on-unmatched` overrides an ini-option or env
+var set to true, for a single local run.
+
+## Exit-code behavior
+
+| Import response | Effect on `pytest`'s exit code |
+|---|---|
+| `201` — every test matched | Untouched; a summary is printed to stderr. |
+| `207` — some tests unmatched | Untouched by default (a warning is printed, naming the unmatched case keys and `--testpulse-fail-on-unmatched` as the escalation path). Set `--testpulse-fail-on-unmatched` to make this a hard failure instead. |
+| Network error, auth failure, non-2xx | **Always** fails the session — this isn't suppressible, since a broken submission is a different problem than an incomplete case-annotation rollout. |
+
+## Dry run
+
+`--testpulse-dry-run` previews which annotated case keys would match, via a
+**read-only** fetch of the project's cases — it never calls the import
+endpoint, never creates a run, and never affects the exit code:
+
+```bash
+pytest --junitxml=report.xml --testpulse-dry-run
+```
+
+## Attachments
+
+Call the `testpulse_attach` fixture from inside a marked test to attach a
+screenshot or file to its case:
+
+```python
+@pytest.mark.testpulse("LOGIN-42")
+def test_login_succeeds(testpulse_attach):
+    ...
+    testpulse_attach("failure.png")
+```
+
+Calling it on a test with no `@pytest.mark.testpulse` marker drops the
+attachment with a warning — there's no case key to attach it to. If a
+marked test's case comes back unmatched in a `207` response, its attachment
+is named separately in the warning output, distinct from the plain
+unmatched-case listing.
+
+## License
+
+MIT

pytest_testpulse-1.0.0/README.md

@@ -0,0 +1,97 @@
+# pytest-testpulse
+
+A pytest plugin that reports test results into [TestPulse](https://github.com/Barayo/TestPulse)
+via its JUnit-XML import API, matching each test to an existing case by key.
+
+## Install
+
+```bash
+pip install pytest-testpulse
+```
+
+## Usage
+
+Mark a test with the case key it corresponds to in TestPulse:
+
+```python
+import pytest
+
+@pytest.mark.testpulse("LOGIN-42", platform="linux", tags=["smoke"])
+def test_login_succeeds():
+    ...
+```
+
+Run with `--junitxml` — the plugin reads pytest's own JUnit XML output rather
+than generating it itself, so this flag is required whenever the marker (or
+`--testpulse-dry-run`) is in use:
+
+```bash
+pytest --junitxml=report.xml
+```
+
+At the end of the session, the plugin submits `report.xml` to
+`POST /api/v1/projects/{project}/imports` and prints a summary. A suite with
+no marked tests and no `--testpulse-dry-run` needs no configuration at all —
+the plugin does nothing.
+
+## Configuration
+
+Each setting resolves in this order: **CLI flag › environment variable ›
+`pytest.ini`/`pyproject.toml` option** — the first one present wins.
+
+| Setting | CLI flag | Env var | ini-option |
+|---|---|---|---|
+| API base URL | `--testpulse-url` | `TESTPULSE_URL` | `testpulse_url` |
+| API token | `--testpulse-token` | `TESTPULSE_TOKEN` | `testpulse_token` |
+| Project key | `--testpulse-project` | `TESTPULSE_PROJECT` | `testpulse_project` |
+| Fail on unmatched | `--testpulse-fail-on-unmatched` / `--testpulse-no-fail-on-unmatched` | `TESTPULSE_FAIL_ON_UNMATCHED` | `testpulse_fail_on_unmatched` |
+
+`TESTPULSE_URL`/`TESTPULSE_TOKEN` match the env var names TestPulse's own
+docs already use for the raw `conftest.py` snippet, so migrating from that
+snippet to this plugin doesn't require renaming CI secrets. Put your token in
+an env var or CI secret — not in a committed ini-option.
+
+`testpulse_fail_on_unmatched` (env var and ini-option) accepts
+`1`/`true`/`yes` (case-insensitive) as true; anything else, including unset,
+is false. `--testpulse-no-fail-on-unmatched` overrides an ini-option or env
+var set to true, for a single local run.
+
+## Exit-code behavior
+
+| Import response | Effect on `pytest`'s exit code |
+|---|---|
+| `201` — every test matched | Untouched; a summary is printed to stderr. |
+| `207` — some tests unmatched | Untouched by default (a warning is printed, naming the unmatched case keys and `--testpulse-fail-on-unmatched` as the escalation path). Set `--testpulse-fail-on-unmatched` to make this a hard failure instead. |
+| Network error, auth failure, non-2xx | **Always** fails the session — this isn't suppressible, since a broken submission is a different problem than an incomplete case-annotation rollout. |
+
+## Dry run
+
+`--testpulse-dry-run` previews which annotated case keys would match, via a
+**read-only** fetch of the project's cases — it never calls the import
+endpoint, never creates a run, and never affects the exit code:
+
+```bash
+pytest --junitxml=report.xml --testpulse-dry-run
+```
+
+## Attachments
+
+Call the `testpulse_attach` fixture from inside a marked test to attach a
+screenshot or file to its case:
+
+```python
+@pytest.mark.testpulse("LOGIN-42")
+def test_login_succeeds(testpulse_attach):
+    ...
+    testpulse_attach("failure.png")
+```
+
+Calling it on a test with no `@pytest.mark.testpulse` marker drops the
+attachment with a warning — there's no case key to attach it to. If a
+marked test's case comes back unmatched in a `207` response, its attachment
+is named separately in the warning output, distinct from the plain
+unmatched-case listing.
+
+## License
+
+MIT

pytest_testpulse-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytest-testpulse"
+version = "1.0.0"
+description = "Report pytest results into TestPulse via its JUnit-XML import API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "TestPulse" }]
+classifiers = [
+    "Framework :: Pytest",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "pytest>=7.0",
+    "requests>=2.28",
+]
+
+[project.urls]
+Homepage = "https://github.com/Barayo/pytest-testpulse"
+
+[project.entry-points.pytest11]
+testpulse = "pytest_testpulse.plugin"
+
+[project.optional-dependencies]
+dev = [
+    "responses>=0.23",
+    "pytest-cov>=4.0",
+    "python-semantic-release>=9.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+commit_message = "chore(release): {version}"
+build_command = "pip install build && python -m build"
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[tool.semantic_release.remote.token]
+env = "GH_TOKEN"

pytest_testpulse-1.0.0/setup.cfg

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

pytest_testpulse-1.0.0/src/pytest_testpulse/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

pytest_testpulse-1.0.0/src/pytest_testpulse/plugin.py

@@ -0,0 +1,373 @@
+"""pytest plugin: link tests to TestPulse cases and report results on import."""
+
+import base64
+import mimetypes
+import os
+import sys
+
+import pytest
+import requests
+
+
+class ReportUnavailable(Exception):
+    """Raised when the --junitxml report is missing or unreadable at session end."""
+
+
+def _read_report(xmlpath):
+    if not xmlpath or not os.path.isfile(xmlpath):
+        raise ReportUnavailable(
+            f"pytest-testpulse: expected report at {xmlpath!r} but it does not "
+            "exist. This usually means the run was interrupted before pytest's "
+            "own --junitxml writer finished."
+        )
+    with open(xmlpath, "r", encoding="utf-8") as fh:
+        return fh.read()
+
+
+_SETTINGS = {
+    "url": ("testpulse_url", "TESTPULSE_URL", "testpulse_url"),
+    "token": ("testpulse_token", "TESTPULSE_TOKEN", "testpulse_token"),
+    "project": ("testpulse_project", "TESTPULSE_PROJECT", "testpulse_project"),
+}
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup("testpulse")
+    group.addoption(
+        "--testpulse-url", dest="testpulse_url", default=None,
+        help="TestPulse API base URL",
+    )
+    group.addoption(
+        "--testpulse-token", dest="testpulse_token", default=None,
+        help="TestPulse API token",
+    )
+    group.addoption(
+        "--testpulse-project", dest="testpulse_project", default=None,
+        help="TestPulse project key",
+    )
+    group.addoption(
+        "--testpulse-fail-on-unmatched", dest="testpulse_fail_on_unmatched",
+        action="store_true", default=None,
+        help="Fail the session when the import reports unmatched tests (207)",
+    )
+    group.addoption(
+        "--testpulse-no-fail-on-unmatched", dest="testpulse_fail_on_unmatched",
+        action="store_false",
+        help="Do not fail the session on unmatched tests, overriding config",
+    )
+    group.addoption(
+        "--testpulse-dry-run", dest="testpulse_dry_run",
+        action="store_true", default=False,
+        help="Preview matches via a read-only cases fetch, without submitting",
+    )
+
+    parser.addini("testpulse_url", help="TestPulse API base URL", default=None)
+    parser.addini("testpulse_token", help="TestPulse API token", default=None)
+    parser.addini("testpulse_project", help="TestPulse project key", default=None)
+    parser.addini(
+        "testpulse_fail_on_unmatched",
+        help="Fail the session when the import reports unmatched tests (207)",
+        default=None,
+    )
+
+
+def resolve_setting(config, name):
+    option_dest, env_var, ini_name = _SETTINGS[name]
+
+    cli_value = getattr(config.option, option_dest, None)
+    if cli_value:
+        return cli_value
+
+    env_value = os.environ.get(env_var)
+    if env_value:
+        return env_value
+
+    ini_value = config.getini(ini_name)
+    if ini_value:
+        return ini_value
+
+    return None
+
+
+_TRUTHY = {"1", "true", "yes"}
+
+
+def _parse_bool(value):
+    if value is None:
+        return False
+    return str(value).strip().lower() in _TRUTHY
+
+
+def resolve_fail_on_unmatched(config):
+    cli_value = getattr(config.option, "testpulse_fail_on_unmatched", None)
+    if cli_value is not None:
+        return bool(cli_value)
+
+    env_value = os.environ.get("TESTPULSE_FAIL_ON_UNMATCHED")
+    if env_value is not None:
+        return _parse_bool(env_value)
+
+    ini_value = config.getini("testpulse_fail_on_unmatched")
+    if ini_value:
+        return _parse_bool(ini_value)
+
+    return False
+
+
+def pytest_configure(config):
+    config.addinivalue_line(
+        "markers",
+        "testpulse(case_key, platform=None, version=None, tags=None): "
+        "link this test to a TestPulse case for result import",
+    )
+    config._testpulse_attachment_warnings = []
+
+
+def _plugin_is_active(config, items):
+    if getattr(config.option, "testpulse_dry_run", False):
+        return True
+    return any(item.get_closest_marker("testpulse") is not None for item in items)
+
+
+def pytest_collection_modifyitems(config, items):
+    if not _plugin_is_active(config, items):
+        return
+
+    if not config.option.xmlpath:
+        raise pytest.UsageError(
+            "pytest-testpulse: --junitxml is required when using "
+            "@pytest.mark.testpulse or --testpulse-dry-run (the plugin reads "
+            "pytest's own JUnit XML output rather than generating it)."
+        )
+
+    for name in ("url", "token", "project"):
+        if resolve_setting(config, name) is None:
+            option_dest, env_var, ini_name = _SETTINGS[name]
+            raise pytest.UsageError(
+                f"pytest-testpulse: missing required setting {name!r}. Set it via "
+                f"--{option_dest.replace('_', '-')}, the {env_var} environment "
+                f"variable, or the {ini_name} ini-option."
+            )
+
+    config._testpulse_marked_items = [
+        item for item in items if item.get_closest_marker("testpulse") is not None
+    ]
+    config._testpulse_attachments = []
+
+
+def _import_endpoint(url, project):
+    return f"{url.rstrip('/')}/api/v1/projects/{project}/imports"
+
+
+def _submit_report(config, report, attachments):
+    url = resolve_setting(config, "url")
+    token = resolve_setting(config, "token")
+    project = resolve_setting(config, "project")
+
+    payload = {"format": "junit-xml", "report": report}
+    if attachments:
+        payload["attachments"] = attachments
+
+    return requests.post(
+        _import_endpoint(url, project),
+        json=payload,
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=30,
+    )
+
+
+def _cases_endpoint(url, project):
+    return f"{url.rstrip('/')}/api/v1/projects/{project}/cases"
+
+
+def _marked_case_keys(marked_items):
+    keys = []
+    for item in marked_items:
+        marker = item.get_closest_marker("testpulse")
+        case_key = marker.args[0] if marker.args else marker.kwargs.get("case_key")
+        if case_key:
+            keys.append(case_key)
+    return keys
+
+
+def _run_dry_run(config, marked_items):
+    url = resolve_setting(config, "url")
+    token = resolve_setting(config, "token")
+    project = resolve_setting(config, "project")
+
+    try:
+        response = requests.get(
+            _cases_endpoint(url, project),
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30,
+        )
+    except requests.RequestException as exc:
+        print(f"pytest-testpulse: dry-run cases fetch failed: {exc}", file=sys.stderr)
+        return False
+
+    if response.status_code != 200:
+        print(
+            f"pytest-testpulse: dry-run cases fetch failed "
+            f"({response.status_code}): {response.text}",
+            file=sys.stderr,
+        )
+        return False
+
+    existing_keys = {case.get("key") for case in response.json()}
+    annotated_keys = _marked_case_keys(marked_items)
+    matched = [key for key in annotated_keys if key in existing_keys]
+    unmatched = [key for key in annotated_keys if key not in existing_keys]
+
+    for key in matched:
+        print(f"pytest-testpulse: dry-run: {key} would match", file=sys.stdout)
+    for key in unmatched:
+        print(f"pytest-testpulse: dry-run: {key} would be unmatched", file=sys.stdout)
+
+    return True
+
+
+def pytest_sessionfinish(session, exitstatus):
+    config = session.config
+
+    for warning in getattr(config, "_testpulse_attachment_warnings", []):
+        print(warning, file=sys.stderr)
+
+    marked_items = getattr(config, "_testpulse_marked_items", None)
+    if getattr(config.option, "testpulse_dry_run", False):
+        ok = _run_dry_run(config, marked_items or [])
+        if not ok:
+            session.exitstatus = 1
+        return
+    if not marked_items:
+        return
+
+    try:
+        report = _read_report(config.option.xmlpath)
+    except ReportUnavailable as exc:
+        print(str(exc), file=sys.stderr)
+        session.exitstatus = 1
+        return
+
+    attachments = getattr(config, "_testpulse_attachments", [])
+
+    try:
+        response = _submit_report(config, report, attachments)
+    except requests.RequestException as exc:
+        print(f"pytest-testpulse: submission failed: {exc}", file=sys.stderr)
+        session.exitstatus = 1
+        return
+
+    total = len(marked_items)
+
+    if response.status_code == 201:
+        # The 201 body is the created Run object directly (importResults'
+        # 201 response schema is a bare $ref: Run, not {"run": ...}).
+        run = response.json()
+        print(
+            f"pytest-testpulse: {total}/{total} matched, "
+            f"run {run.get('key', run.get('id', '?'))} created",
+            file=sys.stderr,
+        )
+        return
+
+    if response.status_code == 207:
+        body = response.json()
+        run = body.get("run", {})
+        unmatched = body.get("unmatched", [])
+        matched = body.get("matched", total - len(unmatched))
+        unmatched_keys = {entry.get("caseKey") for entry in unmatched}
+        unmatched_list = ", ".join(sorted(k for k in unmatched_keys if k))
+        print(
+            f"pytest-testpulse: {matched}/{total} matched, "
+            f"run {run.get('key', run.get('id', '?'))} created. "
+            f"Unmatched: {unmatched_list}. Re-run with "
+            "--testpulse-fail-on-unmatched to make this a hard failure.",
+            file=sys.stderr,
+        )
+        dropped_attachment_keys = sorted(
+            {a.get("caseKey") for a in attachments if a.get("caseKey") in unmatched_keys}
+        )
+        for key in dropped_attachment_keys:
+            print(
+                f"pytest-testpulse: {key} is unmatched, and its attachment "
+                "was not saved.",
+                file=sys.stderr,
+            )
+        if resolve_fail_on_unmatched(config):
+            session.exitstatus = 1
+        return
+
+    print(
+        f"pytest-testpulse: submission rejected ({response.status_code}): "
+        f"{response.text}",
+        file=sys.stderr,
+    )
+    session.exitstatus = 1
+
+
+@pytest.fixture(autouse=True)
+def _testpulse_case_link(request, record_property):
+    marker = request.node.get_closest_marker("testpulse")
+    if marker is None:
+        return
+
+    case_key = marker.args[0] if marker.args else marker.kwargs.get("case_key")
+    if case_key:
+        record_property("testpulse_case_key", case_key)
+
+    platform = marker.kwargs.get("platform")
+    if platform:
+        record_property("testpulse_platform", platform)
+
+    version = marker.kwargs.get("version")
+    if version:
+        record_property("testpulse_version", version)
+
+    tags = marker.kwargs.get("tags")
+    if tags:
+        record_property("testpulse_tags", ",".join(tags))
+
+
+def _attachment_bytes(path_or_bytes):
+    if isinstance(path_or_bytes, (bytes, bytearray)):
+        return bytes(path_or_bytes)
+    with open(path_or_bytes, "rb") as fh:
+        return fh.read()
+
+
+@pytest.fixture
+def testpulse_attach(request):
+    def _attach(path_or_bytes, filename=None, content_type=None):
+        marker = request.node.get_closest_marker("testpulse")
+        case_key = None
+        if marker is not None:
+            case_key = marker.args[0] if marker.args else marker.kwargs.get("case_key")
+
+        if not case_key:
+            request.config._testpulse_attachment_warnings.append(
+                f"pytest-testpulse: testpulse_attach() called on "
+                f"{request.node.nodeid} with no @pytest.mark.testpulse marker; "
+                "dropping attachment (no case key to attach it to)."
+            )
+            return
+
+        if filename is None:
+            filename = (
+                os.path.basename(path_or_bytes)
+                if isinstance(path_or_bytes, str)
+                else "attachment"
+            )
+        if content_type is None:
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+        data = _attachment_bytes(path_or_bytes)
+        request.config._testpulse_attachments.append(
+            {
+                "caseKey": case_key,
+                "filename": filename,
+                "contentType": content_type,
+                "data": base64.b64encode(data).decode("ascii"),
+            }
+        )
+
+    return _attach