From e7b4613471939e051a80aa3bfd0979054af74848 Mon Sep 17 00:00:00 2001
From: Jeff Smith <jeff@unbiasedgeek.com>
Date: Mon, 6 Apr 2026 17:06:41 -0600
Subject: [PATCH] =?UTF-8?q?wiki:=20document=20testing=20=E2=80=94=20covera?=
 =?UTF-8?q?ge=20table,=20requirements,=20how=20to=20add=20new=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DevelopmentGuide.md | 60 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/DevelopmentGuide.md b/DevelopmentGuide.md
index 5ab340e..a82332f 100644
--- a/DevelopmentGuide.md
+++ b/DevelopmentGuide.md
@@ -89,6 +89,57 @@ git branch -d <branch>
 
 ---
 
+## Testing
+
+### Running tests
+
+```bash
+python3 -m unittest discover -s tests/ -v
+```
+
+No dependencies needed — the test suite uses stdlib `unittest` only.
+
+### Test coverage
+
+Tests live in `tests/`, one file per module:
+
+| Test file | Module covered |
+|---|---|
+| `test_cache.py` | `cache.py` — entry validation, confidence fields, investigation IDs |
+| `test_filetypes.py` | `filetypes.py` — extension classification, `classify_files`, `summarize_categories` |
+| `test_code.py` | `code.py` — language detection, LOC counting, large file detection |
+| `test_disk.py` | `disk.py` — disk usage parsing, `_human_size`, `top_directories` |
+| `test_recency.py` | `recency.py` — recent file detection, output parsing |
+| `test_tree.py` | `tree.py` — tree building, rendering, hidden/exclude logic |
+| `test_report.py` | `report.py` — `format_flags`, `format_report`, all sections |
+| `test_capabilities.py` | `capabilities.py` — `_check_package` |
+
+Modules **not covered** (exempt from unit testing):
+
+| Module | Reason |
+|---|---|
+| `ai.py` | Requires live Anthropic API |
+| `ast_parser.py` | Requires tree-sitter optional dep |
+| `watch.py` | Stateful filesystem event loop |
+| `prompts.py` | String templates with no logic |
+
+### Test requirements
+
+- Every change to a covered module must include or update its tests
+- All 129 tests must pass before merging to main
+- Subprocess-heavy functions (`wc`, `du`, `find`, `file`) are tested via `unittest.mock` — no real filesystem calls needed
+- Tests that require real filesystem interaction use `tempfile.mkdtemp()` and clean up automatically
+
+### Adding tests for new modules
+
+1. Create `tests/test_<module>.py`
+2. Import from `luminos_lib.<module>`
+3. Use `unittest.TestCase` subclasses
+4. Mock subprocess calls with `unittest.mock.patch("subprocess.run", ...)`
+5. Add the new file to the table above
+
+---
+
 ## Naming Conventions
 
 | Context | Convention | Example |
@@ -120,6 +171,15 @@ luminos/
 │   ├── report.py           terminal report formatter
 │   ├── tree.py             directory tree
 │   └── watch.py            watch mode
+├── tests/
+│   ├── test_cache.py
+│   ├── test_capabilities.py
+│   ├── test_code.py
+│   ├── test_disk.py
+│   ├── test_filetypes.py
+│   ├── test_recency.py
+│   ├── test_report.py
+│   └── test_tree.py
 ├── docs/wiki/              local clone of Forgejo wiki (gitignored)
 ├── setup_env.sh            venv + AI dep setup script
 ├── CLAUDE.md               Claude Code context (thin — points to wiki)