diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 627f0cb..37fe7d2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,6 +24,7 @@ jobs: # out of the navigation fails. Linux on purpose: it proves the reference # never imports the Windows-only MetaTrader5 package. name: documentation site (mkdocs --strict) + needs: coverage runs-on: ubuntu-latest steps: # Actions are pinned to commit SHAs: a moved tag cannot inject code into CI. @@ -37,11 +38,41 @@ jobs: - run: mkdocs build --strict env: NO_MKDOCS_2_WARNING: "1" + # Only the coverage job's output joins the site: the tests and the dev + # tools never run on the machine that uploads it (ADR 0015). + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: coverage + path: site - if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 with: path: site + coverage: + # The number the README badge shows, measured here and published with the + # site (ADR 0015): the HTML report under /coverage/ and the badge's data + # in coverage.json. A job of its own: the tests and the dev tools must not + # share a machine with the site artifact. + name: coverage report + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.12" + - run: python -m pip install -e ".[dev]" + - run: pytest --cov --cov-report=json --cov-report=html:report/coverage + - run: python scripts/coverage_badge.py coverage.json report/coverage.json + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: coverage + path: report + if-no-files-found: error + retention-days: 1 + diagrams: # The browser renders Mermaid, so the build cannot see a broken diagram; # this parses each one in the runner's Chrome against the Mermaid release diff --git a/.gitignore b/.gitignore index b4a70b2..4f3ce24 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ __pycache__/ .pytest_cache/ .coverage coverage.xml +coverage.json htmlcov/ # Documentation build output (mkdocs build) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84e6cca..848b3ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +### Added +- A coverage badge in the README, measured by the tests on master and linked + to the full line-by-line report on the documentation site (ADR 0015). + Coverage is 100% of lines and branches, release scripts included, and CI + now requires 100%. + ## [3.0.2] - 2026-11-11 Documentation only: the library code behaves exactly as in 3.0.1. diff --git a/README.md b/README.md index bc10d7f..251a6d4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![CI](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml) [![Docs](https://img.shields.io/badge/docs-online-blue?logo=materialformkdocs&logoColor=white)](https://akinzou.github.io/MetaTrader5-Python/) +[![Coverage](https://img.shields.io/endpoint?url=https://akinzou.github.io/MetaTrader5-Python/coverage.json)](https://akinzou.github.io/MetaTrader5-Python/coverage/) [![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5)](https://pypi.org/project/PythonMetaTrader5/) ![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white) ![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg) @@ -471,6 +472,7 @@ to MetaTrader 5. Details: [docs/architecture.md](https://github.com/Akinzou/Meta | [0012](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0012-pin-readme-links-at-publish.md) | Publish from the tag and pin the README's links there | | [0013](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0013-documentation-site.md) | A documentation site built from the README and the source | | [0014](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0014-mermaid-diagrams.md) | Diagrams as Mermaid, checked in CI and replaced on PyPI | +| [0015](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0015-measured-coverage-badge.md) | A coverage badge measured on master, with the full report | ## Development @@ -479,10 +481,13 @@ python -m venv .venv && .venv\Scripts\activate pip install -e ".[dev]" ruff check src tests scripts && ruff format --check src tests scripts mypy -pytest --cov +pytest --cov # 100% line and branch coverage required python scripts/check_file_length.py ``` +Coverage of the latest master, line by line: + (ADR 0015). + The documentation site (ADR 0013) includes this README as its user guide: ```bash diff --git a/docs/adr/0015-measured-coverage-badge.md b/docs/adr/0015-measured-coverage-badge.md new file mode 100644 index 0000000..1a056c6 --- /dev/null +++ b/docs/adr/0015-measured-coverage-badge.md @@ -0,0 +1,52 @@ +# ADR 0015: A coverage badge measured on master, with the full report + +- Status: accepted (unreleased). Asked for by the package owner on 2026-11-12. + +## Context + +Tests cover 100% of the lines and branches of the library and of the release +scripts in `scripts/`. The owner wants the README to show it. A coverage +number is only worth showing if a reader can trust that it is current, and +check it. + +## Decision + +- **The docs workflow measures it.** On every run, a `coverage` job in + `docs.yml` runs the tests with coverage. Its output is all that joins the + site; the tests and dev tools never run on the machine that uploads it. It + publishes two files: + - the HTML report at ; + - `coverage.json`, written by `scripts/coverage_badge.py` in the shields.io + endpoint format. + + The README badge reads that file and links to the report. +- **The number is coverage.py's own.** The badge shows coverage.py's display + value, which never rounds 99.9 up to 100. A report without totals fails the + step rather than publish a badge. +- **CI requires 100%** (`fail_under = 100`). A drop fails the pull request, and + on master it also stops the deploy, so the badge never shows a number that + the gate let slip. +- **`scripts/` is measured too.** The scripts decide what reaches PyPI (link + pinning, diagram replacement). Only `if __name__ == "__main__":` lines are + excluded, together with the existing `TYPE_CHECKING` and + impossible-state lines. + +We chose a self-hosted badge over Codecov or Coveralls. Those need an account, +a token in the repository's secrets, and the source sent to a third party, +for the same badge. They would add history graphs, which this project does +not need. + +We chose a measured badge over a static shields.io badge with the number typed +in, because the typed number goes stale at the first change and nothing would +notice. + +## Consequences + +- The badge shows master, like the CI badge, also on the README of older + releases on PyPI. +- 100% is a gate, not a target to game. A state the types rule out is written + so that it has no branch of its own and fails loudly at runtime, rather than + excluded or skipped quietly. +- The docs workflow runs the tests once more than CI does, which adds about + half a minute. We kept that over sharing CI's report across workflows, + because that would couple the deploy to another workflow's artifacts. diff --git a/mkdocs.yml b/mkdocs.yml index 00dd525..797d042 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -144,5 +144,6 @@ nav: - adr/0012-pin-readme-links-at-publish.md - adr/0013-documentation-site.md - adr/0014-mermaid-diagrams.md + - adr/0015-measured-coverage-badge.md - Migrating from 2.x: MIGRATION.md - Changelog: CHANGELOG.md diff --git a/pyproject.toml b/pyproject.toml index ce3c131..26073aa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -69,13 +69,16 @@ pythonpath = ["scripts"] markers = ["integration: needs a running MetaTrader 5 terminal and MT5_* credentials"] [tool.coverage.run] -source = ["PythonMetaTrader5"] +# scripts/ too: they gate every release (link pinning, diagram replacement). +source = ["PythonMetaTrader5", "scripts"] branch = true [tool.coverage.report] -fail_under = 95 +# 100: the README shows the measured coverage, so CI keeps it from slipping +# unnoticed (ADR 0015). +fail_under = 100 show_missing = true -exclude_also = ["if TYPE_CHECKING:", "raise AssertionError"] +exclude_also = ["if TYPE_CHECKING:", "raise AssertionError", "if __name__ == .__main__.:"] [tool.ruff] line-length = 100 diff --git a/scripts/coverage_badge.py b/scripts/coverage_badge.py new file mode 100644 index 0000000..272774c --- /dev/null +++ b/scripts/coverage_badge.py @@ -0,0 +1,45 @@ +"""Turn coverage.py's JSON report into a shields.io endpoint badge (ADR 0015). + +The docs workflow runs the tests on master, writes this next to the site and +the HTML report, and the README badge reads it: the number on the badge is the +number of the last run on master, never one typed in by hand. +""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path + +# Lowest total for each colour, highest first. +COLOURS = ((100.0, "brightgreen"), (95.0, "green"), (90.0, "yellow"), (80.0, "orange")) + + +def colour(percent: float) -> str: + return next((name for floor, name in COLOURS if percent >= floor), "red") + + +def main(argv: list[str]) -> int: + if len(argv) != 2: # noqa: PLR2004 + print("usage: coverage_badge.py ") + return 1 + source, target = Path(argv[0]), Path(argv[1]) + report = json.loads(source.read_text(encoding="utf-8")) + totals = report.get("totals") if isinstance(report, dict) else None + if not totals: + print(f"{source}: no totals; refusing to publish a badge without a measurement") + return 1 + # coverage.py's own display rounding: it never shows 100 for 99.9. + badge = { + "schemaVersion": 1, + "label": "coverage", + "message": f"{totals['percent_covered_display']}%", + "color": colour(totals["percent_covered"]), + } + target.write_text(json.dumps(badge), encoding="utf-8") + print(f"{target}: coverage {badge['message']}") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/src/PythonMetaTrader5/application/batch.py b/src/PythonMetaTrader5/application/batch.py index 3bc9e74..22b4196 100644 --- a/src/PythonMetaTrader5/application/batch.py +++ b/src/PythonMetaTrader5/application/batch.py @@ -44,11 +44,14 @@ def run_batch( succeeded: list[TradeReceipt] = [] errors: list[TradeError] = [] for item in items: - match action(item): - case Ok(receipt): - succeeded.append(receipt) - case Err(error): - errors.append(replace(error, ticket=item.ticket)) + # isinstance, not a match without a fallback: an action that broke the + # Result contract fails loudly on `.value` instead of being skipped, + # which would end in Ok([]), read as "all closed". + result = action(item) + if isinstance(result, Err): + errors.append(replace(result.error, ticket=item.ticket)) + else: + succeeded.append(result.value) if errors: return Err(BatchFailure(tuple(succeeded), tuple(errors))) return Ok(succeeded) diff --git a/tests/unit/test_check_diagrams_main.py b/tests/unit/test_check_diagrams_main.py new file mode 100644 index 0000000..1242460 --- /dev/null +++ b/tests/unit/test_check_diagrams_main.py @@ -0,0 +1,84 @@ +"""check_diagrams.main: each way a run ends, without starting a browser.""" + +from __future__ import annotations + +import subprocess +from pathlib import Path + +import check_diagrams as check +import pytest + +URL = "https://unpkg.com/mermaid@11.17.2/dist/mermaid.min.js" +TAG = f'' +FLOW = "```mermaid\nflowchart LR\n a --> b\n```\n" + + +@pytest.fixture +def site(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + for name in ("README.md", "CHANGELOG.md", "MIGRATION.md"): + (tmp_path / name).write_text(FLOW if name == "README.md" else "", encoding="utf-8") + (tmp_path / "docs").mkdir() + (tmp_path / "overrides").mkdir() + (tmp_path / "overrides" / "main.html").write_text(TAG, encoding="utf-8") + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("DIAGRAM_BROWSER", "browser") + return tmp_path + + +def browser_returns(monkeypatch: pytest.MonkeyPatch, stdout: str, stderr: str = "") -> None: + def fake(executable: str, content: str) -> subprocess.CompletedProcess[str]: + assert 'integrity="sha384-abc"' in content + return subprocess.CompletedProcess([executable], 0, stdout, stderr) + + monkeypatch.setattr(check, "render", fake) + + +def test_every_diagram_parsing_passes( + site: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + browser_returns(monkeypatch, '
["OK   README.md#1"]
') + assert check.main([]) == 0 + assert "all 1 Mermaid diagrams parse" in capsys.readouterr().out + + +def test_a_page_without_verdicts_reports_the_browser_output( + site: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + browser_returns(monkeypatch, '
pending
', stderr="sandbox failed") + assert check.main([]) == 1 + assert "browser exit 0: sandbox failed" in capsys.readouterr().out + + +def test_a_site_without_a_pinned_mermaid_fails( + site: Path, capsys: pytest.CaptureFixture[str] +) -> None: + (site / "overrides" / "main.html").write_text("", encoding="utf-8") + assert check.main([]) == 1 + assert "no pinned Mermaid" in capsys.readouterr().out + + +def test_an_unextractable_fence_fails_before_any_browser_runs( + site: Path, capsys: pytest.CaptureFixture[str] +) -> None: + (site / "README.md").write_text("~~~mermaid\nflowchart LR\n a --> b\n~~~\n", encoding="utf-8") + assert check.main([]) == 1 + assert "form not checked" in capsys.readouterr().out + + +def test_no_browser_found_fails( + site: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.delenv("DIAGRAM_BROWSER") + monkeypatch.setattr(check.shutil, "which", lambda name: None) + monkeypatch.setattr(check, "EDGE", site / "no-edge.exe") + assert check.main([]) == 1 + assert "set DIAGRAM_BROWSER" in capsys.readouterr().out + + +def test_edge_is_the_fallback_on_windows(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + edge = tmp_path / "msedge.exe" + edge.write_text("", encoding="utf-8") + monkeypatch.delenv("DIAGRAM_BROWSER", raising=False) + monkeypatch.setattr(check.shutil, "which", lambda name: None) + monkeypatch.setattr(check, "EDGE", edge) + assert check.browser() == str(edge) diff --git a/tests/unit/test_check_file_length.py b/tests/unit/test_check_file_length.py index efa07ea..203d8ff 100644 --- a/tests/unit/test_check_file_length.py +++ b/tests/unit/test_check_file_length.py @@ -2,6 +2,7 @@ from __future__ import annotations +import subprocess from pathlib import Path import check_file_length as script @@ -41,3 +42,18 @@ def test_only_the_top_level_readme_is_exempt( ) -> None: code = run_on(tmp_path, monkeypatch, "docs/README.md", 301) assert code == 1 + + +def test_binary_files_are_not_counted(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + assert run_on(tmp_path, monkeypatch, "docs/assets/logo.png", 5000) == 0 + + +def test_the_files_checked_are_the_ones_git_tracks(monkeypatch: pytest.MonkeyPatch) -> None: + # git itself is faked: the test must pass outside a checkout too. + def ls_files(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]: + assert command == ["git", "ls-files"] + listing = "\n".join(["README.md", "docs/a.md", "", ""]) + return subprocess.CompletedProcess(command, 0, listing, "") + + monkeypatch.setattr(script.subprocess, "run", ls_files) + assert script.tracked_files() == [Path("README.md"), Path("docs/a.md")] diff --git a/tests/unit/test_coverage_badge.py b/tests/unit/test_coverage_badge.py new file mode 100644 index 0000000..9fc11a1 --- /dev/null +++ b/tests/unit/test_coverage_badge.py @@ -0,0 +1,63 @@ +"""The coverage badge is computed from the report of the run, never typed in.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import coverage_badge as badge +import pytest + + +def report(tmp_path: Path, display: str) -> Path: + path = tmp_path / "coverage.json" + totals = {"percent_covered_display": display, "percent_covered": float(display)} + path.write_text(json.dumps({"totals": totals}), encoding="utf-8") + return path + + +def test_the_badge_shows_the_report_total(tmp_path: Path) -> None: + out = tmp_path / "badge.json" + assert badge.main([str(report(tmp_path, "100")), str(out)]) == 0 + assert json.loads(out.read_text(encoding="utf-8")) == { + "schemaVersion": 1, + "label": "coverage", + "message": "100%", + "color": "brightgreen", + } + + +@pytest.mark.parametrize( + ("display", "color"), + [("100", "brightgreen"), ("97", "green"), ("90", "yellow"), ("80", "orange"), ("50", "red")], +) +def test_the_colour_drops_with_the_total(tmp_path: Path, display: str, color: str) -> None: + out = tmp_path / "badge.json" + badge.main([str(report(tmp_path, display)), str(out)]) + assert json.loads(out.read_text(encoding="utf-8"))["color"] == color + + +def test_a_report_without_totals_fails_instead_of_a_made_up_badge( + tmp_path: Path, capsys: pytest.CaptureFixture[str] +) -> None: + source = tmp_path / "coverage.json" + source.write_text("{}", encoding="utf-8") + out = tmp_path / "badge.json" + assert badge.main([str(source), str(out)]) == 1 + assert not out.exists() + assert "no totals" in capsys.readouterr().out + + +@pytest.mark.parametrize("content", ["[]", '{"totals": {}}']) +def test_a_report_of_another_shape_is_refused_with_a_message( + tmp_path: Path, capsys: pytest.CaptureFixture[str], content: str +) -> None: + source = tmp_path / "coverage.json" + source.write_text(content, encoding="utf-8") + assert badge.main([str(source), str(tmp_path / "badge.json")]) == 1 + assert "no totals" in capsys.readouterr().out + + +def test_a_missing_argument_prints_the_usage(capsys: pytest.CaptureFixture[str]) -> None: + assert badge.main(["coverage.json"]) == 1 + assert "usage:" in capsys.readouterr().out diff --git a/tests/unit/test_replace_readme_diagrams.py b/tests/unit/test_replace_readme_diagrams.py index 725fb87..da167c7 100644 --- a/tests/unit/test_replace_readme_diagrams.py +++ b/tests/unit/test_replace_readme_diagrams.py @@ -133,3 +133,21 @@ def test_a_longer_backtick_fence_closes_a_diagram_as_on_github( path = readme(tmp_path, monkeypatch, text) assert diagrams.main([]) == 0 assert "\nKept.\n\n```\ncode\n```\n" in path.read_bytes().decode("utf-8") + + +def test_a_diagram_before_any_heading_links_the_readme_itself( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + path = readme(tmp_path, monkeypatch, FLOW) + assert diagrams.main([]) == 0 + assert f"]({diagrams.README})" in path.read_bytes().decode("utf-8") + + +def test_a_diagram_holding_a_fence_line_is_refused_and_the_readme_kept( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + original = "## A\n\n```mermaid\n~~~\nflowchart LR\n```\n" + path = readme(tmp_path, monkeypatch, original) + assert diagrams.main([]) == 1 + assert "swallowed a code block" in capsys.readouterr().out + assert path.read_bytes().decode("utf-8") == original diff --git a/tests/unit/test_safety_edges.py b/tests/unit/test_safety_edges.py index bb2c69f..768828a 100644 --- a/tests/unit/test_safety_edges.py +++ b/tests/unit/test_safety_edges.py @@ -7,6 +7,7 @@ from PythonMetaTrader5 import Broker, connect from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.batch import run_batch from PythonMetaTrader5.application.ports import Credentials from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind @@ -176,3 +177,11 @@ def test_adapter_releases_the_session_after_a_failed_login() -> None: mt5.initialize_ok = False assert isinstance(MetaTrader5Terminal(mt5).connect(Credentials(1, "pw", "s")), Err) assert [name for name, _, _ in mt5.calls] == ["initialize", "shutdown"] + + +def test_a_batch_action_that_returns_no_result_fails_loudly() -> None: + # Skipping it would report Ok([]), "everything closed", with the position + # still open. The types forbid it; at runtime it must not pass in silence. + position = make_position() + with pytest.raises(AttributeError): + run_batch([position], lambda item: object()) # type: ignore[arg-type,return-value]