From 6d5e09c133e84e2bf805c3856b04337048002354 Mon Sep 17 00:00:00 2001 From: Salkutsan Aleksey Date: Mon, 6 Jul 2026 03:56:43 +0200 Subject: [PATCH 1/2] 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 adae75f75..e06637fee 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: From 57f60a969b5736177c1bc42c474de9ed4b1157d7 Mon Sep 17 00:00:00 2001 From: kernelpanic888 <48477233+kernelpanic888@users.noreply.github.com> Date: Fri, 4 Sep 2026 01:11:09 +0200 Subject: [PATCH 2/2] docs: address test readability review --- tests/write-tests.md | 66 +++++++++++++++++++++++++++++--------------- 1 file changed, 43 insertions(+), 23 deletions(-) diff --git a/tests/write-tests.md b/tests/write-tests.md index e06637fee..f34654738 100644 --- a/tests/write-tests.md +++ b/tests/write-tests.md @@ -100,29 +100,6 @@ 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: @@ -156,6 +133,49 @@ package? Below are a few examples: user can easily understand why it failed by providing a useful error message. +### 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 example, a test based on the `add_numbers` function in the +[pyOpenSci Python package template](https://github.com/pyOpenSci/pyos-package-template) +can make its inputs, action, and expected result visible at a glance: + +```python +from my_package.example import add_numbers + + +def test_add_numbers_returns_sum(): + first_number = 1 + second_number = 2 + expected_sum = 3 + + actual_sum = add_numbers(first_number, second_number) + + assert actual_sum == expected_sum +``` + +For more guidance on structuring readable tests, see pytest's +[anatomy of a test](https://docs.pytest.org/en/stable/explanation/anatomy.html), +which explains the arrange, act, assert, and cleanup phases, and the package +template's [example unit test](https://github.com/pyOpenSci/pyos-package-template/blob/main/template/%7B%25%20if%20use_test%20%25%7Dtests%7B%25%20endif%20%25%7D/unit/test_example.py.jinja). + ## Next steps Now that you understand what and why to test, explore the [three types of