pytest-charisma 0.3.1__py3-none-any.whl

pytest_charisma/__init__.py

@@ -0,0 +1,3 @@
+"""pytest-charisma: A pytest plugin that streams test results to the Charisma ingestion API."""
+
+__version__ = "0.3.1"

pytest_charisma/client.py

@@ -0,0 +1,121 @@
+"""HTTP client wrapper for Charisma API communication.
+
+Provides CharismaClient for opening launches and flushing test result batches
+to the Charisma streaming ingestion API. Uses httpx with connection pooling
+and configured timeouts.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger("pytest-charisma")
+
+
+class CharismaClient:
+    """HTTP client for the Charisma ingestion API.
+
+    Wraps httpx.Client with connection pooling, Bearer token auth,
+    and configured timeouts (5s connect, 10s read).
+
+    Args:
+        base_url: Base URL of the Charisma API (e.g. "https://api.charisma.dev").
+        token: Bearer token for API authentication.
+    """
+
+    CONNECT_TIMEOUT = 5.0
+    READ_TIMEOUT = 10.0
+
+    def __init__(self, base_url: str, token: str) -> None:
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            timeout=httpx.Timeout(self.CONNECT_TIMEOUT, read=self.READ_TIMEOUT),
+        )
+
+    def open_launch(self, payload: dict) -> str:
+        """Open a new launch session.
+
+        POST /api/v1/launches with the given payload. Returns the launchId
+        from the response body. Raises on any non-2xx response or missing launchId.
+
+        Args:
+            payload: Launch request body containing projectAlias, expectedTests,
+                and optional fields (buildId, commitSha, branch, etc.).
+
+        Returns:
+            The launchId string from the API response.
+
+        Raises:
+            httpx.HTTPStatusError: On non-2xx response status.
+            ValueError: If the response body does not contain a launchId.
+        """
+        url = "/api/v1/launches"
+        response = self._http.post(url, json=payload)
+        if response.status_code >= 400:
+            logger.warning("open_launch failed: status=%d, body=%s", response.status_code, response.text[:500])
+        response.raise_for_status()
+        data = response.json()
+        launch_id = data.get("launchId")
+        if not launch_id:
+            raise ValueError(f"API response missing 'launchId': {data}")
+        return launch_id
+
+    def flush_batch(self, launch_id: str, results: list[dict]) -> bool:
+        """Flush a batch of test results to the API.
+
+        POST /api/v1/launches/{launch_id}/results with results wrapped in
+        a {"results": [...]} payload. Returns True on HTTP 200, False on
+        any failure (HTTP errors, network errors). Never raises.
+
+        Args:
+            launch_id: The launch session ID to append results to.
+            results: List of serialized test result dicts.
+
+        Returns:
+            True if the API returned 200, False otherwise.
+        """
+        try:
+            response = self._http.post(
+                f"/api/v1/launches/{launch_id}/results",
+                json={"results": results},
+            )
+            if response.status_code != 200:
+                logger.warning("flush_batch got status=%d, body=%s", response.status_code, response.text[:200])
+            return response.status_code == 200
+        except Exception as e:
+            logger.warning("flush_batch exception: %s", e)
+            return False
+
+    def close_launch(self, launch_id: str) -> bool:
+        """Close a streaming launch, finalizing its status.
+
+        POST /api/v1/launches/{launch_id}/close. Signals the API that no more
+        results will be sent and the launch should compute its final status
+        from whatever results were received. Idempotent.
+
+        Args:
+            launch_id: The launch session ID to close.
+
+        Returns:
+            True if the API returned 200, False otherwise.
+        """
+        try:
+            response = self._http.post(
+                f"/api/v1/launches/{launch_id}/close",
+            )
+            if response.status_code != 200:
+                logger.warning("close_launch got status=%d, body=%s", response.status_code, response.text[:200])
+            return response.status_code == 200
+        except Exception as e:
+            logger.warning("close_launch exception: %s", e)
+            return False
+
+    def close(self) -> None:
+        """Close the underlying httpx.Client and release connection pool."""
+        self._http.close()

pytest_charisma/config.py

@@ -0,0 +1,265 @@
+"""Configuration resolution for pytest-charisma.
+
+Resolves plugin configuration from three sources with priority: CLI > ini > env.
+Emits pytest warnings for missing required fields and clamps batch_size to [1, 50].
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+from dataclasses import dataclass
+
+import pytest
+
+logger = logging.getLogger("pytest-charisma")
+
+# ---------------------------------------------------------------------------
+# Configuration option descriptors
+# ---------------------------------------------------------------------------
+
+# Each tuple: (field_name, cli_flag, ini_key, env_var)
+_OPTIONS: list[tuple[str, str, str, str]] = [
+    ("url", "--charisma-url", "charisma_url", "CHARISMA_URL"),
+    ("token", "--charisma-token", "charisma_token", "CHARISMA_TOKEN"),
+    ("project_alias", "--charisma-project-alias", "charisma_project_alias", "CHARISMA_PROJECT_ALIAS"),
+    ("batch_size", "--charisma-batch-size", "charisma_batch_size", "CHARISMA_BATCH_SIZE"),
+    ("build_id", "--charisma-build-id", "charisma_build_id", "CHARISMA_BUILD_ID"),
+    ("commit_sha", "--charisma-commit-sha", "charisma_commit_sha", "CHARISMA_COMMIT_SHA"),
+    ("branch", "--charisma-branch", "charisma_branch", "CHARISMA_BRANCH"),
+    ("component_alias", "--charisma-component", "charisma_component", "CHARISMA_COMPONENT"),
+    ("source_url", "--charisma-source-url", "charisma_source_url", "CHARISMA_SOURCE_URL"),
+]
+
+
+# ---------------------------------------------------------------------------
+# CharismaConfig dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CharismaConfig:
+    """Immutable configuration for the pytest-charisma plugin.
+
+    All fields are resolved from CLI > ini > env priority via the resolve() classmethod.
+    """
+
+    url: str
+    token: str
+    project_alias: str
+    batch_size: int = 20
+    build_id: str | None = None
+    commit_sha: str | None = None
+    branch: str | None = None
+    component_alias: str | None = None
+    source_url: str | None = None
+
+    @classmethod
+    def resolve(cls, config: pytest.Config) -> CharismaConfig | None:
+        """Resolve configuration from CLI > ini > env with priority.
+
+        Returns None if plugin should be disabled (missing url or required fields).
+        Emits pytest warnings for validation issues.
+
+        Args:
+            config: The pytest Config object providing getoption() and getini().
+
+        Returns:
+            A CharismaConfig instance if all required fields are present, else None.
+        """
+        resolved: dict[str, str | None] = {}
+
+        for field_name, cli_flag, ini_key, env_var in _OPTIONS:
+            value = _resolve_option(config, cli_flag, ini_key, env_var)
+            resolved[field_name] = value
+
+        # --- URL check: if absent, plugin is silently disabled ---
+        url = resolved["url"]
+        if not url:
+            return None
+
+        # --- Token check: emit warning if missing ---
+        token = resolved["token"]
+        if not token:
+            logger.warning("token missing — plugin DISABLED")
+            warnings.warn(
+                "charisma: token is required when url is configured. Plugin disabled.",
+                pytest.PytestConfigWarning,
+                stacklevel=2,
+            )
+            return None
+
+        # --- Project alias check: emit warning if missing ---
+        project_alias = resolved["project_alias"]
+        if not project_alias:
+            logger.warning("project_alias missing — plugin DISABLED")
+            warnings.warn(
+                "charisma: project alias is required when url is configured. Plugin disabled.",
+                pytest.PytestConfigWarning,
+                stacklevel=2,
+            )
+            return None
+
+        # --- Batch size: parse and clamp to [1, 50] ---
+        batch_size = _parse_batch_size(resolved["batch_size"])
+
+        return cls(
+            url=url,
+            token=token,
+            project_alias=project_alias,
+            batch_size=batch_size,
+            build_id=resolved["build_id"] or None,
+            commit_sha=resolved["commit_sha"] or None,
+            branch=resolved["branch"] or None,
+            component_alias=resolved["component_alias"] or None,
+            source_url=resolved["source_url"] or None,
+        )
+
+
+# ---------------------------------------------------------------------------
+# CLI option registration helper
+# ---------------------------------------------------------------------------
+
+
+def register_cli_options(parser: pytest.Parser) -> None:
+    """Register all --charisma-* CLI options and ini values with pytest.
+
+    Called from pytest_addoption hook in plugin.py.
+
+    Args:
+        parser: The pytest argument parser.
+    """
+    group = parser.getgroup("charisma", "Charisma test reporting")
+
+    group.addoption(
+        "--charisma-url",
+        dest="charisma_url",
+        default=None,
+        help="Charisma API base URL",
+    )
+    group.addoption(
+        "--charisma-token",
+        dest="charisma_token",
+        default=None,
+        help="Charisma API authentication token",
+    )
+    group.addoption(
+        "--charisma-project-alias",
+        dest="charisma_project_alias",
+        default=None,
+        help="Charisma project alias",
+    )
+    group.addoption(
+        "--charisma-batch-size",
+        dest="charisma_batch_size",
+        default=None,
+        help="Number of results per batch (1-50, default: 20)",
+    )
+    group.addoption(
+        "--charisma-build-id",
+        dest="charisma_build_id",
+        default=None,
+        help="Build identifier (e.g., CI build number)",
+    )
+    group.addoption(
+        "--charisma-commit-sha",
+        dest="charisma_commit_sha",
+        default=None,
+        help="Git commit SHA",
+    )
+    group.addoption(
+        "--charisma-branch",
+        dest="charisma_branch",
+        default=None,
+        help="Git branch name",
+    )
+    group.addoption(
+        "--charisma-component",
+        dest="charisma_component",
+        default=None,
+        help="Component alias within the project",
+    )
+    group.addoption(
+        "--charisma-source-url",
+        dest="charisma_source_url",
+        default=None,
+        help="CI/CD source URL for this run",
+    )
+
+    # Register ini values
+    parser.addini("charisma_url", help="Charisma API base URL", default="")
+    parser.addini("charisma_token", help="Charisma API authentication token", default="")
+    parser.addini("charisma_project_alias", help="Charisma project alias", default="")
+    parser.addini("charisma_batch_size", help="Number of results per batch (1-50)", default="")
+    parser.addini("charisma_build_id", help="Build identifier", default="")
+    parser.addini("charisma_commit_sha", help="Git commit SHA", default="")
+    parser.addini("charisma_branch", help="Git branch name", default="")
+    parser.addini("charisma_component", help="Component alias", default="")
+    parser.addini("charisma_source_url", help="CI/CD source URL", default="")
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_option(
+    config: pytest.Config,
+    cli_flag: str,
+    ini_key: str,
+    env_var: str,
+) -> str | None:
+    """Resolve a single option from CLI > ini > env.
+
+    Returns the first non-None, non-empty value found, or None.
+    """
+    # 1. CLI argument (highest priority)
+    cli_value = config.getoption(cli_flag, default=None)
+    if cli_value is not None and str(cli_value).strip():
+        return str(cli_value).strip()
+
+    # 2. ini value (medium priority)
+    ini_value = config.getini(ini_key)
+    if ini_value is not None and str(ini_value).strip():
+        return str(ini_value).strip()
+
+    # 3. Environment variable (lowest priority)
+    env_value = os.environ.get(env_var)
+    if env_value is not None and env_value.strip():
+        return env_value.strip()
+
+    return None
+
+
+def _parse_batch_size(raw: str | None) -> int:
+    """Parse and clamp batch_size to [1, 50].
+
+    Returns 20 (default) if raw is None or not a valid integer.
+    Emits a pytest warning if clamping occurs.
+    """
+    if raw is None:
+        return 20
+
+    try:
+        value = int(raw)
+    except (ValueError, TypeError):
+        return 20
+
+    if value < 1:
+        warnings.warn(
+            f"charisma: batch_size {value} is below minimum, clamped to 1.",
+            pytest.PytestConfigWarning,
+            stacklevel=3,
+        )
+        return 1
+
+    if value > 50:
+        warnings.warn(
+            f"charisma: batch_size {value} exceeds maximum, clamped to 50.",
+            pytest.PytestConfigWarning,
+            stacklevel=3,
+        )
+        return 50
+
+    return value

pytest_charisma/models.py

@@ -0,0 +1,120 @@
+"""Data classes for test result payloads.
+
+Provides TestResultPayload dataclass and mapping from pytest report objects
+to the Charisma API result schema.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+
+
+@dataclass
+class TestResultPayload:
+    """A single test result payload for the Charisma streaming API.
+
+    Attributes:
+        testId: Pytest nodeid (e.g., "tests/test_login.py::TestAuth::test_valid").
+        outcome: Mapped outcome (passed, failed, skipped, broken).
+        duration_ms: Test duration in milliseconds (rounded).
+        started_at: ISO 8601 UTC timestamp when the test started.
+        ended_at: ISO 8601 UTC timestamp when the test ended.
+        error_message: Error description on failure/broken, None otherwise.
+        stack_trace: Full traceback on failure/broken, None otherwise.
+        stdout: Captured stdout if non-empty, None otherwise.
+        stderr: Captured stderr if non-empty, None otherwise.
+    """
+
+    testId: str
+    outcome: str
+    duration_ms: int
+    started_at: str
+    ended_at: str
+    error_message: str | None = None
+    stack_trace: str | None = None
+    stdout: str | None = None
+    stderr: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dict for JSON encoding, omitting None fields."""
+        d: dict[str, Any] = {
+            "testId": self.testId,
+            "outcome": self.outcome,
+            "duration_ms": self.duration_ms,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+        }
+        if self.error_message is not None:
+            d["error_message"] = self.error_message
+        if self.stack_trace is not None:
+            d["stack_trace"] = self.stack_trace
+        if self.stdout is not None:
+            d["stdout"] = self.stdout
+        if self.stderr is not None:
+            d["stderr"] = self.stderr
+        return d
+
+
+def _map_outcome(when: str, outcome: str) -> str:
+    """Map pytest report phase and outcome to Charisma outcome.
+
+    Only call/failed and setup|teardown/failed are meaningful for the API.
+    Setup/teardown failures map to 'broken'. Call-phase outcomes pass through.
+
+    Args:
+        when: The pytest report phase (setup, call, teardown).
+        outcome: The pytest outcome (passed, failed, skipped).
+
+    Returns:
+        Charisma outcome string (passed, failed, skipped, broken).
+    """
+    if when in ("setup", "teardown") and outcome == "failed":
+        return "broken"
+    return outcome
+
+
+def map_report_to_payload(report: Any, started_at: datetime) -> TestResultPayload:
+    """Map a pytest TestReport to a TestResultPayload.
+
+    Args:
+        report: A pytest TestReport (or mock with nodeid, when, outcome,
+                duration, longrepr, capstdout, capstderr attributes).
+        started_at: The UTC datetime when the test started executing.
+
+    Returns:
+        A TestResultPayload ready for serialization and API submission.
+    """
+    outcome = _map_outcome(report.when, report.outcome)
+    duration_ms = round(report.duration * 1000)
+
+    started_at_str = started_at.isoformat()
+    ended_at = started_at + timedelta(seconds=report.duration)
+    ended_at_str = ended_at.isoformat()
+
+    # Capture error info only on failure or broken outcomes
+    error_message: str | None = None
+    stack_trace: str | None = None
+    if outcome in ("failed", "broken") and report.longrepr is not None:
+        longrepr_str = str(report.longrepr)
+        # error_message: last line (the actual error), stack_trace: full repr
+        lines = longrepr_str.strip().splitlines()
+        error_message = lines[-1] if lines else longrepr_str
+        stack_trace = longrepr_str
+
+    # Capture stdout/stderr only if non-empty
+    stdout: str | None = report.capstdout if report.capstdout else None
+    stderr: str | None = report.capstderr if report.capstderr else None
+
+    return TestResultPayload(
+        testId=report.nodeid,
+        outcome=outcome,
+        duration_ms=duration_ms,
+        started_at=started_at_str,
+        ended_at=ended_at_str,
+        error_message=error_message,
+        stack_trace=stack_trace,
+        stdout=stdout,
+        stderr=stderr,
+    )

pytest_charisma/plugin.py

@@ -0,0 +1,536 @@
+"""Pytest hooks and plugin entry point for pytest-charisma.
+
+Supports both single-process and pytest-xdist parallel execution.
+In xdist mode, the controller opens the launch and shares the launch_id
+with workers via workerinput. Each worker streams results independently
+to the shared launch.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import sys
+from datetime import datetime, timezone
+
+import pytest
+
+from pytest_charisma.client import CharismaClient
+from pytest_charisma.config import CharismaConfig, register_cli_options
+from pytest_charisma.models import TestResultPayload, map_report_to_payload
+from pytest_charisma.worker import BackgroundWorker
+
+logger = logging.getLogger("pytest-charisma")
+
+
+def _setup_logging() -> None:
+    """Configure pytest-charisma logger to output to stderr at INFO level.
+
+    Ensures logs are always visible in CI regardless of pytest capture settings.
+    Only adds a handler if one hasn't been added already.
+    """
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(logging.Formatter("[%(name)s] %(message)s"))
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register all --charisma-* CLI options and ini values."""
+    register_cli_options(parser)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Resolve config and register the appropriate plugin variant.
+
+    Routes to CharismaWorkerPlugin (xdist worker), CharismaControllerPlugin
+    (xdist controller), or CharismaPlugin (single-process) based on the
+    detected execution mode.
+    """
+    _setup_logging()
+
+    charisma_config = CharismaConfig.resolve(config)
+    if charisma_config is None:
+        return
+
+    is_worker = _is_xdist_worker(config)
+    is_controller = _is_xdist_controller(config)
+
+    if is_worker:
+        plugin = CharismaWorkerPlugin(charisma_config)
+        config.pluginmanager.register(plugin, "charisma-plugin")
+    elif is_controller:
+        plugin = CharismaControllerPlugin(charisma_config)
+        config.pluginmanager.register(plugin, "charisma-plugin")
+        logger.info(
+            "config: url=%s, project=%s, component=%s, batch_size=%d",
+            charisma_config.url,
+            charisma_config.project_alias,
+            charisma_config.component_alias or "—",
+            charisma_config.batch_size,
+        )
+    else:
+        plugin = CharismaPlugin(charisma_config)
+        config.pluginmanager.register(plugin, "charisma-plugin")
+        logger.info(
+            "config: url=%s, project=%s, component=%s, batch_size=%d",
+            charisma_config.url,
+            charisma_config.project_alias,
+            charisma_config.component_alias or "—",
+            charisma_config.batch_size,
+        )
+
+
+# ---------------------------------------------------------------------------
+# xdist detection helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_xdist_worker(config: pytest.Config) -> bool:
+    """Return True if running as a pytest-xdist worker process.
+
+    xdist sets config.workerinput as a dict on worker processes.
+    We check both existence and that it's a dict to avoid false positives
+    with mock objects.
+    """
+    workerinput = getattr(config, "workerinput", None)
+    return isinstance(workerinput, dict)
+
+
+def _is_xdist_controller(config: pytest.Config) -> bool:
+    """Return True if running as a pytest-xdist controller process.
+
+    Checks that xdist is loaded AND tests will actually be distributed
+    (numprocesses > 0 or numprocesses == "auto"). This avoids false positives
+    when xdist is installed but not active (no -n flag).
+    """
+    try:
+        has_xdist = config.pluginmanager.hasplugin("xdist")
+        if not has_xdist:
+            return False
+        # xdist is installed but might not be active (e.g., -p no:xdist or no -n flag)
+        num_processes = getattr(config.option, "numprocesses", None)
+        if num_processes is None:
+            return False
+        # numprocesses can be "auto" (str) or an int; must be a real value
+        if isinstance(num_processes, str):
+            return not _is_xdist_worker(config)
+        if isinstance(num_processes, int):
+            return num_processes > 0 and not _is_xdist_worker(config)
+        # Unexpected type (e.g., MagicMock) — not xdist
+        return False
+    except AttributeError:
+        logger.warning("xdist detection failed (missing attribute)")
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_launch_payload(config: CharismaConfig, expected_tests: int) -> dict[str, str | int]:
+    """Build the open-launch request payload from config.
+
+    Args:
+        config: Resolved CharismaConfig instance.
+        expected_tests: Number of collected test items.
+
+    Returns:
+        Dict payload for the open-launch API call.
+    """
+    payload: dict[str, str | int] = {
+        "projectAlias": config.project_alias,
+        "expectedTests": expected_tests,
+    }
+    if config.build_id:
+        payload["buildId"] = config.build_id
+    if config.commit_sha:
+        payload["commitSha"] = config.commit_sha
+    if config.branch:
+        payload["branch"] = config.branch
+    if config.component_alias:
+        payload["componentAlias"] = config.component_alias
+    if config.source_url:
+        payload["sourceUrl"] = config.source_url
+    return payload
+
+
+# ---------------------------------------------------------------------------
+# Streaming mixin (shared report handling + session finish logic)
+# ---------------------------------------------------------------------------
+
+
+class _StreamingMixin:
+    """Shared logic for plugins that stream test results.
+
+    Provides report buffering, batch flushing, and session finish handling.
+    Subclasses must set _config, _worker, _launch_id, _buffer, _start_times.
+    """
+
+    _config: CharismaConfig
+    _worker: BackgroundWorker | None
+    _launch_id: str | None
+    _buffer: list[TestResultPayload]
+    _start_times: dict[str, datetime]
+    _is_launch_owner: bool  # True for single-process plugin, False for xdist workers
+    _results_count: int
+    _reported_nodeids: set  # Track which tests were actually reported
+    _collected_nodeids: list  # All collected test item nodeids
+    _session_finished: bool  # Guard against double-flush (atexit + sessionfinish)
+
+    def _atexit_flush(self) -> None:
+        """Emergency flush called by atexit — sends any buffered results.
+
+        Registered via ``atexit.register`` in ``__init__``. When pytest crashes
+        (segfault, KeyboardInterrupt, worker killed), pytest_sessionfinish may
+        never fire, so this handler ensures buffered results are flushed to the
+        server before the process exits.
+        """
+        if getattr(self, "_session_finished", False):
+            return  # Already handled by pytest_sessionfinish
+        try:
+            self._handle_session_finish()
+        except Exception:
+            # Best-effort — don't crash during interpreter shutdown
+            pass
+
+    def _handle_report(self, report: pytest.TestReport) -> None:
+        """Process a test report — buffer and flush at batch_size threshold."""
+        # Process: call phase (any outcome), setup/teardown failures, setup skips.
+        # Setup skips represent tests that never reach the call phase (e.g., skip
+        # markers, xfail during fixture) — they must be counted toward expectedTests
+        # so the launch can transition out of 'receiving' state.
+        if (
+            report.when == "call"
+            or (report.when == "setup" and report.outcome in ("failed", "skipped"))
+            or (report.when == "teardown" and report.outcome == "failed")
+        ):
+            pass
+        else:
+            return
+
+        # Skip if streaming is not active
+        if self._launch_id is None or self._worker is None:
+            return
+
+        # Get start time (fallback to now if not recorded)
+        started_at = self._start_times.get(report.nodeid, datetime.now(timezone.utc))
+
+        # Map report to payload and remove consumed start time
+        payload = map_report_to_payload(report, started_at)
+        self._start_times.pop(report.nodeid, None)
+        self._buffer.append(payload)
+        self._results_count += 1
+        self._reported_nodeids.add(report.nodeid)
+
+        # Flush at batch_size threshold
+        if len(self._buffer) >= self._config.batch_size:
+            batch = self._buffer[:]
+            self._buffer.clear()
+            self._worker.submit_batch(batch)
+
+    def _handle_session_finish(self) -> None:
+        """Flush remaining buffer, report unreported skips, close launch, stop worker."""
+        if getattr(self, "_session_finished", False):
+            return  # Already handled (guard against double-call from atexit)
+        self._session_finished = True
+
+        if self._worker is None:
+            return
+
+        # Flush remaining buffer (only if non-empty)
+        if self._buffer:
+            batch = self._buffer[:]
+            self._buffer.clear()
+            self._worker.submit_batch(batch)
+
+        # Report unreported tests as skipped — ONLY for single-process mode.
+        # In xdist, each worker collects ALL items but executes only a subset,
+        # so _collected_nodeids contains tests assigned to OTHER workers.
+        # Backfilling those would overwrite real results from other workers.
+        if getattr(self, "_is_launch_owner", False):
+            unreported = [nid for nid in getattr(self, "_collected_nodeids", []) if nid not in self._reported_nodeids]
+            if unreported:
+                now = datetime.now(timezone.utc).isoformat()
+                skip_batch = [
+                    TestResultPayload(
+                        testId=nid,
+                        outcome="skipped",
+                        duration_ms=0,
+                        started_at=now,
+                        ended_at=now,
+                        error_message=None,
+                        stack_trace=None,
+                        stdout=None,
+                        stderr=None,
+                    )
+                    for nid in unreported
+                ]
+                for i in range(0, len(skip_batch), self._config.batch_size):
+                    self._worker.submit_batch(skip_batch[i : i + self._config.batch_size])
+                self._results_count += len(unreported)
+                logger.info("reported %d unreported tests as skipped", len(unreported))
+
+        # Stop worker with 30s timeout (ensures all batches are flushed)
+        self._worker.stop(timeout=30.0)
+        if self._results_count > 0:
+            logger.info("dumped %d test results", self._results_count)
+
+        # Close the launch to finalize status (handles expected_tests mismatch)
+        # Only the launch owner (single-process or xdist controller) closes.
+        # Must use a FRESH client because worker.stop() closes the shared one.
+        if self._launch_id and getattr(self, "_is_launch_owner", False):
+            from pytest_charisma.client import CharismaClient
+
+            close_client = CharismaClient(self._config.url, self._config.token)
+            try:
+                success = close_client.close_launch(self._launch_id)
+                if success:
+                    logger.info("launch closed: id=%s", self._launch_id)
+                else:
+                    logger.warning("close_launch failed for id=%s", self._launch_id)
+            finally:
+                close_client.close()
+
+
+# ---------------------------------------------------------------------------
+# Single-process plugin (original behavior)
+# ---------------------------------------------------------------------------
+
+
+class CharismaPlugin(_StreamingMixin):
+    """Pytest plugin that streams test results to the Charisma API.
+
+    Used in single-process mode (no xdist). Opens a launch after collection,
+    batches results during execution, and flushes at session end.
+
+    Args:
+        config: Resolved CharismaConfig instance.
+    """
+
+    def __init__(self, config: CharismaConfig) -> None:
+        self._config = config
+        self._client: CharismaClient | None = None
+        self._worker: BackgroundWorker | None = None
+        self._launch_id: str | None = None
+        self._buffer: list[TestResultPayload] = []
+        self._start_times: dict[str, datetime] = {}
+        self._results_count: int = 0
+        self._is_launch_owner: bool = True  # Single-process owns the launch
+        self._reported_nodeids: set[str] = set()
+        self._collected_nodeids: list[str] = []
+        self._session_finished: bool = False
+        atexit.register(self._atexit_flush)
+
+    def pytest_runtest_logstart(self, nodeid: str, location: tuple[str, int | None, str]) -> None:
+        """Record test start time."""
+        self._start_times[nodeid] = datetime.now(timezone.utc)
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        """Capture test results and batch them."""
+        try:
+            self._handle_report(report)
+        except Exception:
+            logger.warning("error processing report", exc_info=True)
+
+    def pytest_collection_modifyitems(self, config: pytest.Config, items: list[pytest.Item]) -> None:
+        """Open launch session after collection."""
+        try:
+            self._handle_collection(items)
+        except Exception:
+            logger.warning("error during collection hook", exc_info=True)
+
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        """Flush remaining buffer and drain worker."""
+        try:
+            self._handle_session_finish()
+        except Exception:
+            logger.warning("error during session finish", exc_info=True)
+
+    def _handle_collection(self, items: list[pytest.Item]) -> None:
+        """Open launch session after collection (internal)."""
+        if not items:
+            return
+
+        # Track collected nodeids for unreported-skip detection at session end
+        self._collected_nodeids = [item.nodeid for item in items]
+
+        client = CharismaClient(self._config.url, self._config.token)
+        payload = _build_launch_payload(self._config, len(items))
+
+        try:
+            launch_id = client.open_launch(payload)
+        except Exception:
+            logger.warning("open-launch FAILED, streaming disabled", exc_info=True)
+            client.close()
+            return
+
+        self._client = client
+        self._launch_id = launch_id
+        logger.info("launch opened: id=%s (%d tests, single-process)", launch_id, len(items))
+
+        # Create and start worker
+        worker = BackgroundWorker(client, launch_id)
+        worker.start()
+        self._worker = worker
+
+
+# ---------------------------------------------------------------------------
+# xdist controller plugin
+# ---------------------------------------------------------------------------
+
+
+class CharismaControllerPlugin:
+    """Pytest plugin for the xdist controller process.
+
+    Opens the launch eagerly in pytest_configure_node (first call) by
+    performing a manual test collection to get the accurate test count.
+    This is necessary because xdist does not collect on the controller —
+    workers collect independently — but we need the count before workers
+    spawn to pass launch_id via workerinput.
+
+    Args:
+        config: Resolved CharismaConfig instance.
+    """
+
+    def __init__(self, config: CharismaConfig) -> None:
+        self._config = config
+        self._client: CharismaClient | None = None
+        self._launch_id: str | None = None
+        self._launch_opened = False
+
+    def pytest_configure_node(self, node: object) -> None:
+        """Open launch on first call (with real test count), pass launch_id to workers.
+
+        Args:
+            node: xdist WorkerController instance.
+        """
+        if not self._launch_opened:
+            self._launch_opened = True
+            self._open_launch_with_collection(node)
+
+        if self._launch_id is not None:
+            node.workerinput["charisma_launch_id"] = self._launch_id  # type: ignore[attr-defined]
+
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        """Close the launch and HTTP client on the controller when session ends."""
+        if self._client is not None:
+            # Close the launch to finalize status
+            if self._launch_id:
+                success = self._client.close_launch(self._launch_id)
+                if success:
+                    logger.info("launch closed by controller: id=%s", self._launch_id)
+                else:
+                    logger.warning("close_launch failed for id=%s", self._launch_id)
+            self._client.close()
+
+    def _open_launch_with_collection(self, node: object) -> None:
+        """Collect tests manually to get count, then open launch."""
+        config = node.config  # type: ignore[attr-defined]
+        test_count = self._collect_test_count(config)
+        if test_count == 0:
+            return
+
+        client = CharismaClient(self._config.url, self._config.token)
+        payload = _build_launch_payload(self._config, expected_tests=test_count)
+
+        try:
+            launch_id = client.open_launch(payload)
+        except Exception:
+            logger.warning("open-launch FAILED, streaming disabled", exc_info=True)
+            client.close()
+            return
+
+        self._client = client
+        self._launch_id = launch_id
+        logger.info("launch opened: id=%s (%d tests, xdist controller)", launch_id, test_count)
+
+    def _collect_test_count(self, config: pytest.Config) -> int:
+        """Collect tests using the existing session to get item count."""
+        try:
+            session = config.pluginmanager.get_plugin("session")
+            if session is None:
+                return 0
+            session.perform_collect()
+            return len(session.items)
+        except Exception:
+            logger.warning("manual collection failed", exc_info=True)
+            return 0
+
+
+# ---------------------------------------------------------------------------
+# xdist worker plugin
+# ---------------------------------------------------------------------------
+
+
+class CharismaWorkerPlugin(_StreamingMixin):
+    """Pytest plugin for xdist worker processes.
+
+    Receives the launch_id from the controller via workerinput and streams
+    test results to the shared launch. Each worker has its own HTTP client
+    and BackgroundWorker thread.
+
+    Args:
+        config: Resolved CharismaConfig instance.
+    """
+
+    def __init__(self, config: CharismaConfig) -> None:
+        self._config = config
+        self._client: CharismaClient | None = None
+        self._worker: BackgroundWorker | None = None
+        self._launch_id: str | None = None
+        self._buffer: list[TestResultPayload] = []
+        self._start_times: dict[str, datetime] = {}
+        self._results_count: int = 0
+        self._is_launch_owner: bool = False  # Workers don't own the launch
+        self._reported_nodeids: set[str] = set()
+        self._collected_nodeids: list[str] = []
+        self._session_finished: bool = False
+        atexit.register(self._atexit_flush)
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_collection_modifyitems(self, config: pytest.Config, items: list[pytest.Item]) -> None:
+        """Initialize streaming on the worker after collection."""
+        try:
+            self._collected_nodeids = [item.nodeid for item in items]
+            self._initialize_from_workerinput(config)
+        except Exception:
+            logger.warning("worker initialization failed", exc_info=True)
+
+    def pytest_runtest_logstart(self, nodeid: str, location: tuple[str, int | None, str]) -> None:
+        """Record test start time."""
+        self._start_times[nodeid] = datetime.now(timezone.utc)
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        """Capture test results and batch them."""
+        try:
+            self._handle_report(report)
+        except Exception:
+            logger.warning("[worker] error processing report", exc_info=True)
+
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        """Flush remaining buffer and drain worker."""
+        try:
+            self._handle_session_finish()
+        except Exception:
+            logger.warning("[worker] error during session finish", exc_info=True)
+
+    def _initialize_from_workerinput(self, config: pytest.Config) -> None:
+        """Read launch_id from workerinput and start streaming."""
+        workerinput = getattr(config, "workerinput", None)
+        if workerinput is None:
+            return
+
+        launch_id = workerinput.get("charisma_launch_id")
+        if not launch_id:
+            return
+
+        client = CharismaClient(self._config.url, self._config.token)
+        self._client = client
+        self._launch_id = launch_id
+
+        worker = BackgroundWorker(client, launch_id)
+        worker.start()
+        self._worker = worker

pytest_charisma/worker.py

@@ -0,0 +1,154 @@
+"""Background worker thread for batching and flushing results.
+
+Provides BackgroundWorker class that processes test result batches
+in a daemon thread, with retry logic and circuit-breaker behavior.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+
+from pytest_charisma.client import CharismaClient
+from pytest_charisma.models import TestResultPayload
+
+logger = logging.getLogger("pytest-charisma")
+
+
+class BackgroundWorker:
+    """Background daemon thread that flushes test result batches to the API.
+
+    Dequeues batches from a thread-safe queue, serializes them, and sends
+    via CharismaClient. Implements retry-once and circuit-breaker (3 consecutive
+    failures → disabled).
+
+    Args:
+        client: CharismaClient instance for HTTP communication.
+        launch_id: The launch session ID for append requests.
+    """
+
+    MAX_CONSECUTIVE_FAILURES = 3
+
+    def __init__(self, client: CharismaClient, launch_id: str) -> None:
+        self._queue: queue.Queue[list[TestResultPayload] | None] = queue.Queue()
+        self._client = client
+        self._launch_id = launch_id
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._consecutive_failures = 0
+        self._lock = threading.Lock()
+        self._disabled = False
+        self._dropped_count = 0
+
+    def start(self) -> None:
+        """Start the daemon worker thread."""
+        self._thread.start()
+
+    def submit_batch(self, batch: list[TestResultPayload]) -> None:
+        """Enqueue a batch for flushing. Non-blocking.
+
+        Does nothing if the worker is disabled (circuit breaker tripped).
+
+        Args:
+            batch: List of TestResultPayload items to flush.
+        """
+        with self._lock:
+            if not self._disabled:
+                self._queue.put(batch)
+
+    def stop(self, timeout: float = 30.0) -> None:
+        """Signal stop and wait for drain up to timeout seconds.
+
+        Sends a sentinel (None) to the queue and joins the worker thread.
+
+        Args:
+            timeout: Maximum seconds to wait for the thread to finish.
+        """
+        self._queue.put(None)  # Sentinel
+        self._thread.join(timeout=timeout)
+
+    @property
+    def dropped_count(self) -> int:
+        """Number of test results discarded due to flush failures."""
+        return self._dropped_count
+
+    def _run(self) -> None:
+        """Worker loop: dequeue batches, flush, handle failures."""
+        try:
+            while True:
+                try:
+                    batch = self._queue.get(timeout=1.0)
+                except queue.Empty:
+                    continue
+
+                if batch is None:
+                    # Sentinel received — process remaining items then exit
+                    self._drain_remaining()
+                    break
+
+                if self._disabled:
+                    break
+
+                self._flush_with_retry(batch)
+
+                if self._disabled:
+                    break
+        except Exception:
+            logger.warning("pytest-charisma: worker thread crashed", exc_info=True)
+        finally:
+            self._client.close()
+
+    def _drain_remaining(self) -> None:
+        """Process any remaining batches in the queue after sentinel."""
+        while True:
+            try:
+                batch = self._queue.get_nowait()
+            except queue.Empty:
+                break
+            if batch is None:
+                break
+            if self._disabled:
+                break
+            self._flush_with_retry(batch)
+
+    def _flush_with_retry(self, batch: list[TestResultPayload]) -> None:
+        """Flush a batch with one retry on failure.
+
+        On success: resets consecutive failure counter.
+        On double failure: discards batch, increments counter, checks circuit breaker.
+
+        Args:
+            batch: List of TestResultPayload items to flush.
+        """
+        results = [result.to_dict() for result in batch]
+
+        success = self._client.flush_batch(self._launch_id, results)
+        if success:
+            self._consecutive_failures = 0
+            logger.info("pytest-charisma: flushed %d results successfully", len(results))
+            return
+
+        # Retry once
+        success = self._client.flush_batch(self._launch_id, results)
+        if success:
+            self._consecutive_failures = 0
+            return
+
+        # Both attempts failed — discard batch
+        self._dropped_count += len(batch)
+        self._consecutive_failures += 1
+        logger.warning(
+            "pytest-charisma: discarded %d results after retry failure "
+            "(consecutive failures: %d)",
+            len(batch),
+            self._consecutive_failures,
+        )
+
+        if self._consecutive_failures >= self.MAX_CONSECUTIVE_FAILURES:
+            with self._lock:
+                self._disabled = True
+            logger.warning(
+                "pytest-charisma: circuit breaker tripped after %d consecutive failures, "
+                "streaming disabled",
+                self._consecutive_failures,
+            )

pytest_charisma-0.3.1.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: pytest-charisma
+Version: 0.3.1
+Summary: A pytest plugin that streams test results to the Charisma ingestion API as tests execute.
+Author: Charisma Team
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.24
+Requires-Dist: pytest<10.0,>=7.0
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-charisma
+
+A pytest plugin that streams test results to the Charisma ingestion API as tests execute.
+
+Results are batched and sent in a background thread so test execution is not blocked by network I/O. The plugin implements retry-once semantics and a circuit breaker (3 consecutive failures disables streaming for the rest of the session).
+
+## Installation
+
+```bash
+pip install pytest-charisma
+```
+
+No token, no index URL — works on any laptop and in any CI. The package is published to public PyPI; the Charisma repo itself stays private (only this client plugin wheel is public).
+
+For local development from a checkout of the repo:
+
+```bash
+pip install -e packages/pytest-charisma
+```
+
+## Publishing (maintainers)
+
+Releases publish to public PyPI automatically from the merge-queue workflow using a **PyPI API token**.
+
+> Trusted publishing (OIDC) is not used because this repo runs on **GitHub Enterprise Server**, whose OIDC issuer PyPI does not trust. A stored API token is required instead.
+
+One-time setup (done once by a PyPI project owner):
+
+1. Sign in to [PyPI](https://pypi.org) with the team-owned account (2FA enabled).
+2. Go to **Account settings → API tokens → Add API token**. Scope it to the `pytest-charisma` project once the project exists; for the very first publish use an account-scoped token, then re-scope it to the project afterward.
+3. Copy the token (starts with `pypi-`).
+4. In the GitHub Enterprise repo, add it as an Actions secret named **`PYPI_API_TOKEN`** (org-level secret recommended so both packages share it).
+5. Bump `version` in `pyproject.toml` and merge — the workflow builds and publishes on the next release.
+
+Rotate the token periodically and store it in the team secret manager.
+
+---
+
+## Quick start
+
+```bash
+pytest \
+  --charisma-url https://api.charisma.example.com \
+  --charisma-token $CHARISMA_TOKEN \
+  --charisma-project-alias my-project
+```
+
+The plugin activates automatically when `charisma_url` is configured. If the URL is absent, the plugin stays silent and does nothing.
+
+## Configuration
+
+Options are resolved with priority: **CLI flag > pytest.ini / pyproject.toml > environment variable**.
+
+| CLI flag                   | ini key                  | Env var                  | Required | Description                           |
+| -------------------------- | ------------------------ | ------------------------ | -------- | ------------------------------------- |
+| `--charisma-url`           | `charisma_url`           | `CHARISMA_URL`           | Yes      | API base URL                          |
+| `--charisma-token`         | `charisma_token`         | `CHARISMA_TOKEN`         | Yes      | Bearer token for authentication       |
+| `--charisma-project-alias` | `charisma_project_alias` | `CHARISMA_PROJECT_ALIAS` | Yes      | Project alias in Charisma             |
+| `--charisma-batch-size`    | `charisma_batch_size`    | `CHARISMA_BATCH_SIZE`    | No       | Results per batch, 1–50 (default: 20) |
+| `--charisma-build-id`      | `charisma_build_id`      | `CHARISMA_BUILD_ID`      | No       | CI build number or identifier         |
+| `--charisma-commit-sha`    | `charisma_commit_sha`    | `CHARISMA_COMMIT_SHA`    | No       | Git commit SHA                        |
+| `--charisma-branch`        | `charisma_branch`        | `CHARISMA_BRANCH`        | No       | Git branch name                       |
+| `--charisma-component`     | `charisma_component`     | `CHARISMA_COMPONENT`     | No       | Component alias within the project    |
+| `--charisma-source-url`    | `charisma_source_url`    | `CHARISMA_SOURCE_URL`    | No       | Link back to CI/CD run                |
+
+## Configuration via pyproject.toml
+
+```toml
+[tool.pytest.ini_options]
+charisma_url = "https://api.charisma.example.com"
+charisma_project_alias = "my-project"
+charisma_batch_size = "10"
+charisma_branch = "main"
+# Token should come from env var for security:
+# export CHARISMA_TOKEN=your-token
+```
+
+## Configuration via pytest.ini
+
+```ini
+[pytest]
+charisma_url = https://api.charisma.example.com
+charisma_project_alias = my-project
+charisma_batch_size = 10
+```
+
+## Environment variables only (CI-friendly)
+
+```bash
+export CHARISMA_URL=https://api.charisma.example.com
+export CHARISMA_TOKEN=your-api-token
+export CHARISMA_PROJECT_ALIAS=my-project
+export CHARISMA_BUILD_ID=$CI_BUILD_NUMBER
+export CHARISMA_COMMIT_SHA=$CI_COMMIT_SHA
+export CHARISMA_BRANCH=$CI_BRANCH
+export CHARISMA_SOURCE_URL=$CI_BUILD_URL
+
+pytest
+```
+
+## How it works
+
+1. **Collection** — After pytest collects tests, the plugin opens a launch session via `POST /api/v1/launches`.
+2. **Execution** — As each test completes, results are buffered. When the buffer reaches `batch_size`, the batch is submitted to a background worker thread.
+3. **Flush** — At session end, remaining results are flushed and the worker drains its queue (up to 30s timeout).
+4. **Resilience** — Each batch gets one retry on failure. After 3 consecutive batch failures, the circuit breaker trips and streaming is disabled for the rest of the session. Test execution is never affected.
+
+## Outcome mapping
+
+| pytest outcome            | Charisma status |
+| ------------------------- | --------------- |
+| `passed` (call phase)     | `passed`        |
+| `failed` (call phase)     | `failed`        |
+| `skipped`                 | `skipped`       |
+| `failed` (setup/teardown) | `broken`        |
+
+## Requirements
+
+- Python ≥ 3.10
+- pytest ≥ 7.0, < 9.0
+- httpx ≥ 0.24, < 1.0
+
+## Development
+
+```bash
+cd packages/pytest-charisma
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pytest_charisma-0.3.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+pytest_charisma/__init__.py,sha256=ek63G-CfvPcr5gwZT6FD7FQkKYZDj4Zzrfqr9K43bnM,119
+pytest_charisma/client.py,sha256=xuCA0rSMhK_RYH4_gk_XnjKrrfhzMZeR7Ir8zNaaU9Y,4349
+pytest_charisma/config.py,sha256=yQdeZwIC5AaUyRR8OZ10FmMKiKeedVV61of0UBFQLcc,8830
+pytest_charisma/models.py,sha256=KdnGD_m9wbaC8dU-7FGchV2zD2Wq3DF7QcWIV9wwcYs,4246
+pytest_charisma/plugin.py,sha256=0Mj07OAdwV3lejTC23hUg0QvNT5Wa_sTrUveZwPbpNM,21260
+pytest_charisma/worker.py,sha256=O2EyKZrJxacHgYAJMPZDb4y2NadKU9U96TZkmh5C4iM,5076
+pytest_charisma-0.3.1.dist-info/METADATA,sha256=MxOCkMzWzNU19aLH8xqGUE51XM26qennllfwQJQ37UI,6502
+pytest_charisma-0.3.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pytest_charisma-0.3.1.dist-info/entry_points.txt,sha256=RWB7HLn1ohGG-50fppgwicuRqHj8iVLJ9gkpajsN62k,45
+pytest_charisma-0.3.1.dist-info/RECORD,,

pytest_charisma-0.3.1.dist-info/WHEEL

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

pytest_charisma-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+charisma = pytest_charisma.plugin