Skip to content

Give clearer guidance regarding the use of docstrings in the test suite #1302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nathanjmcdougall merged 1 commit into from
Feb 20, 2026
Merged

Give clearer guidance regarding the use of docstrings in the test suite #1302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ uv run pytest -k "test_help" -v
- Use arrange-act-assert structure with comments separating sections
- Only one contiguous block of assertions in assert section
- Tests organized into classes: `TestMyClass` containing `TestMyMethod` for nested method tests
- Test classes and functions should not have docstrings; descriptive names should suffice
- **No side-effects**: Tests must not modify, create, or delete files in the repository directory
- Always use pytest's `tmp_path` fixture for file operations
- Always use `usethis._test.change_cwd` context manager when testing code that operates on the current working directory
Expand Down Expand Up @@ -246,7 +247,8 @@ Follow the guide in CONTRIBUTING.md:
**Docstrings:**
- Google style format
- NO type annotations in docstrings (already in function signature)
- Example: `text:` not `text (str):`
- Example: `text:` not `text (str):
- Do not use in the test suite unless explicitly instructed

**Linting:**
- Avoid suppressions unless absolutely necessary
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ uv run pytest

Tests are written using the `pytest` framework. The test suite is located in the `tests` directory. The tests are organized into subdirectories with a directory structure that mirrors the structure of the code being tested. This makes it easy to find the tests for a specific module or function. For example: `src/x/y/z.py` would be tested at `tests/x/y/test_z.py`.

Tests are usually organized into classes centred around the objects being tested; either modules or classes. For example, tests for a class `MyClass` would be tested in a class `TestMyClass`. If testing a method of a class, the method tests would be nested within the class test. For example, tests for the `my_method` method of `MyClass` would be in a nested class `TestMyMethod` within `TestMyClass`.
Tests are usually organized into classes centred around the objects being tested; either modules or classes. For example, tests for a class `MyClass` would be tested in a class `TestMyClass`. If testing a method of a class, the method tests would be nested within the class test. For example, tests for the `my_method` method of `MyClass` would be in a nested class `TestMyMethod` within `TestMyClass`. These classes, and the test functions themselves do not usually need docstrings, and their use is discouraged. The test function names are usually descriptive enough to make it clear what is being tested.

PRs should ideally include tests for any new features or bug fixes.

Expand Down