"""Shared mock helpers for TDD tag validation tests.

Provides ``make_mock_scenario`` — a factory for lightweight mock
``Scenario`` objects used by both the Behave step definitions
(``features/steps/tdd_tag_validation_steps.py``) and the Robot
Framework integration test helper (``robot/helper_tdd_tag_validation.py``).

Centralising the mock builder eliminates duplication and ensures both
test suites exercise ``apply_tdd_inversion`` with identically-shaped
mock objects.

See CONTRIBUTING.md > TDD Issue Test Tags for the three-tag specification.
"""

from __future__ import annotations

from unittest.mock import MagicMock

from behave.model import Status


def make_mock_scenario(
    tags: list[str],
    steps_passed: bool = True,
    hook_failed: bool = False,
    was_dry_run: bool = False,
    step_exception: BaseException | None = None,
) -> MagicMock:
    """Build a lightweight mock ``Scenario`` for ``apply_tdd_inversion`` tests.

    Args:
        tags: The effective tags to place on the scenario.
        steps_passed: When ``True`` every step has ``Status.passed``.
            When ``False`` the first step has ``Status.failed`` with
            *step_exception* (defaulting to ``AssertionError``).
        hook_failed: Simulates an infrastructure/hook error.
        was_dry_run: Simulates ``--dry-run`` mode.
        step_exception: The exception attached to the failed step when
            *steps_passed* is ``False``.  Defaults to ``AssertionError``.

    Returns:
        A ``MagicMock`` configured to look like a Behave ``Scenario``.
    """
    scenario = MagicMock()
    scenario.effective_tags = tags
    scenario.name = "mock-scenario"
    scenario.hook_failed = hook_failed
    scenario.was_dry_run = was_dry_run

    mock_step = MagicMock()
    if steps_passed:
        mock_step.status = Status.passed
        mock_step.exception = None
    else:
        mock_step.status = Status.failed
        mock_step.exception = (
            step_exception
            if step_exception is not None
            else AssertionError("simulated assertion failure")
        )
    scenario.all_steps = [mock_step]
    return scenario


__all__: list[str] = ["make_mock_scenario"]