Merge branch 'main' into create-pull-request/patch

nathanjmcdougall · web-flow · commit 5b8d285cb275 · 2026-04-09T13:31:47.000+12:00
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."""`