tusk-drift-python-sdk 0.1.22__tar.gz → 0.1.24__tar.gz

{tusk_drift_python_sdk-0.1.22 → tusk_drift_python_sdk-0.1.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tusk-drift-python-sdk
-Version: 0.1.22
+Version: 0.1.24
 Summary: Python SDK for Tusk Drift instrumentation and replay
 Author-email: Tusk <support@usetusk.ai>
 License: Apache-2.0
@@ -23,10 +23,10 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: protobuf>=6.0
+Requires-Dist: protobuf>=3.20.0
 Requires-Dist: PyYAML>=6.0
-Requires-Dist: requests>=2.32.5
-Requires-Dist: tusk-drift-schemas>=0.1.24
+Requires-Dist: requests>=2.28.0
+Requires-Dist: tusk-drift-schemas>=0.1.34
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: aiofiles>=23.0.0
 Requires-Dist: opentelemetry-api>=1.20.0
@@ -41,8 +41,10 @@ Requires-Dist: uvicorn>=0.34.2; extra == "fastapi"
 Requires-Dist: starlette<0.42.0; extra == "fastapi"
 Provides-Extra: django
 Requires-Dist: Django>=4.2; extra == "django"
+Provides-Extra: coverage
+Requires-Dist: coverage>=7.0.0; extra == "coverage"
 Provides-Extra: rust
-Requires-Dist: drift-core-python>=0.1.7; extra == "rust"
+Requires-Dist: drift-core-python>=0.1.9; extra == "rust"
 Provides-Extra: dev
 Requires-Dist: Flask>=3.1.2; extra == "dev"
 Requires-Dist: fastapi>=0.115.6; extra == "dev"
@@ -61,13 +63,13 @@ Dynamic: license-file
 
 <p align="center">
   <a href="https://pypi.org/project/tusk-drift-python-sdk/"><img src="https://img.shields.io/pypi/v/tusk-drift-python-sdk" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/tusk-drift-python-sdk/"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/tusk-drift-python-sdk"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
-  <a href="https://github.com/Use-Tusk/drift-python-sdk/commits/main/"><img src="https://img.shields.io/github/last-commit/Use-Tusk/drift-python-sdk" alt="GitHub last commit"></a>
   <a href="https://x.com/usetusk"><img src="https://img.shields.io/twitter/url?url=https%3A%2F%2Fx.com%2Fusetusk&style=flat&logo=x&label=Tusk&color=BF40BF" alt="Tusk X account"></a>
   <a href="https://join.slack.com/t/tusk-community/shared_invite/zt-3fve1s7ie-NAAUn~UpHsf1m_2tdoGjsQ"><img src="https://img.shields.io/badge/slack-badge?style=flat&logo=slack&label=Tusk&color=BF40BF" alt="Tusk Community Slack"></a>
 </p>
 
-The Python Tusk Drift SDK enables fast and deterministic API testing by capturing and replaying API calls made to/from your service. Automatically record real-world API calls, then replay them as tests using the [Tusk CLI](https://github.com/Use-Tusk/tusk-drift-cli) to find regressions. During replay, all outbound requests are intercepted with recorded data to ensure consistent behavior without side-effects.
+The Python Tusk Drift SDK enables fast and deterministic API testing by capturing and replaying API calls made to/from your service. Automatically record real-world API calls, then replay them as tests using the [Tusk CLI](https://github.com/Use-Tusk/tusk-cli) to find regressions. During replay, all outbound requests are intercepted with recorded data to ensure consistent behavior without side-effects.
 
 <div align="center">
 
@@ -124,7 +126,7 @@ If you're using packages or versions not listed above, please create an issue wi
 
 ### Step 1: Install the CLI
 
-First, install the Tusk Drift CLI by following our [CLI installation guide](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#install).
+First, install the Tusk Drift CLI by following our [CLI installation guide](https://github.com/Use-Tusk/tusk-cli?tab=readme-ov-file#install).
 
 ### Step 2: Set up Tusk Drift
 
@@ -135,7 +137,7 @@ Use our AI agent to automatically set up Tusk Drift for your service:
 ```bash
 cd path/to/your/service
 export ANTHROPIC_API_KEY=your-api-key
-tusk setup
+tusk drift setup
 ```
 
 The agent will analyze your codebase, install the SDK, instrument it into your application, create configuration files, and test the setup with recording and replay.
@@ -156,7 +158,7 @@ Alternatively, you can set up Tusk Drift manually:
 
    *For more information about Rust acceleration, refer to [this doc](docs/rust-core-bindings).*
 
-2. Create configuration: Run `tusk init` to create your `.tusk/config.yaml` config file interactively, or create it manually per the [configuration docs](https://github.com/Use-Tusk/tusk-drift-cli/blob/main/docs/configuration.md).
+2. Create configuration: Run `tusk init` to create your `.tusk/config.yaml` config file interactively, or create it manually per the [configuration docs](https://github.com/Use-Tusk/tusk-cli/blob/main/docs/drift/configuration.md).
 
 3. Initialize the SDK: Refer to the [initialization guide](docs/initialization.md) to instrument the SDK in your service.
 

{tusk_drift_python_sdk-0.1.22 → tusk_drift_python_sdk-0.1.24}/README.md

@@ -4,13 +4,13 @@
 
 <p align="center">
   <a href="https://pypi.org/project/tusk-drift-python-sdk/"><img src="https://img.shields.io/pypi/v/tusk-drift-python-sdk" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/tusk-drift-python-sdk/"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/tusk-drift-python-sdk"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
-  <a href="https://github.com/Use-Tusk/drift-python-sdk/commits/main/"><img src="https://img.shields.io/github/last-commit/Use-Tusk/drift-python-sdk" alt="GitHub last commit"></a>
   <a href="https://x.com/usetusk"><img src="https://img.shields.io/twitter/url?url=https%3A%2F%2Fx.com%2Fusetusk&style=flat&logo=x&label=Tusk&color=BF40BF" alt="Tusk X account"></a>
   <a href="https://join.slack.com/t/tusk-community/shared_invite/zt-3fve1s7ie-NAAUn~UpHsf1m_2tdoGjsQ"><img src="https://img.shields.io/badge/slack-badge?style=flat&logo=slack&label=Tusk&color=BF40BF" alt="Tusk Community Slack"></a>
 </p>
 
-The Python Tusk Drift SDK enables fast and deterministic API testing by capturing and replaying API calls made to/from your service. Automatically record real-world API calls, then replay them as tests using the [Tusk CLI](https://github.com/Use-Tusk/tusk-drift-cli) to find regressions. During replay, all outbound requests are intercepted with recorded data to ensure consistent behavior without side-effects.
+The Python Tusk Drift SDK enables fast and deterministic API testing by capturing and replaying API calls made to/from your service. Automatically record real-world API calls, then replay them as tests using the [Tusk CLI](https://github.com/Use-Tusk/tusk-cli) to find regressions. During replay, all outbound requests are intercepted with recorded data to ensure consistent behavior without side-effects.
 
 <div align="center">
 
@@ -67,7 +67,7 @@ If you're using packages or versions not listed above, please create an issue wi
 
 ### Step 1: Install the CLI
 
-First, install the Tusk Drift CLI by following our [CLI installation guide](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#install).
+First, install the Tusk Drift CLI by following our [CLI installation guide](https://github.com/Use-Tusk/tusk-cli?tab=readme-ov-file#install).
 
 ### Step 2: Set up Tusk Drift
 
@@ -78,7 +78,7 @@ Use our AI agent to automatically set up Tusk Drift for your service:
 ```bash
 cd path/to/your/service
 export ANTHROPIC_API_KEY=your-api-key
-tusk setup
+tusk drift setup
 ```
 
 The agent will analyze your codebase, install the SDK, instrument it into your application, create configuration files, and test the setup with recording and replay.
@@ -99,7 +99,7 @@ Alternatively, you can set up Tusk Drift manually:
 
    *For more information about Rust acceleration, refer to [this doc](docs/rust-core-bindings).*
 
-2. Create configuration: Run `tusk init` to create your `.tusk/config.yaml` config file interactively, or create it manually per the [configuration docs](https://github.com/Use-Tusk/tusk-drift-cli/blob/main/docs/configuration.md).
+2. Create configuration: Run `tusk init` to create your `.tusk/config.yaml` config file interactively, or create it manually per the [configuration docs](https://github.com/Use-Tusk/tusk-cli/blob/main/docs/drift/configuration.md).
 
 3. Initialize the SDK: Refer to the [initialization guide](docs/initialization.md) to instrument the SDK in your service.
 

{tusk_drift_python_sdk-0.1.22 → tusk_drift_python_sdk-0.1.24}/drift/core/communication/__init__.py

@@ -6,28 +6,18 @@ for replay testing. Communication uses Protocol Buffers over Unix sockets or TCP
 
 from .communicator import CommunicatorConfig, ProtobufCommunicator
 from .types import (
-    CliMessage,
-    CLIMessageType,
     ConnectRequest,
     ConnectResponse,
     GetMockRequest,
     GetMockResponse,
-    MessageType,
     MockRequestInput,
     MockResponseOutput,
-    # Protobuf types (re-exported)
-    SdkMessage,
-    SDKMessageType,
     dict_to_span,
     extract_response_data,
     span_to_proto,
 )
 
 __all__ = [
-    # Message types
-    "MessageType",
-    "SDKMessageType",
-    "CLIMessageType",
     # Request/Response types
     "ConnectRequest",
     "ConnectResponse",
@@ -35,9 +25,6 @@ __all__ = [
     "GetMockResponse",
     "MockRequestInput",
     "MockResponseOutput",
-    # Protobuf types
-    "SdkMessage",
-    "CliMessage",
     # Utilities
     "span_to_proto",
     "dict_to_span",

{tusk_drift_python_sdk-0.1.22 → tusk_drift_python_sdk-0.1.24}/drift/core/communication/communicator.py

@@ -10,24 +10,31 @@ import traceback
 from dataclasses import dataclass
 from typing import Any
 
-from tusk.drift.core.v1 import GetMockRequest as ProtoGetMockRequest
+from tusk.drift.core.v1 import (
+    BranchInfo,
+    CliMessage,
+    CoverageSnapshotResponse,
+    FileCoverageData,
+    InstrumentationVersionMismatchAlert,
+    MessageType,
+    SdkMessage,
+    SendAlertRequest,
+    SendInboundSpanForReplayRequest,
+    SetTimeTravelResponse,
+    UnpatchedDependencyAlert,
+)
+from tusk.drift.core.v1 import (
+    GetMockRequest as ProtoGetMockRequest,
+)
 
 from ...version import MIN_CLI_VERSION, SDK_VERSION
 from ..span_serialization import clean_span_to_proto
 from ..types import CleanSpanData, calling_library_context
 from .types import (
-    CliMessage,
     ConnectRequest,
     GetMockRequest,
-    InstrumentationVersionMismatchAlert,
-    MessageType,
     MockRequestInput,
     MockResponseOutput,
-    SdkMessage,
-    SendAlertRequest,
-    SendInboundSpanForReplayRequest,
-    SetTimeTravelResponse,
-    UnpatchedDependencyAlert,
     span_to_proto,
 )
 
@@ -750,6 +757,10 @@ class ProtobufCommunicator:
                     self._handle_set_time_travel_sync(cli_message)
                     continue
 
+                if cli_message.type == MessageType.COVERAGE_SNAPSHOT:
+                    self._handle_coverage_snapshot_sync(cli_message)
+                    continue
+
                 # Route responses to waiting callers by request_id
                 request_id = cli_message.request_id
                 if request_id:
@@ -774,8 +785,8 @@ class ProtobufCommunicator:
 
     def _handle_set_time_travel_sync(self, cli_message: CliMessage) -> None:
         """Handle SetTimeTravel request from CLI and send response."""
-        request = cli_message.set_time_travel_request
-        if not request:
+        request = getattr(cli_message, "set_time_travel_request", None)
+        if request is None:
             return
 
         logger.debug(
@@ -809,6 +820,57 @@ class ProtobufCommunicator:
         except Exception as e:
             logger.error(f"Failed to send SetTimeTravel response: {e}")
 
+    def _handle_coverage_snapshot_sync(self, cli_message: CliMessage) -> None:
+        """Handle CoverageSnapshot request from CLI and send response."""
+        request = getattr(cli_message, "coverage_snapshot_request", None)
+        if request is None:
+            return
+
+        logger.debug(f"Received CoverageSnapshot request: baseline={request.baseline}")
+
+        try:
+            from ..coverage_server import take_coverage_snapshot
+
+            result = take_coverage_snapshot(request.baseline)
+
+            # Convert to protobuf
+            coverage: dict[str, FileCoverageData] = {}
+            for file_path, file_data in result.items():
+                branches: dict[str, BranchInfo] = {}
+                for line, branch_info in file_data.get("branches", {}).items():
+                    branches[line] = BranchInfo(
+                        total=branch_info.get("total", 0),
+                        covered=branch_info.get("covered", 0),
+                    )
+
+                coverage[file_path] = FileCoverageData(
+                    lines=file_data.get("lines", {}),
+                    total_branches=file_data.get("totalBranches", 0),
+                    covered_branches=file_data.get("coveredBranches", 0),
+                    branches=branches,
+                )
+
+            response = CoverageSnapshotResponse(
+                success=True,
+                error="",
+                coverage=coverage,
+            )
+        except Exception as e:
+            logger.error(f"Failed to take coverage snapshot: {e}")
+            response = CoverageSnapshotResponse(success=False, error=str(e))
+
+        sdk_message = SdkMessage(
+            type=MessageType.COVERAGE_SNAPSHOT,
+            request_id=cli_message.request_id,
+            coverage_snapshot_response=response,
+        )
+
+        try:
+            self._send_message_sync(sdk_message)
+            logger.debug(f"Sent CoverageSnapshot response: success={response.success}")
+        except Exception as e:
+            logger.error(f"[coverage] Failed to send response: {e}")
+
     def _send_message_sync(self, message: SdkMessage) -> None:
         """Send a message synchronously on the main socket."""
         if not self._socket:

{tusk_drift_python_sdk-0.1.22 → tusk_drift_python_sdk-0.1.24}/drift/core/communication/types.py

@@ -12,20 +12,6 @@ The protocol uses:
 from __future__ import annotations
 
 __all__ = [
-    # Re-exported protobuf types
-    "CliMessage",
-    "InstrumentationVersionMismatchAlert",
-    "MessageType",
-    "Runtime",
-    "SdkMessage",
-    "SendAlertRequest",
-    "SendInboundSpanForReplayRequest",
-    "SetTimeTravelRequest",
-    "SetTimeTravelResponse",
-    "UnpatchedDependencyAlert",
-    # Aliases
-    "SDKMessageType",
-    "CLIMessageType",
     # Dataclasses
     "ConnectRequest",
     "ConnectResponse",
@@ -42,18 +28,6 @@ __all__ = [
 from dataclasses import dataclass, field
 from typing import Any
 
-from tusk.drift.core.v1 import (
-    CliMessage,
-    InstrumentationVersionMismatchAlert,
-    MessageType,
-    Runtime,
-    SdkMessage,
-    SendAlertRequest,
-    SendInboundSpanForReplayRequest,
-    SetTimeTravelRequest,
-    SetTimeTravelResponse,
-    UnpatchedDependencyAlert,
-)
 from tusk.drift.core.v1 import (
     ConnectRequest as ProtoConnectRequest,
 )
@@ -66,6 +40,9 @@ from tusk.drift.core.v1 import (
 from tusk.drift.core.v1 import (
     GetMockResponse as ProtoGetMockResponse,
 )
+from tusk.drift.core.v1 import (
+    Runtime,
+)
 from tusk.drift.core.v1 import (
     Span as ProtoSpan,
 )
@@ -79,9 +56,6 @@ from tusk.drift.core.v1 import (
     StatusCode as ProtoStatusCode,
 )
 
-SDKMessageType = MessageType
-CLIMessageType = MessageType
-
 
 def _python_to_value(value: Any) -> Any:
     """Convert Python value to protobuf Value."""

{tusk_drift_python_sdk-0.1.22 → tusk_drift_python_sdk-0.1.24}/drift/core/content_type_utils.py

@@ -111,7 +111,7 @@ CONTENT_TYPE_MAPPING: dict[str, DecodedType] = {
     "application/binary": DecodedType.BINARY,
 }
 
-ACCEPTABLE_DECODED_TYPES = {DecodedType.JSON, DecodedType.PLAIN_TEXT, DecodedType.HTML}
+ACCEPTABLE_DECODED_TYPES = {DecodedType.JSON, DecodedType.PLAIN_TEXT}
 
 
 def get_decoded_type(content_type: str | None) -> DecodedType | None:

tusk_drift_python_sdk-0.1.24/drift/core/coverage_server.py

@@ -0,0 +1,274 @@
+"""Coverage collection for Python SDK.
+
+Manages coverage.py for collecting per-test code coverage data.
+Coverage data is accessed via take_coverage_snapshot() which is called
+from the protobuf communicator handler.
+
+Flow:
+1. start_coverage_collection() initializes coverage.py at SDK startup
+2. Between tests, CLI sends CoverageSnapshotRequest via protobuf
+3. Communicator calls take_coverage_snapshot(baseline)
+4. For baseline: returns ALL coverable lines (including uncovered at count=0)
+5. For per-test: returns only executed lines since last snapshot, then resets
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+
+logger = logging.getLogger("TuskDrift")
+
+# Shared state for coverage collection
+_cov_instance = None
+_source_root: str | None = None
+_lock = threading.Lock()
+
+# Cache branch structure from baseline to ensure deterministic branch counts.
+# Branch detection via _analyze() depends on observed arcs, which vary with
+# thread timing. By caching from the baseline (which has the fullest data),
+# per-test snapshots report consistent totals.
+_branch_cache: dict[str, dict] | None = None
+
+
+def start_coverage_collection() -> bool:
+    """Initialize coverage.py collection if TUSK_COVERAGE is set.
+
+    TUSK_COVERAGE is set by the CLI when coverage is enabled.
+    This is the language-agnostic signal (Node uses NODE_V8_COVERAGE additionally).
+
+    Returns True if coverage was started, False otherwise.
+    """
+    global _cov_instance, _source_root
+
+    # TUSK_COVERAGE is the language-agnostic signal from the CLI
+    if not os.environ.get("TUSK_COVERAGE"):
+        return False
+
+    # Coverage collection only makes sense in REPLAY mode.
+    # If TUSK_DRIFT_MODE is not set we still proceed for backwards compatibility.
+    mode = os.environ.get("TUSK_DRIFT_MODE", "").upper()
+    if mode and mode != "REPLAY":
+        logger.debug("Coverage collection skipped: not in REPLAY mode (mode=%s)", mode)
+        return False
+
+    try:
+        import coverage as coverage_module
+    except ImportError:
+        logger.warning(
+            "Coverage requested but 'coverage' package is not installed. Install it with: pip install coverage"
+        )
+        return False
+
+    with _lock:
+        # Guard against double initialization — stop existing instance first
+        if _cov_instance is not None:
+            try:
+                _cov_instance.stop()
+            except Exception:
+                pass
+
+        _source_root = os.path.realpath(os.getcwd())
+
+        _cov_instance = coverage_module.Coverage(
+            source=[_source_root],
+            branch=True,
+            omit=[
+                "*/site-packages/*",
+                "*/venv/*",
+                "*/.venv/*",
+                "*/tests/*",
+                "*/test_*.py",
+                "*/__pycache__/*",
+            ],
+        )
+        _cov_instance.start()
+
+    logger.info("Coverage collection started")
+    return True
+
+
+def stop_coverage_collection() -> None:
+    """Stop coverage collection and clean up. Thread-safe."""
+    global _cov_instance, _branch_cache, _source_root
+    with _lock:
+        if _cov_instance is not None:
+            try:
+                _cov_instance.stop()
+            except Exception:
+                pass
+            _cov_instance = None
+        _branch_cache = None
+        _source_root = None
+
+
+def take_coverage_snapshot(baseline: bool = False) -> dict:
+    """Take a coverage snapshot.
+
+    Called from the protobuf communicator handler between tests.
+
+    Args:
+        baseline: If True, returns ALL coverable lines (including uncovered at count=0)
+                  for computing the total coverage denominator.
+                  If False, returns only lines executed since the last snapshot.
+
+    Returns:
+        dict of { filePath: { "lines": {...}, "totalBranches": N, "coveredBranches": N, "branches": {...} } }
+    """
+    with _lock:
+        if _cov_instance is None:
+            raise RuntimeError("Coverage not initialized")
+        _cov_instance.stop()
+        coverage = {}
+
+        try:
+            global _branch_cache
+            if baseline:
+                # Baseline: compute fresh branch data and cache it for per-test reuse
+                _branch_cache = {}
+                data = _cov_instance.get_data()
+                for filename in data.measured_files():
+                    if not _is_user_file(filename):
+                        continue
+                    try:
+                        _, statements, _, missing, _ = _cov_instance.analysis2(filename)
+                        missing_set = set(missing)
+                        lines_map = {}
+                        for line in statements:
+                            lines_map[str(line)] = 0 if line in missing_set else 1
+                        branch_data = _get_branch_data(data, filename)
+                        _branch_cache[filename] = branch_data
+                        if lines_map:
+                            coverage[filename] = {"lines": lines_map, **branch_data}
+                    except Exception as e:
+                        logger.debug(f"Failed to analyze {filename}: {e}")
+                        continue
+            else:
+                data = _cov_instance.get_data()
+                for filename in data.measured_files():
+                    if not _is_user_file(filename):
+                        continue
+                    lines = data.lines(filename)
+                    if lines:
+                        # Use cached branch data from baseline for stable totals.
+                        # Fall back to live _analyze() if no cache (e.g., no baseline taken).
+                        if _branch_cache is not None and filename in _branch_cache:
+                            branch_data = _get_per_test_branch_data(data, filename, _branch_cache[filename])
+                        else:
+                            branch_data = _get_branch_data(data, filename)
+                        coverage[filename] = {
+                            "lines": {str(line): 1 for line in lines},
+                            **branch_data,
+                        }
+        finally:
+            _cov_instance.erase()
+            _cov_instance.start()
+
+    return coverage
+
+
+def _is_user_file(filename: str) -> bool:
+    """Check if a file is a user source file (not third-party)."""
+    if "site-packages" in filename or "lib/python" in filename:
+        return False
+    # Resolve symlinks for consistent path comparison
+    resolved = os.path.realpath(filename)
+    # Use trailing separator to avoid prefix collisions (/app matching /application)
+    return not _source_root or resolved.startswith(_source_root + os.sep) or resolved == _source_root
+
+
+def _group_arcs_by_line(arcs: set) -> dict[int, list[int]]:
+    """Group executed arcs by from_line, skipping negative entry arcs."""
+    by_line: dict[int, list[int]] = {}
+    for from_line, to_line in arcs:
+        if from_line < 0:
+            continue
+        by_line.setdefault(from_line, []).append(to_line)
+    return by_line
+
+
+def _get_branch_data(data, filename: str) -> dict:
+    """Extract branch coverage data for a file.
+
+    Uses coverage.py's arc tracking (from_line, to_line) to compute
+    per-line branch coverage.
+    """
+    try:
+        if not data.has_arcs():
+            return {"totalBranches": 0, "coveredBranches": 0, "branches": {}}
+
+        if _cov_instance is None:
+            return {"totalBranches": 0, "coveredBranches": 0, "branches": {}}
+
+        analysis = _cov_instance._analyze(filename)
+        numbers = analysis.numbers
+
+        total_branches = numbers.n_branches
+        covered_branches = max(0, total_branches - numbers.n_missing_branches)
+
+        missing_arcs = analysis.missing_branch_arcs()
+        executed_arcs = set(data.arcs(filename) or [])
+        executed_by_line = _group_arcs_by_line(executed_arcs)
+
+        # A line is a branch point if:
+        # - it appears in missing_arcs (at least one path wasn't taken), OR
+        # - it has multiple executed arcs (multiple paths from same line)
+        branch_point_lines = set(missing_arcs.keys())
+        for from_line, to_lines in executed_by_line.items():
+            if len(to_lines) > 1:
+                branch_point_lines.add(from_line)
+
+        branch_lines: dict[int, dict] = {}
+
+        for from_line in branch_point_lines:
+            executed_count = len(executed_by_line.get(from_line, []))
+            missing_count = len(missing_arcs.get(from_line, []))
+            branch_lines[from_line] = {
+                "total": executed_count + missing_count,
+                "covered": executed_count,
+            }
+
+        branches = {str(line): info for line, info in branch_lines.items()}
+
+        return {
+            "totalBranches": total_branches,
+            "coveredBranches": covered_branches,
+            "branches": branches,
+        }
+    except Exception:
+        return {"totalBranches": 0, "coveredBranches": 0, "branches": {}}
+
+
+def _get_per_test_branch_data(data, filename: str, cached: dict) -> dict:
+    """Compute per-test branch coverage using cached branch structure from baseline.
+
+    Uses the cached branch point set (from baseline) for stable totals,
+    but computes covered counts from the current test's executed arcs.
+    This avoids flaky branch totals caused by non-deterministic arc detection.
+    """
+    try:
+        if not data.has_arcs():
+            return {"totalBranches": 0, "coveredBranches": 0, "branches": {}}
+
+        executed_arcs = set(data.arcs(filename) or [])
+        executed_by_line = _group_arcs_by_line(executed_arcs)
+
+        # Use cached branch points — only compute covered from current arcs
+        cached_branches = cached.get("branches", {})
+        branches: dict[str, dict] = {}
+        total_covered = 0
+
+        for line_str, info in cached_branches.items():
+            total = info["total"]
+            covered = min(len(executed_by_line.get(int(line_str), [])), total)
+            branches[line_str] = {"total": total, "covered": covered}
+            total_covered += covered
+
+        return {
+            "totalBranches": cached.get("totalBranches", 0),
+            "coveredBranches": total_covered,
+            "branches": branches,
+        }
+    except Exception:
+        return {"totalBranches": 0, "coveredBranches": 0, "branches": {}}