"""Step definitions used exclusively by ``tdd_expected_fail_demo.feature``.

Per CONTRIBUTING.md: steps used only by a particular feature file must live
in a correspondingly named step definition file.

These steps provide deliberately-passing and deliberately-failing behaviour
to exercise the ``Scenario.run()`` wrapper installed by
``_install_tdd_expected_fail_patch()`` in ``features/environment.py``.

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

from __future__ import annotations

from behave import given, then, when
from behave.runner import Context


@given("tdd demo a step that always succeeds")
def step_tdd_demo_success(context: Context) -> None:
    """A trivial passing step."""
    context.tdd_demo_ran = True


@when("tdd demo a deliberately failing assertion is executed")
def step_tdd_demo_deliberate_fail(context: Context) -> None:
    """This step deliberately fails to simulate a bug still being present.

    The ``@tdd_expected_fail`` tag on the scenario causes the
    ``Scenario.run()`` wrapper to invert this failure into a pass.
    """
    msg = "Deliberate failure: bug #999 is still present (expected by TDD tag)"
    raise AssertionError(msg)


@then("tdd demo this step is never reached")
def step_tdd_demo_never_reached(context: Context) -> None:
    """Placeholder step — unreachable because the previous step fails."""
    context.tdd_demo_unreachable = True