pytest-best-practices

cfircoo's avatarfrom cfircoo

Expert guidance for writing high-quality pytest tests. Use when writing tests, setting up fixtures, parametrizing, mocking, or reviewing test code.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Testing and QA]

When & Why to Use This Skill

This Claude skill provides expert guidance on Python testing using the pytest framework. It helps developers implement high-quality test suites by offering industry-standard best practices for fixtures, parametrization, mocking, and maintainable directory structures, ensuring robust and efficient code validation for modern software projects.

Use Cases

  • Setting up complex test environments and managing dependencies using reusable pytest fixtures to ensure strict test isolation.
  • Reducing code duplication by running a single test function against multiple data sets using @pytest.mark.parametrize.
  • Isolating units of code by mocking external API calls or database interactions using pytest-mock and mocker.patch.
  • Auditing existing test suites to align with industry-standard naming conventions and directory structures for better maintainability.
  • Implementing advanced testing patterns such as expected failures (xfail), floating-point comparisons, and asynchronous test handling.
namepytest-best-practices
descriptionExpert guidance for writing high-quality pytest tests. Use when writing tests, setting up fixtures, parametrizing, mocking, or reviewing test code.
Provide pytest best practices and patterns for writing maintainable, efficient tests.

Test Independence

  • Each test must run in isolation - no shared state between tests
  • Use fixtures for setup/teardown, never class-level mutable state
  • Tests should pass regardless of execution order

Naming Conventions

  • Files: test_*.py or *_test.py
  • Functions: test_<description>()
  • Classes: Test<ClassName>
  • Fixtures: descriptive lowercase_with_underscores

Directory Structure

tests/
├── conftest.py          # Shared fixtures
├── unit/
│   └── test_module.py
├── integration/
│   └── test_api.py
└── fixtures/            # Test data files

Core Testing Rules

  • Use plain assert statements (pytest provides detailed failure messages)
  • One logical assertion per test when practical
  • Test edge cases: empty inputs, boundaries, invalid data, errors
  • Keep tests focused and readable
Pattern Use Case
@pytest.fixture Setup/teardown, dependency injection
@pytest.mark.parametrize Run test with multiple inputs
@pytest.mark.skip Skip test temporarily
@pytest.mark.xfail Expected failure (known bug)
pytest.raises(Exception) Test exception raising
pytest.approx(value) Float comparison
mocker.patch() Mock dependencies
conftest.py Share fixtures across modules

Common Commands

pytest -v                    # Verbose
pytest -x                    # Stop on first failure
pytest --lf                  # Run last failed
pytest -k "pattern"          # Match test names
pytest -m "marker"           # Run marked tests
pytest --cov=src             # Coverage report

Based on what you're doing, read the relevant reference:

Task Reference
Setting up fixtures, scopes, factories references/fixtures.md
Parametrizing tests, multiple inputs references/parametrization.md
Mocking, patching, faking dependencies references/mocking.md
Markers, exceptions, assertions, async references/patterns.md
```bash pip install pytest pytest-asyncio pytest-mock pytest-cov pytest-xdist ```