Pytest Markers

pytest-markers

pytest markers — comprehensive testing patterns and workflows for Python projects.

Pytest Markers

Master pytest markers for reliable, maintainable Python test suites.

Overview

pytest markers provides a complete toolkit for writing, organizing, and running tests in Python applications. This skill covers setup, configuration, common patterns, and advanced techniques that experienced developers use in production codebases.

Whether you're building a new test suite from scratch or improving coverage on an existing project, this skill guides the agent through idiomatic testing patterns, assertion strategies, and test organization that scales with your codebase.

The skill emphasizes practical, real-world testing — not toy examples. It handles edge cases like async operations, external service dependencies, database interactions, and complex state management that you encounter in production applications.

When to Use

Activate this skill when the user needs to:

Write new unit tests for Python functions, classes, or modules

Refactor existing tests to be more maintainable and faster

Set up a testing framework from scratch in a new project

Debug flaky or failing tests in CI/CD pipelines

Improve code coverage in specific areas of the codebase

Create test utilities, helpers, or custom matchers

Core Capabilities

Test Structure & Organization

Generates well-organized test files following pytest conventions. Groups related tests using describe/context blocks, uses clear test names that document behavior, and maintains a logical file structure mirroring the source code.

Assertion Patterns

Uses the full range of pytest assertion APIs — equality checks, deep comparisons, error expectations, async assertions, and custom matchers. Chooses the most specific assertion for clear failure messages.

Mocking & Stubbing

Creates appropriate test doubles for external dependencies — mocks for behavior verification, stubs for state control, spies for call tracking. Properly cleans up mocks between tests to prevent cross-contamination.

Async Testing

Handles promises, async/await, callbacks, timers, and event-driven code with proper test patterns. Ensures tests don't pass falsely due to unhandled rejections or race conditions.

Example Prompts

Users might ask:

"Write unit tests for the UserService class covering all public methods"

"Add tests for the edge cases in the payment processing module"

"Set up pytest with proper configuration for our monorepo"

"Create a test helper for database fixture loading"

"Fix the flaky test in auth.test.py"

Configuration

ParameterDefaultDescription

testDir./testsDirectory containing test files

coveragetrueEnable code coverage collection

timeout10sMaximum time per test before failure

paralleltrueRun test files in parallel for speed

Best Practices

Follow AAA pattern — Structure every test as Arrange (setup), Act (execute), Assert (verify) for readability

One assertion per test concept — Each test should verify a single behavior — multiple assertions are fine if they test the same logical concept

Use descriptive test names — Test names should read as specifications: "should return 404 when user not found" not "test error case"

Avoid test interdependence — Each test must pass in isolation. Never rely on execution order or shared mutable state between tests

Keep tests fast — Unit tests should complete in milliseconds. Mock slow dependencies (network, filesystem, databases)

Test behavior, not implementation — Assert on outputs and side effects, not internal method calls. This makes tests resilient to refactoring

Common Pitfalls

⚠️ Testing implementation details instead of behavior — leads to brittle tests that break on every refactor

⚠️ Forgetting to clean up mocks/spies between tests — causes mysterious failures in unrelated tests

⚠️ Over-mocking — when everything is mocked, you're testing your mocks, not your code

⚠️ Ignoring flaky tests — they erode trust in the test suite and should be fixed immediately

⚠️ Writing tests after bugs instead of before — TDD catches bugs before they reach production

Output Format

Generates complete test files with proper imports, setup/teardown hooks, grouped test cases, and assertions. Includes comments explaining non-obvious test decisions.

Prerequisites

pytest installed and configured in the project

Source code to test is accessible and importable