From 6d5e09c133e84e2bf805c3856b04337048002354 Mon Sep 17 00:00:00 2001 From: Salkutsan Aleksey Date: Mon, 6 Jul 2026 03:56:43 +0200 Subject: [PATCH] docs: clarify test readability guidance --- tests/write-tests.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/tests/write-tests.md b/tests/write-tests.md index adae75f7..e06637fe 100644 --- a/tests/write-tests.md +++ b/tests/write-tests.md @@ -100,6 +100,29 @@ test_add_numbers() ``` ```` +### Write tests that are easy to review + +Clear tests help reviewers and future contributors understand what behavior is +being checked and why that behavior matters. As you write tests, try to make the +main idea of each test visible without requiring readers to reverse-engineer the +setup. + +- **Use descriptive test names:** Name each test after the behavior, condition, + or edge case it checks. For example, `test_add_numbers_accepts_negative_values` + tells readers more than `test_add_numbers_2`. +- **Keep one main behavior in focus:** A test can contain several assertions, but + they should support one clear idea. If a test starts checking several unrelated + behaviors, split it into smaller tests. +- **Add comments only where they help:** A short comment is useful when a + fixture, regression, or unusual edge case is not obvious from the assertion. + Avoid comments that repeat the code. +- **Keep setup, action, and assertion easy to scan:** Arrange the test so readers + can quickly see what input is prepared, what code is run, and what result is + expected. + +For maintained testing references, see the [pytest documentation](https://docs.pytest.org/) +and the Python documentation for [`unittest`](https://docs.python.org/3/library/unittest.html). + ### 🧩🐍 How do you know what type of tests to write? As you begin to write tests for your package, you should consider: