Enhance the Tests section with best practices for clarity and documentation

[akhilkrishnar0]

Hi everyone,

I'd like to propose adding a new “Tests” section to the packaging guide that outlines best practices for writing clear, well-documented tests. This idea came up in a recent conversation https://github.com/pyOpenSci/software-peer-review/issues/201, where we discussed the value of making tests easier for reviewers and contributors to understand.

Here’s what the new section could include:

• Use of meaningful test names that reflect what is being tested
• Docstrings or comments in test functions/modules that describe the purpose of the test
• Clear test structure and organisation
• Simple examples of good and bad test documentation practices

This would help both reviewers (who need to understand what’s being tested) and new contributors (who may want to add tests or debug). Thanks to @ucodery for suggesting that I open this issue to get the conversation started. Any comments or contributions are invited.

[akhilkrishnar0]

I found that tests are already covered in this issue: https://github.com/pyOpenSci/python-package-guide/issues/59#issuecomment-2873607531

I'm realising now that the current "Tests" section already does a solid job of covering the basics. As a beginner, I don’t feel I can meaningfully contribute more at this stage, so I’ll step back and leave this issue open in case someone with more experience wants to build on it. I'm happy to revisit this in the future as I gain more insight.

[lwasser]

@all-contributors add @akhilkrishnar0 for ideas, review

[allcontributors[bot]]

@lwasser

I've put up a pull request to add @akhilkrishnar0! :tada:

[lwasser]

hey @akhilkrishnar0 I can add this issue to our help-wanted board. Could you provide some more details around what you'd like to see added to that section? I'm asking for this because it will make it easier for someone else to pick things up if we know what is missing!! Many thanks!

[eliotwrobson]

Is this something we should link to other resources for? I think there's been plenty written about best practices for writing tests in Python, and there's nothing that I think applies specifically to just packages we care about.