Backtest Expert

#!/usr/bin/env python3
"""Evaluate backtest quality using a 5-dimension scoring framework.

Dimensions (each 20 points, total 100):
  1. Sample Size   — total trades
  2. Expectancy    — win rate * avg win vs loss rate * avg loss
  3. Risk Mgmt     — max drawdown and profit factor
  4. Robustness    — years tested and parameter count
  5. Exec Realism  — slippage/friction tested flag

Based on methodology from skills/backtest-expert/references/methodology.md
and red-flag checklist from skills/backtest-expert/references/failed_tests.md.
"""

from __future__ import annotations

import argparse
import json
from datetime import datetime
from pathlib import Path

# ---------------------------------------------------------------------------
# Scoring functions (each returns 0-20)
# ---------------------------------------------------------------------------


def score_sample_size(total_trades: int) -> int:
    """Score based on number of trades.

    <30  -> 0
    30   -> 8
    100  -> 15
    200+ -> 20
    """
    if total_trades < 30:
        return 0
    if total_trades < 100:
        # Linear interpolation 8..14 for 30..99
        return 8 + int((total_trades - 30) / 70 * 7)
    if total_trades < 200:
        return 15 + int((total_trades - 100) / 100 * 5)
    return 20


def calc_profit_factor(win_rate: float, avg_win_pct: float, avg_loss_pct: float) -> float:
    """Calculate profit factor: (win_rate * avg_win) / (loss_rate * avg_loss).

    Returns float('inf') when loss component is zero.
    """
    wr = win_rate / 100.0
    loss_component = (1 - wr) * avg_loss_pct
    if loss_component == 0:
        return float("inf")
    return (wr * avg_win_pct) / loss_component


def calc_expectancy(win_rate: float, avg_win_pct: float, avg_loss_pct: float) -> float:
    """Calculate expectancy per trade in percent.

    E = win_rate * avg_win - loss_rate * avg_loss
    """
    wr = win_rate / 100.0
    return wr * avg_win_pct - (1 - wr) * avg_loss_pct


def score_expectancy(win_rate: float, avg_win_pct: float, avg_loss_pct: float) -> int:
    """Score based on expectancy value.

    <=0       -> 0
    0..0.5    -> 5..10  (linear)
    0.5..1.5  -> 10..18 (linear)
    >=1.5     -> 20
    """
    exp = calc_expectancy(win_rate, avg_win_pct, avg_loss_pct)
    if exp <= 0:
        return 0
    if exp < 0.5:
        return 5 + int(exp / 0.5 * 5)
    if exp < 1.5:
        return 10 + int((exp - 0.5) / 1.0 * 8)
    return 20


def score_risk_management(
    max_drawdown_pct: float,
    win_rate: float,
    avg_win_pct: float,
    avg_loss_pct: float,
) -> int:
    """Score based on max drawdown and profit factor.

    Drawdown component (0-12):
      <20%  -> 12
      20-50% -> linear 12..0
      >50%  -> 0

    Profit factor component (0-8):
      <1.0  -> 0
      1.0-3.0 -> linear 0..8
      3.0+  -> 8
    """
    # Drawdown component (0-12)
    # 50%+ drawdown is catastrophic — override total to 0
    if max_drawdown_pct >= 50:
        return 0
    if max_drawdown_pct < 20:
        dd_score = 12
    else:
        dd_score = int(12 * (50 - max_drawdown_pct) / 30)

    # Profit factor component (0-8)
    # Continuous: PF 1.0→3.0 maps linearly to 0→8, capped at 8 for PF≥3.0
    pf = calc_profit_factor(win_rate, avg_win_pct, avg_loss_pct)
    if pf < 1.0:
        pf_score = 0
    elif pf >= 3.0:
        pf_score = 8
    else:
        pf_score = int((pf - 1.0) / 2.0 * 8)

    total = dd_score + pf_score
    return min(20, total)


def score_robustness(years_tested: int, num_parameters: int) -> int:
    """Score based on test duration and parameter count.

    Years component (0-15):
      <5   -> 0
      5-9  -> linear 5..14
      10+  -> 15

    Parameter component (0-5):
      <=4  -> 5
      5-6  -> 3
      7    -> 1
      8+   -> 0
    """
    # Years component (0-15)
    if years_tested < 5:
        years_score = 0
    elif years_tested >= 10:
        years_score = 15
    else:
        years_score = 5 + int((years_tested - 5) / 5 * 10)

    # Parameter component (0-5)
    if num_parameters <= 4:
        param_score = 5
    elif num_parameters <= 6:
        param_score = 3
    elif num_parameters == 7:
        param_score = 1
    else:
        param_score = 0

    return min(20, years_score + param_score)


def score_execution_realism(slippage_tested: bool) -> int:
    """Score based on whether slippage/friction was tested.

    Tested   -> 20
    Untested -> 0
    """
    return 20 if slippage_tested else 0


# ---------------------------------------------------------------------------
# Verdict
# ---------------------------------------------------------------------------


def get_verdict(total_score: int) -> str:
    """Map total score to Deploy / Refine / Abandon."""
    if total_score >= 70:
        return "Deploy"
    if total_score >= 40:
        return "Refine"
    return "Abandon"


# ---------------------------------------------------------------------------
# Red flags
# ---------------------------------------------------------------------------


def detect_red_flags(
    total_trades: int,
    win_rate: float,
    avg_win_pct: float,
    avg_loss_pct: float,
    max_drawdown_pct: float,
    years_tested: int,
    num_parameters: int,
    slippage_tested: bool,
) -> list[dict]:
    """Detect red flags based on methodology checklist."""
    flags: list[dict] = []

    if total_trades < 30:
        flags.append(
            {
                "id": "small_sample",
                "severity": "high",
                "message": f"Only {total_trades} trades — minimum 30 required for statistical confidence.",
            }
        )

    if not slippage_tested:
        flags.append(
            {
                "id": "no_slippage_test",
                "severity": "high",
                "message": "Slippage/friction not tested — results may not survive real-world execution.",
            }
        )

    if max_drawdown_pct > 50:
        flags.append(
            {
                "id": "excessive_drawdown",
                "severity": "high",
                "message": f"Max drawdown {max_drawdown_pct}% exceeds 50% threshold — catastrophic risk.",
            }
        )

    if num_parameters >= 7:
        flags.append(
            {
                "id": "over_optimized",
                "severity": "medium",
                "message": f"{num_parameters} parameters suggests over-optimization / curve-fitting risk.",
            }
        )

    if years_tested < 5:
        flags.append(
            {
                "id": "short_test_period",
                "severity": "medium",
                "message": f"Only {years_tested} years tested — may miss regime changes (minimum 5 recommended).",
            }
        )

    exp = calc_expectancy(win_rate, avg_win_pct, avg_loss_pct)
    if exp < 0:
        flags.append(
            {
                "id": "negative_expectancy",
                "severity": "high",
                "message": f"Negative expectancy ({exp:.3f}%) — strategy loses money on average.",
            }
        )

    if win_rate > 90 and max_drawdown_pct < 5:
        flags.append(
            {
                "id": "too_good",
                "severity": "medium",
                "message": "Results look too good — audit for look-ahead bias or data issues.",
            }
        )

    return flags


# ---------------------------------------------------------------------------
# Main evaluation
# ---------------------------------------------------------------------------


def validate_inputs(
    total_trades: int,
    win_rate: float,
    avg_win_pct: float,
    avg_loss_pct: float,
    max_drawdown_pct: float,
    years_tested: int,
    num_parameters: int,
) -> None:
    """Validate evaluation inputs at system boundary. Raises ValueError."""
    if total_trades < 0:
        raise ValueError("total_trades must be >= 0")
    if not (0 <= win_rate <= 100):
        raise ValueError("win_rate must be between 0 and 100")
    if avg_win_pct < 0:
        raise ValueError("avg_win_pct must be >= 0")
    if avg_loss_pct < 0:
        raise ValueError("avg_loss_pct must be >= 0")
    if max_drawdown_pct < 0:
        raise ValueError("max_drawdown_pct must be >= 0")
    if years_tested < 0:
        raise ValueError("years_tested must be >= 0")
    if num_parameters < 0:
        raise ValueError("num_parameters must be >= 0")


def evaluate(
    total_trades: int,
    win_rate: float,
    avg_win_pct: float,
    avg_loss_pct: float,
    max_drawdown_pct: float,
    years_tested: int,
    num_parameters: int,
    slippage_tested: bool,
) -> dict:
    """Run full 5-dimension evaluation and return structured result."""
    validate_inputs(
        total_trades,
        win_rate,
        avg_win_pct,
        avg_loss_pct,
        max_drawdown_pct,
        years_tested,
        num_parameters,
    )
    d1 = score_sample_size(total_trades)
    d2 = score_expectancy(win_rate, avg_win_pct, avg_loss_pct)
    d3 = score_risk_management(max_drawdown_pct, win_rate, avg_win_pct, avg_loss_pct)
    d4 = score_robustness(years_tested, num_parameters)
    d5 = score_execution_realism(slippage_tested)

    total = d1 + d2 + d3 + d4 + d5
    total = max(0, min(100, total))

    return {
        "total_score": total,
        "verdict": get_verdict(total),
        "dimensions": [
            {"name": "Sample Size", "score": d1, "max_score": 20},
            {"name": "Expectancy", "score": d2, "max_score": 20},
            {"name": "Risk Management", "score": d3, "max_score": 20},
            {"name": "Robustness", "score": d4, "max_score": 20},
            {"name": "Execution Realism", "score": d5, "max_score": 20},
        ],
        "red_flags": detect_red_flags(
            total_trades,
            win_rate,
            avg_win_pct,
            avg_loss_pct,
            max_drawdown_pct,
            years_tested,
            num_parameters,
            slippage_tested,
        ),
        "profit_factor": calc_profit_factor(win_rate, avg_win_pct, avg_loss_pct),
        "expectancy": calc_expectancy(win_rate, avg_win_pct, avg_loss_pct),
        "inputs": {
            "total_trades": total_trades,
            "win_rate": win_rate,
            "avg_win_pct": avg_win_pct,
            "avg_loss_pct": avg_loss_pct,
            "max_drawdown_pct": max_drawdown_pct,
            "years_tested": years_tested,
            "num_parameters": num_parameters,
            "slippage_tested": slippage_tested,
        },
    }


# ---------------------------------------------------------------------------
# Output writers
# ---------------------------------------------------------------------------


def to_markdown(result: dict) -> str:
    """Render evaluation result as markdown report."""
    lines = [
        "# Backtest Evaluation Report",
        "",
        f"**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
        "",
        f"## Verdict: {result['verdict']}",
        "",
        f"**Total Score: {result['total_score']} / 100**",
        "",
        "## Dimension Scores",
        "",
        "| Dimension | Score | Max |",
        "|-----------|------:|----:|",
    ]
    for dim in result["dimensions"]:
        lines.append(f"| {dim['name']} | {dim['score']} | {dim['max_score']} |")

    lines.extend(
        [
            "",
            "## Key Metrics",
            "",
            f"- **Profit Factor**: {result['profit_factor']:.2f}"
            if result["profit_factor"] != float("inf")
            else "- **Profit Factor**: Inf (no losing trades)",
            f"- **Expectancy**: {result['expectancy']:.3f}% per trade",
        ]
    )

    if result["red_flags"]:
        lines.extend(["", "## Red Flags", ""])
        for flag in result["red_flags"]:
            icon = "🔴" if flag["severity"] == "high" else "🟡"
            lines.append(f"- {icon} **{flag['id']}**: {flag['message']}")
    else:
        lines.extend(["", "## Red Flags", "", "No red flags detected."])

    lines.extend(
        [
            "",
            "## Input Parameters",
            "",
        ]
    )
    for key, value in result["inputs"].items():
        lines.append(f"- **{key}**: {value}")

    lines.append("")
    return "\n".join(lines)


def write_outputs(result: dict, output_dir: Path) -> tuple[Path, Path]:
    """Write JSON and Markdown reports to output_dir. Returns (json_path, md_path)."""
    output_dir.mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y-%m-%d_%H%M%S")
    stem = f"backtest_eval_{timestamp}"

    json_path = output_dir / f"{stem}.json"
    md_path = output_dir / f"{stem}.md"

    json_path.write_text(
        json.dumps(result, ensure_ascii=False, indent=2, default=str),
        encoding="utf-8",
    )
    md_path.write_text(to_markdown(result), encoding="utf-8")

    return json_path, md_path


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Evaluate backtest quality using a 5-dimension scoring framework."
    )
    parser.add_argument(
        "--total-trades", type=int, required=True, help="Number of trades in backtest"
    )
    parser.add_argument(
        "--win-rate", type=float, required=True, help="Win rate in percent (e.g. 58)"
    )
    parser.add_argument(
        "--avg-win-pct", type=float, required=True, help="Average winning trade in percent"
    )
    parser.add_argument(
        "--avg-loss-pct",
        type=float,
        required=True,
        help="Average losing trade in percent (positive number)",
    )
    parser.add_argument(
        "--max-drawdown-pct", type=float, required=True, help="Maximum drawdown in percent"
    )
    parser.add_argument(
        "--years-tested", type=int, required=True, help="Number of years in backtest period"
    )
    parser.add_argument(
        "--num-parameters", type=int, required=True, help="Number of tunable parameters in strategy"
    )
    parser.add_argument(
        "--slippage-tested", action="store_true", help="Whether slippage/friction was modeled"
    )
    parser.add_argument(
        "--output-dir", default="reports/", help="Output directory (default: reports/)"
    )
    return parser.parse_args()


def main() -> int:
    args = parse_args()

    result = evaluate(
        total_trades=args.total_trades,
        win_rate=args.win_rate,
        avg_win_pct=args.avg_win_pct,
        avg_loss_pct=args.avg_loss_pct,
        max_drawdown_pct=args.max_drawdown_pct,
        years_tested=args.years_tested,
        num_parameters=args.num_parameters,
        slippage_tested=args.slippage_tested,
    )

    output_dir = Path(args.output_dir)
    json_path, md_path = write_outputs(result, output_dir)

    print(f"Score: {result['total_score']}/100 — Verdict: {result['verdict']}")
    if result["red_flags"]:
        print(f"Red flags: {len(result['red_flags'])}")
        for flag in result["red_flags"]:
            print(f"  [{flag['severity'].upper()}] {flag['message']}")
    print(f"JSON: {json_path}")
    print(f"Markdown: {md_path}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

"""Test fixtures for backtest evaluator."""

from __future__ import annotations

import importlib.util
import sys
from pathlib import Path

import pytest


@pytest.fixture(scope="module")
def evaluator_module():
    """Load evaluate_backtest.py as a module for unit tests."""
    script_path = Path(__file__).resolve().parents[1] / "evaluate_backtest.py"
    spec = importlib.util.spec_from_file_location("evaluate_backtest", script_path)
    if spec is None or spec.loader is None:
        raise RuntimeError("Failed to load evaluate_backtest.py")
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module
    spec.loader.exec_module(module)
    return module

"""Tests for evaluate_backtest.py — backtest quality evaluation tool."""

from __future__ import annotations

import json
from pathlib import Path

import pytest

# ---------------------------------------------------------------------------
# 0. Input validation
# ---------------------------------------------------------------------------


class TestInputValidation:
    def test_win_rate_above_100(self, evaluator_module):
        """win_rate > 100 raises ValueError."""
        with pytest.raises(ValueError, match="win_rate"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=110,
                avg_win_pct=2.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=15,
                years_tested=5,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_win_rate_negative(self, evaluator_module):
        """win_rate < 0 raises ValueError."""
        with pytest.raises(ValueError, match="win_rate"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=-5,
                avg_win_pct=2.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=15,
                years_tested=5,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_negative_avg_win(self, evaluator_module):
        """Negative avg_win_pct raises ValueError."""
        with pytest.raises(ValueError, match="avg_win_pct"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=60,
                avg_win_pct=-1.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=15,
                years_tested=5,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_negative_avg_loss(self, evaluator_module):
        """Negative avg_loss_pct raises ValueError."""
        with pytest.raises(ValueError, match="avg_loss_pct"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=60,
                avg_win_pct=2.0,
                avg_loss_pct=-1.0,
                max_drawdown_pct=15,
                years_tested=5,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_negative_total_trades(self, evaluator_module):
        """Negative total_trades raises ValueError."""
        with pytest.raises(ValueError, match="total_trades"):
            evaluator_module.evaluate(
                total_trades=-10,
                win_rate=60,
                avg_win_pct=2.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=15,
                years_tested=5,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_negative_max_drawdown(self, evaluator_module):
        """Negative max_drawdown_pct raises ValueError."""
        with pytest.raises(ValueError, match="max_drawdown_pct"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=60,
                avg_win_pct=2.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=-5,
                years_tested=5,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_negative_years_tested(self, evaluator_module):
        """Negative years_tested raises ValueError."""
        with pytest.raises(ValueError, match="years_tested"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=60,
                avg_win_pct=2.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=15,
                years_tested=-1,
                num_parameters=3,
                slippage_tested=True,
            )

    def test_negative_num_parameters(self, evaluator_module):
        """Negative num_parameters raises ValueError."""
        with pytest.raises(ValueError, match="num_parameters"):
            evaluator_module.evaluate(
                total_trades=100,
                win_rate=60,
                avg_win_pct=2.0,
                avg_loss_pct=1.0,
                max_drawdown_pct=15,
                years_tested=5,
                num_parameters=-2,
                slippage_tested=True,
            )

    def test_boundary_win_rate_zero(self, evaluator_module):
        """win_rate=0 is valid (all losses)."""
        result = evaluator_module.evaluate(
            total_trades=100,
            win_rate=0,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=5,
            num_parameters=3,
            slippage_tested=True,
        )
        assert result["total_score"] >= 0

    def test_boundary_win_rate_100(self, evaluator_module):
        """win_rate=100 is valid (all wins)."""
        result = evaluator_module.evaluate(
            total_trades=100,
            win_rate=100,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=5,
            num_parameters=3,
            slippage_tested=True,
        )
        assert result["total_score"] >= 0


# ---------------------------------------------------------------------------
# 1. Sample Size scoring
# ---------------------------------------------------------------------------


class TestSampleSizeScoring:
    def test_below_minimum(self, evaluator_module):
        """<30 trades -> 0 points."""
        assert evaluator_module.score_sample_size(20) == 0

    def test_at_minimum(self, evaluator_module):
        """30 trades -> partial credit."""
        score = evaluator_module.score_sample_size(30)
        assert 0 < score < 15

    def test_good_sample(self, evaluator_module):
        """100 trades -> 15 points."""
        assert evaluator_module.score_sample_size(100) == 15

    def test_excellent_sample(self, evaluator_module):
        """200+ trades -> full 20 points."""
        assert evaluator_module.score_sample_size(200) == 20
        assert evaluator_module.score_sample_size(500) == 20


# ---------------------------------------------------------------------------
# 2. Expectancy calculation
# ---------------------------------------------------------------------------


class TestExpectancyCalculation:
    def test_positive_expectancy(self, evaluator_module):
        """Positive expectancy -> positive score."""
        score = evaluator_module.score_expectancy(win_rate=60, avg_win_pct=2.0, avg_loss_pct=1.0)
        assert score > 0

    def test_negative_expectancy(self, evaluator_module):
        """Negative expectancy -> 0 points."""
        score = evaluator_module.score_expectancy(win_rate=30, avg_win_pct=1.0, avg_loss_pct=2.0)
        assert score == 0

    def test_zero_expectancy(self, evaluator_module):
        """Break-even -> 0 points."""
        # win_rate=50, avg_win=1, avg_loss=1 => expectancy = 0
        score = evaluator_module.score_expectancy(win_rate=50, avg_win_pct=1.0, avg_loss_pct=1.0)
        assert score == 0

    def test_high_expectancy_capped(self, evaluator_module):
        """Very high expectancy still capped at 20."""
        score = evaluator_module.score_expectancy(win_rate=90, avg_win_pct=5.0, avg_loss_pct=0.5)
        assert score == 20


# ---------------------------------------------------------------------------
# 3. Risk Management scoring
# ---------------------------------------------------------------------------


class TestRiskManagementScoring:
    def test_low_drawdown(self, evaluator_module):
        """<20% drawdown + high PF -> full points."""
        # PF = (0.75 * 2.0) / (0.25 * 1.0) = 6.0 (well above 3.0 threshold)
        score = evaluator_module.score_risk_management(
            max_drawdown_pct=10, win_rate=75, avg_win_pct=2.0, avg_loss_pct=1.0
        )
        assert score == 20

    def test_moderate_drawdown(self, evaluator_module):
        """30% drawdown -> partial points."""
        score = evaluator_module.score_risk_management(
            max_drawdown_pct=30, win_rate=60, avg_win_pct=2.0, avg_loss_pct=1.0
        )
        assert 0 < score < 20

    def test_extreme_drawdown(self, evaluator_module):
        """50%+ drawdown -> 0 points."""
        score = evaluator_module.score_risk_management(
            max_drawdown_pct=55, win_rate=60, avg_win_pct=2.0, avg_loss_pct=1.0
        )
        assert score == 0


# ---------------------------------------------------------------------------
# 4. Robustness scoring — years tested
# ---------------------------------------------------------------------------


class TestRobustnessYears:
    def test_short_period(self, evaluator_module):
        """<5 years -> 0 for years component."""
        score = evaluator_module.score_robustness(years_tested=3, num_parameters=3)
        assert score < 15  # years component is 0

    def test_minimum_years(self, evaluator_module):
        """5 years -> partial credit."""
        score = evaluator_module.score_robustness(years_tested=5, num_parameters=3)
        assert score > 0

    def test_long_period(self, evaluator_module):
        """10+ years -> full years component (15 pts)."""
        score = evaluator_module.score_robustness(years_tested=10, num_parameters=3)
        assert score >= 15


# ---------------------------------------------------------------------------
# 5. Robustness scoring — parameters
# ---------------------------------------------------------------------------


class TestRobustnessParameters:
    def test_few_parameters(self, evaluator_module):
        """3 parameters -> full parameter component (5 pts)."""
        score = evaluator_module.score_robustness(years_tested=10, num_parameters=3)
        assert score == 20  # 15 (years) + 5 (params)

    def test_moderate_parameters(self, evaluator_module):
        """5 parameters -> partial deduction."""
        score = evaluator_module.score_robustness(years_tested=10, num_parameters=5)
        assert 15 <= score < 20

    def test_many_parameters(self, evaluator_module):
        """8+ parameters -> heavy deduction."""
        score = evaluator_module.score_robustness(years_tested=10, num_parameters=8)
        assert score < 18


# ---------------------------------------------------------------------------
# 6. Slippage flag
# ---------------------------------------------------------------------------


class TestSlippageFlag:
    def test_slippage_tested(self, evaluator_module):
        """Slippage tested -> full 20 points."""
        score = evaluator_module.score_execution_realism(slippage_tested=True)
        assert score == 20

    def test_slippage_not_tested(self, evaluator_module):
        """Slippage not tested -> 0 points."""
        score = evaluator_module.score_execution_realism(slippage_tested=False)
        assert score == 0


# ---------------------------------------------------------------------------
# 7. Overall verdict
# ---------------------------------------------------------------------------


class TestOverallVerdict:
    def test_deploy_verdict(self, evaluator_module):
        """Score >= 70 -> Deploy."""
        assert evaluator_module.get_verdict(75) == "Deploy"
        assert evaluator_module.get_verdict(100) == "Deploy"

    def test_refine_verdict(self, evaluator_module):
        """40 <= score < 70 -> Refine."""
        assert evaluator_module.get_verdict(50) == "Refine"
        assert evaluator_module.get_verdict(69) == "Refine"

    def test_abandon_verdict(self, evaluator_module):
        """Score < 40 -> Abandon."""
        assert evaluator_module.get_verdict(30) == "Abandon"
        assert evaluator_module.get_verdict(0) == "Abandon"


# ---------------------------------------------------------------------------
# 8. Profit factor calculation
# ---------------------------------------------------------------------------


class TestProfitFactor:
    def test_positive_profit_factor(self, evaluator_module):
        """win_rate=60, avg_win=2, avg_loss=1 -> PF = 3.0."""
        pf = evaluator_module.calc_profit_factor(win_rate=60, avg_win_pct=2.0, avg_loss_pct=1.0)
        assert abs(pf - 3.0) < 0.01

    def test_breakeven_profit_factor(self, evaluator_module):
        """win_rate=50, avg_win=1, avg_loss=1 -> PF = 1.0."""
        pf = evaluator_module.calc_profit_factor(win_rate=50, avg_win_pct=1.0, avg_loss_pct=1.0)
        assert abs(pf - 1.0) < 0.01

    def test_zero_loss_profit_factor(self, evaluator_module):
        """100% win rate -> PF = inf (capped)."""
        pf = evaluator_module.calc_profit_factor(win_rate=100, avg_win_pct=2.0, avg_loss_pct=1.0)
        assert pf == float("inf")


# ---------------------------------------------------------------------------
# 8b. PF score boundary smoothness
# ---------------------------------------------------------------------------


class TestProfitFactorScoreSmoothness:
    def test_pf_boundary_no_large_jump(self, evaluator_module):
        """PF score should not jump more than 2 points at PF=2.0 boundary."""
        # Use drawdown <20% so dd_score is constant at 12
        score_below = evaluator_module.score_risk_management(
            max_drawdown_pct=10, win_rate=50, avg_win_pct=3.98, avg_loss_pct=2.0
        )  # PF ~= 1.99
        score_at = evaluator_module.score_risk_management(
            max_drawdown_pct=10, win_rate=50, avg_win_pct=4.0, avg_loss_pct=2.0
        )  # PF = 2.0
        # The jump should be at most 2 points (not the previous 4-point gap)
        assert abs(score_at - score_below) <= 2

    def test_pf_monotonically_increasing(self, evaluator_module):
        """Higher PF should give equal or higher risk management score."""
        # All with same low drawdown to isolate PF component
        scores = []
        for avg_win in [1.0, 1.5, 2.0, 3.0, 5.0]:
            s = evaluator_module.score_risk_management(
                max_drawdown_pct=10, win_rate=60, avg_win_pct=avg_win, avg_loss_pct=1.0
            )
            scores.append(s)
        for i in range(len(scores) - 1):
            assert scores[i] <= scores[i + 1], (
                f"Score decreased: PF step {i} gave {scores[i]} "
                f"but step {i + 1} gave {scores[i + 1]}"
            )


# ---------------------------------------------------------------------------
# 9. Output JSON structure
# ---------------------------------------------------------------------------


class TestOutputJsonStructure:
    def test_evaluate_returns_all_keys(self, evaluator_module):
        """evaluate() result must contain all required keys."""
        result = evaluator_module.evaluate(
            total_trades=150,
            win_rate=62,
            avg_win_pct=1.8,
            avg_loss_pct=1.2,
            max_drawdown_pct=15,
            years_tested=8,
            num_parameters=3,
            slippage_tested=True,
        )
        required_keys = {
            "total_score",
            "verdict",
            "dimensions",
            "red_flags",
            "profit_factor",
            "expectancy",
        }
        assert required_keys.issubset(result.keys())

    def test_dimensions_structure(self, evaluator_module):
        """Each dimension must have name, score, max_score."""
        result = evaluator_module.evaluate(
            total_trades=100,
            win_rate=55,
            avg_win_pct=1.5,
            avg_loss_pct=1.0,
            max_drawdown_pct=20,
            years_tested=5,
            num_parameters=4,
            slippage_tested=True,
        )
        for dim in result["dimensions"]:
            assert "name" in dim
            assert "score" in dim
            assert "max_score" in dim
            assert dim["max_score"] == 20

    def test_total_score_range(self, evaluator_module):
        """Total score must be 0-100."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=65,
            avg_win_pct=2.5,
            avg_loss_pct=1.0,
            max_drawdown_pct=12,
            years_tested=10,
            num_parameters=3,
            slippage_tested=True,
        )
        assert 0 <= result["total_score"] <= 100


# ---------------------------------------------------------------------------
# 10. Red flags detection
# ---------------------------------------------------------------------------


class TestRedFlagsDetection:
    def test_small_sample_flag(self, evaluator_module):
        """<30 trades triggers red flag."""
        result = evaluator_module.evaluate(
            total_trades=20,
            win_rate=80,
            avg_win_pct=3.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=10,
            years_tested=10,
            num_parameters=3,
            slippage_tested=True,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "small_sample" in flags

    def test_no_slippage_flag(self, evaluator_module):
        """Slippage not tested triggers red flag."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=10,
            num_parameters=3,
            slippage_tested=False,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "no_slippage_test" in flags

    def test_excessive_drawdown_flag(self, evaluator_module):
        """>50% drawdown triggers red flag."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=55,
            years_tested=10,
            num_parameters=3,
            slippage_tested=True,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "excessive_drawdown" in flags

    def test_over_optimized_flag_at_8(self, evaluator_module):
        """8 parameters triggers red flag."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=10,
            num_parameters=8,
            slippage_tested=True,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "over_optimized" in flags

    def test_over_optimized_flag_at_7(self, evaluator_module):
        """7 parameters also triggers red flag (already penalized in scoring)."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=10,
            num_parameters=7,
            slippage_tested=True,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "over_optimized" in flags

    def test_no_over_optimized_flag_at_6(self, evaluator_module):
        """6 parameters does NOT trigger over_optimized flag."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=10,
            num_parameters=6,
            slippage_tested=True,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "over_optimized" not in flags

    def test_short_test_period_flag(self, evaluator_module):
        """<5 years triggers red flag."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=3,
            num_parameters=3,
            slippage_tested=True,
        )
        flags = [f["id"] for f in result["red_flags"]]
        assert "short_test_period" in flags

    def test_clean_backtest_no_flags(self, evaluator_module):
        """Well-constructed backtest has no red flags."""
        result = evaluator_module.evaluate(
            total_trades=200,
            win_rate=60,
            avg_win_pct=2.0,
            avg_loss_pct=1.0,
            max_drawdown_pct=15,
            years_tested=10,
            num_parameters=3,
            slippage_tested=True,
        )
        assert result["red_flags"] == []


# ---------------------------------------------------------------------------
# 11. File output (JSON + Markdown)
# ---------------------------------------------------------------------------


class TestFileOutput:
    def test_write_outputs(self, evaluator_module, tmp_path: Path):
        """write_outputs creates .json and .md files."""
        result = evaluator_module.evaluate(
            total_trades=150,
            win_rate=62,
            avg_win_pct=1.8,
            avg_loss_pct=1.2,
            max_drawdown_pct=15,
            years_tested=8,
            num_parameters=3,
            slippage_tested=True,
        )
        json_path, md_path = evaluator_module.write_outputs(result, tmp_path)

        assert json_path.exists()
        assert md_path.exists()

        data = json.loads(json_path.read_text(encoding="utf-8"))
        assert data["total_score"] == result["total_score"]

        md_text = md_path.read_text(encoding="utf-8")
        assert "# Backtest Evaluation Report" in md_text
        assert result["verdict"] in md_text