add doc coverage

Author: tipatterson-dev

.github/workflows/tests.yaml

@@ -34,5 +34,18 @@ jobs:
       # They're tagged `@pytest.mark.network` and skipped here. The plan is
       # to shim those with mocks; once a test no longer needs a real server,
       # drop the marker and it will run in CI automatically.
-      - name: Run pytest
-        run: uv run --python ${{ matrix.python-version }} pytest -v -m "not network"
+      - name: Run pytest with coverage
+        run: |
+          uv run --python ${{ matrix.python-version }} pytest -v \
+            -m "not network" \
+            --cov --cov-report=term --cov-report=xml
+
+      # Keep coverage.xml around so a later badge/Codecov upload step can use it.
+      - name: Upload coverage report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: warn
+          retention-days: 7

README.md

@@ -9,6 +9,60 @@ Links:
  * [Architecture Doc](https://docs.google.com/document/d/1pIaeQw0ocU6ApNgqTVRZuSwjJAbhCcmweMq6RiVYEic/edit?usp=sharing)
  * [UML Diagram](https://drive.google.com/file/d/1FVrnYiuAR8ykqfOUa1NuoMyZ1abXzMPw/view?usp=drive_link)
 
+## Running Tests
+
+```bash
+uv sync                                # install dev deps (incl. pytest, pytest-cov)
+uv run pytest                          # full suite (skips network-marked tests if you add `-m "not network"`)
+uv run pytest tests/test_swe_components.py -v   # one file, verbose
+uv run pytest -k name_token            # one keyword
+```
+
+Tests that need a live OSH server (e.g. `localhost:8282` running
+FakeWeatherDriver) are tagged `@pytest.mark.network`. CI skips them; locally
+you can include or exclude them:
+
+```bash
+uv run pytest -m "not network"         # what CI runs
+uv run pytest -m network               # only the live-server tests
+```
+
+## Test Coverage
+
+Coverage is opt-in via [`pytest-cov`](https://pytest-cov.readthedocs.io/). The
+default `pytest` run is fast; add `--cov` when you want a report.
+
+```bash
+uv run pytest --cov                    # terminal summary + missing lines
+uv run pytest --cov --cov-report=html  # HTML report at htmlcov/index.html
+uv run pytest --cov --cov-report=xml   # coverage.xml (CI / Codecov-ready)
+```
+
+Configuration lives in `pyproject.toml` under `[tool.coverage.*]` — branch
+coverage is on, source is scoped to `src/oshconnect`, and obvious dead lines
+(`if TYPE_CHECKING:`, `raise NotImplementedError`, etc.) are excluded.
+
+CI (`.github/workflows/tests.yaml`) runs the suite with `--cov` on every push
+across Python 3.12 / 3.13 / 3.14 and uploads `coverage.xml` as a workflow
+artifact (downloadable from the run page).
+
+## Documentation Coverage
+
+[`interrogate`](https://interrogate.readthedocs.io/) reports what fraction of
+public modules / classes / functions / methods carry a docstring (presence
+only, it doesn't check style). It's purely informational right now; there's
+no CI gate. Configuration lives in `pyproject.toml` under `[tool.interrogate]`
+(`__init__`, dunder, private, and property/setter members are skipped).
+
+```bash
+uv run interrogate src/oshconnect              # one-line summary
+uv run interrogate -v src/oshconnect           # per-file table
+uv run interrogate -vv src/oshconnect          # per-symbol (shows which symbols are missing)
+```
+
+Once we agree on a baseline, raise `[tool.interrogate].fail-under` from `0` so
+new code without docstrings starts failing locally and in CI.
+
 ## Generating the Docs
 
 The documentation is built with [MkDocs](https://www.mkdocs.org/) using the

pyproject.toml

@@ -19,6 +19,8 @@ dependencies = [
 dev = [
     "flake8>=7.2.0",
     "pytest>=8.3.5",
+    "pytest-cov>=5.0.0",
+    "interrogate>=1.7.0",
     "sphinx>=7.4.7",
     "sphinx-rtd-theme>=2.0.0",
     "mkdocs-material>=9.5.0",
@@ -34,3 +36,41 @@ pythonpath = ["src"]
 markers = [
     "network: test requires a live OSH server or external network endpoint (skipped by default in CI; see workflow `tests.yaml`).",
 ]
+
+# Coverage is opt-in (run with `pytest --cov`) so the default `pytest` run stays fast.
+# `--cov` with no argument picks up the source paths configured below.
+
+[tool.coverage.run]
+source = ["src/oshconnect"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+precision = 2
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "@(abc\\.)?abstractmethod",
+    "if __name__ == .__main__.:",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[tool.coverage.xml]
+output = "coverage.xml"
+
+# Docstring presence (not style). Run with `uv run interrogate -v src/oshconnect`.
+[tool.interrogate]
+ignore-init-method = true       # constructors covered by class docstring
+ignore-init-module = true       # don't require docstrings on bare __init__.py
+ignore-magic = true             # skip dunder methods (__repr__, __eq__, etc.)
+ignore-private = true           # skip _name and __name (non-dunder) members
+ignore-property-decorators = true
+ignore-nested-functions = true
+ignore-setters = true
+fail-under = 0                  # report-only for now; raise once a baseline is set
+exclude = ["tests", "docs", "build", ".venv", "scripts"]
+verbose = 2                     # 0=summary, 1=per-file, 2=per-symbol