Remove redundant docstrings from test classes (#1897)

Copilot · nathanjmcdougall · web-flow · commit 600a402d341f · 2026-04-09T13:31:33.000+12:00
* Initial plan * remove docstrings from test classes in test files Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/61fa31b6-ac9b-4a7c-bd46-f528bb0630aa Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> * restore docstrings on TestAllBadgesMarkdownValid and TestIconFallbackIntegration; refine skill guidance Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/44fe822c-6d64-4f38-8f80-cbbf2c0d44b3 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> * fix: remove extra blank line in SKILL.md to pass markdownlint Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/505fdfca-5f9f-4c45-a3b0-7f10d683c33d 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> Co-authored-by: Nathan McDougall <nathan.j.mcdougall@gmail.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.4"
+  version: "1.5"
 ---
 
 # Python Test Guidelines
@@ -57,9 +57,11 @@ If a method is defined on `SomeClass` in `some_module.py`, its tests belong unde
 
 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
+### No redundant 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.
+Avoid adding docstrings to test classes and test functions when the name alone is sufficient. For example, `"""Tests for validate_or_raise."""` on `TestValidateOrRaise` is redundant — the class name already communicates this.
+
+However, a docstring is appropriate when it adds genuinely new information that the name does not convey, such as explaining the test strategy, describing a non-obvious constraint, or clarifying how the test output is validated.
 
 ## Using `files_manager` in tests
 
diff --git a/tests/usethis/_core/test_core_tool.py b/tests/usethis/_core/test_core_tool.py
@@ -2234,8 +2234,6 @@ def test_hooks_run_all_tools_empty_repo(self, uv_env_dir: Path):
                 )
 
     class TestMigration:
-        """Test migration of tools to/from pre-commit (issue #1020)."""
-
         @pytest.mark.usefixtures("_vary_network_conn")
         def test_deps_not_removed_when_migrating_to_pre_commit(self, uv_init_dir: Path):
             """Test that deps are NOT removed when migrating to pre-commit."""
diff --git a/tests/usethis/_file/yaml/test_yaml_io_.py b/tests/usethis/_file/yaml/test_yaml_io_.py
@@ -1139,8 +1139,6 @@ def relative_path(self) -> Path:
 
 class TestEditYaml:
     class TestLiterals:
-        """The list of literals is from ruamel/yaml/representer.py near the bottom."""
-
         def test_none(self, tmp_path: Path):
             # Arrange
             path = tmp_path / "test.yaml"
diff --git a/tests/usethis/_integrations/pre_commit/test_hooks.py b/tests/usethis/_integrations/pre_commit/test_hooks.py
@@ -766,8 +766,6 @@ def test_aliases(self):
 
 
 class TestAddRepoPipeweld:
-    """Integration tests for pipeweld-based hook insertion."""
-
     def test_insert_between_nondependent_and_postrequisite(self, tmp_path: Path):
         """Insert a recognized hook between an unrecognized hook and a postrequisite."""
         with change_cwd(tmp_path), files_manager():
diff --git a/tests/usethis/_pipeweld/test_func.py b/tests/usethis/_pipeweld/test_func.py
@@ -174,8 +174,6 @@ def test_nested_series(self):
             assert result.solution == series(series(parallel("A", "B")))
 
         class TestDoubleNesting:
-            """A series of related tests building up to a complex case."""
-
             def test_no_nesting(self):
                 # Arrange
                 adder = Adder(
diff --git a/tests/usethis/_tool/impl/base/test_deptry.py b/tests/usethis/_tool/impl/base/test_deptry.py
@@ -10,8 +10,6 @@
 
 
 class TestDeptryTool:
-    """Tests for DeptryTool."""
-
     def test_get_pyproject_id_keys(self):
         """Test that get_pyproject_id_keys returns the correct keys."""
         # Arrange

Original file line number	Diff line number	Diff line change
`@@ -2234,8 +2234,6 @@ def test_hooks_run_all_tools_empty_repo(self, uv_env_dir: Path):`
`2234`	`2234`	`)`
`2235`	`2235`
`2236`	`2236`	`class TestMigration:`
`2237`		`- """Test migration of tools to/from pre-commit (issue #1020)."""`
`2238`		`-`
`2239`	`2237`	`@pytest.mark.usefixtures("_vary_network_conn")`
`2240`	`2238`	`def test_deps_not_removed_when_migrating_to_pre_commit(self, uv_init_dir: Path):`
`2241`	`2239`	`"""Test that deps are NOT removed when migrating to pre-commit."""`