chore: more claude unit test improvements

- install pyright and pyright-lsp for better python symbol navigation
- overhaul the unit-tests skill to limit coverage generation to domain tests

Author: pwnage101

.claude/settings.json

@@ -4,5 +4,8 @@
       "Skill(quality-tests)",
       "Skill(unit-tests)"
     ]
+  },
+  "enabledPlugins": {
+    "pyright-lsp@anthropic-tools": true
   }
 }

.claude/skills/unit-tests/SKILL.md

@@ -7,14 +7,21 @@ allowed-tools: Bash(docker *), Bash(make *)
 
 ## Arguments
 
-`<TEST_FILES>` (optional): One or more test file paths or pytest node IDs to run. When provided, only the specified tests are run and coverage is disabled (`--no-cov`). When omitted, the full test suite runs with coverage enabled.
+`<TEST_FILES>` (optional): One or more folders, test file paths, or pytest node IDs to run. Coverage is only enabled when a single folder representing a code domain is provided or no arguments are provided.
 
 Examples:
 - `/unit-tests` — run all tests with coverage
+- `/unit-tests enterprise_access/apps/bffs` — run all bff domain tests with domain-only coverage
 - `/unit-tests enterprise_access/apps/customer_billing/tests/test_models.py` — run one test file without coverage
 - `/unit-tests enterprise_access/apps/subsidy_access_policy/tests/test_models.py enterprise_access/apps/content_assignments/tests/test_api.py` — run multiple test files without coverage
 - `/unit-tests enterprise_access/apps/customer_billing/tests/test_models.py::TestSomeClass::test_method` — run a single test by node ID without coverage
 
+## Routing rules (evaluate in order)
+
+- **No arguments** → Step 2c (whole-project tests + whole-project coverage)
+- **Single argument that is a directory** (no `.py`, no `::`) → Step 2b (domain tests + domain coverage). Never enable coverage when testing specific files — only for domain or whole-project runs.
+- **Everything else** (`.py` files, node IDs, multiple args) → Step 2a (targeted tests, NO coverage)
+
 ## Steps
 
 ### 1. Make sure the app container is running
@@ -31,16 +38,49 @@ Start the app container if not running:
 make dev.up
 ```
 
-### 2. Run unit tests
+### 2a. Run specific unit test files or functions
 
-If `<TEST_FILES>` argument(s) are given, run only those tests with coverage disabled:
+If `<TEST_FILES>` specify .py files or functions/classes within, run only those tests using `pytest.local.ini` to disable coverage and warnings:
 
 ```bash
-docker exec enterprise-access.app bash -c "DJANGO_SETTINGS_MODULE=enterprise_access.settings.test pytest --no-cov <TEST_FILES>"
+docker exec enterprise-access.app bash -c "pytest -c pytest.local.ini <TEST_FILES>"
 ```
 
-If no arguments are given, run the full test suite with coverage enabled:
+Example `<TEST_FILES>` which match this case:
+- enterprise_access/apps/customer_billing/tests/test_models.py
+- enterprise_access/apps/subsidy_access_policy/tests/test_models.py enterprise_access/apps/content_assignments/tests/test_api.py
+- enterprise_access/apps/customer_billing/tests/test_models.py::TestSomeClass::test_method
+
+Never enable coverage reports (by adding `--cov`) when only testing specific files, since the results will be misleading.
+
+### 2b. Run domain unit tests and generate domain-only coverage
+
+If `<TEST_FILES>` specifies a single directory which represent a domain, such as a django app, enable coverage.
+
+Convert the directory path to a Python module path for `--cov`: replace `/` with `.` and strip any trailing slash. Example: `enterprise_access/apps/bffs/` → `enterprise_access.apps.bffs`
 
 ```bash
-docker exec enterprise-access.app bash -c "DJANGO_SETTINGS_MODULE=enterprise_access.settings.test pytest"
+docker exec enterprise-access.app bash -c "pytest -c pytest.local.ini <TEST_DOMAIN> --cov=<MODULE_PATH_OF_TEST_DOMAIN>"
+
+# Example: <TEST_FILES> is "enterprise_access/apps/bffs"
+docker exec enterprise-access.app bash -c "pytest -c pytest.local.ini enterprise_access/apps/bffs --cov=enterprise_access.apps.bffs"
 ```
+
+Example `<TEST_FILES>` which match this case:
+- enterprise_access/apps/api
+- enterprise_access/apps/api_client/
+- enterprise_access/apps/bffs
+- enterprise_access/apps/content_assignments/
+- enterprise_access/apps/customer_billing/
+
+Whole-domain coverage will be reported in the console output. Specific line numbers with missing coverage will be reported.
+
+### 2c. Run whole-project unit tests and generate coverage
+
+If no arguments are given, assume the user wants to run the full test suite for the entire project:
+
+```bash
+docker exec enterprise-access.app bash -c "make test"
+```
+
+Whole-project coverage will be reported in the console output. Specific line numbers with missing coverage will be reported.

pytest.ini

@@ -1,3 +1,11 @@
+# Standard settings used by CI and Makefile targets.
+#
+# Designed to run all tests and produce comprehensive coverage reporting.
+#
+# Example usage:
+# ```
+# pytest
+# ```
 [pytest]
 DJANGO_SETTINGS_MODULE = enterprise_access.settings.test
 addopts = --cov enterprise_access --cov-report term-missing --cov-report xml

pytest.local.ini

@@ -1,8 +1,21 @@
-# This makes it easier to get coverage reports for only specific modules
-# when running pytest locally, for example:
-# pytest -x enterprise_access/apps/events/  --cov=enterprise_access.apps.events -c pytest.local.ini
+# pytest settings optimized for development cycles.
+#
+# Differences from pytest.ini:
+# - Removing `--cov enterprise_access` makes it possible to scope coverage reports to specific modules.
+# - Warning are ignored.
+#
+# Example usage:
+# ```
+# # Test only one domain and report coverage only for that domain:
+# pytest -c pytest.local.ini enterprise_access/apps/events/ --cov=enterprise_access.apps.events
+# pytest -c pytest.local.ini enterprise_access/apps/bffs/ --cov=enterprise_access.apps.bffs
+#
+# # Test only one file or function without generating coverage.
+# pytest -c pytest.local.ini enterprise_access/apps/bffs/tests/test_checkout_handlers.py
+# ```
 [pytest]
-addopts = --cov-report term-missing --cov-report xml -W ignore --ds=enterprise_access.settings.test
+DJANGO_SETTINGS_MODULE = enterprise_access.settings.test
+addopts = --cov-report term-missing --cov-report xml -W ignore
 norecursedirs = .* docs requirements site-packages scripts
 
 # Filter depr warnings coming from packages that we can't control.

requirements/dev.in

@@ -6,4 +6,5 @@
 diff-cover                # Changeset diff test coverage
 edx-i18n-tools            # For i18n_tool dummy
 django-debug-toolbar      # For debugging Django
+pyright                   # For optimizing Claude Code reads.
 #transifex-client         # For managing translations

requirements/dev.txt

@@ -439,6 +439,8 @@ nh3==0.3.3
     # via
     #   -r requirements/validation.txt
     #   readme-renderer
+nodeenv==1.10.0
+    # via pyright
 oauthlib==3.3.1
     # via
     #   -r requirements/validation.txt
@@ -557,6 +559,8 @@ pyproject-hooks==1.2.0
     #   -r requirements/pip-tools.txt
     #   build
     #   pip-tools
+pyright==1.1.408
+    # via -r requirements/dev.in
 pytest==9.0.2
     # via
     #   -r requirements/validation.txt
@@ -707,6 +711,7 @@ typing-extensions==4.15.0
     #   cattrs
     #   django-countries
     #   edx-opaque-keys
+    #   pyright
     #   referencing
     #   stripe
 tzdata==2025.3