Add test placement guidance to usethis-python-test skill (#1898)

Copilot · nathanjmcdougall · web-flow · commit 5e08de18390b · 2026-04-09T13:17:05.000+12:00
* Initial plan * Update usethis-python-test skill with test placement guidance (v1.3 → v1.4) Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/c190dab3-7bae-474b-8b73-f1f67ec0ea5b Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
diff --git a/.agents/skills/usethis-python-test/SKILL.md b/.agents/skills/usethis-python-test/SKILL.md
@@ -4,7 +4,7 @@ description: General guidelines for writing tests in the usethis project, includ
 compatibility: usethis, Python, pytest
 license: MIT
 metadata:
-  version: "1.3"
+  version: "1.4"
 ---
 
 # Python Test Guidelines
@@ -49,6 +49,14 @@ Nesting can go two or three levels deep when the logical structure demands it. F
 
 Use the minimum depth needed to clearly communicate the test's context. Avoid nesting beyond three levels.
 
+### Test file placement mirrors source file structure
+
+Tests for a class method must live in the test file that corresponds to the source file where the class is defined — not in a test file for a utility that the method happens to call internally.
+
+If a method is defined on `SomeClass` in `some_module.py`, its tests belong under `TestSomeClass` in `test_some_module.py`, regardless of which helper utilities the method uses at runtime.
+
+Placing tests near the utility they exercise (rather than near the class they belong to) breaks the structural correspondence between source and test files, making tests harder to find and maintain.
+
 ### No docstrings on test classes or functions
 
 Test classes and test functions should not have docstrings. The class and function names should be descriptive enough to communicate what is being tested.
