Full pytest documentation - pytest documentation

Full pytest documentation - pytest documentation
Skip to content
Get Started
How-to guides
Reference guides
Explanation
Examples and customization tricks
About the project
Changelog
Contributing
Backwards Compatibility Policy
History
Python version support
Sponsor
pytest for enterprise
License
Contact channels
Useful links
pytest @ PyPI
pytest @ GitHub
Issue Tracker
PDF Documentation
Full pytest documentation
Download latest version as PDF
Start here
Get Started
Install
pytest
Create your first test
Run multiple tests
Assert that a certain exception is raised
Group multiple tests in a class
Compare floating-point values with pytest.approx
Request a unique temporary directory for functional tests
Continue reading
How-to guides
How to invoke pytest
Specifying which tests to run
Getting help on version, option names, environment variables
Profiling test execution duration
Managing loading of plugins
Other ways of calling pytest
How to write and report assertions in tests
Asserting with the
assert
statement
Assertions about approximate equality
Assertions about expected exceptions
Assertions about expected warnings
Making use of context-sensitive comparisons
Defining your own explanation for failed assertions
Returning non-None value in test functions
Assertion introspection details
How to use fixtures
“Requesting” fixtures
Autouse fixtures (fixtures you don’t have to request)
Scope: sharing fixtures across classes, modules, packages or session
Teardown/Cleanup (AKA Fixture finalization)
Safe teardowns
Running multiple
assert
statements safely
Fixtures can introspect the requesting test context
Using markers to pass data to fixtures
Factories as fixtures
Parametrizing fixtures
Using marks with parametrized fixtures
Modularity: using fixtures from a fixture function
Automatic grouping of tests by fixture instances
Use fixtures in classes and modules with
usefixtures
Overriding fixtures on various levels
Using fixtures from other projects
How to mark test functions with attributes
Registering marks
Raising errors on unknown marks
How to parametrize fixtures and test functions
@pytest.mark.parametrize
: parametrizing test functions
Basic
pytest_generate_tests
example
More examples
How to use temporary directories and files in tests
The
tmp_path
fixture
The
tmp_path_factory
fixture
The
tmpdir
and
tmpdir_factory
fixtures
Temporary directory location and retention
How to monkeypatch/mock modules and environments
Monkeypatching functions
Monkeypatching returned objects: building mock classes
Global patch example: preventing “requests” from remote operations
Monkeypatching environment variables
Monkeypatching dictionaries
API Reference
How to run doctests
Encoding
Using ‘doctest’ options
Continue on failure
Output format
pytest-specific features
Alternatives
How to re-run failed tests and maintain state between test runs
Usage
Rerunning only failures or failures first
Behavior when no tests failed in the last run
The new config.cache object
Inspecting Cache content
Clearing Cache content
Stepwise
How to manage logging
caplog fixture
Live Logs
Customizing Colors
Release notes
Incompatible changes in pytest 3.4
How to capture stdout/stderr output
Default stdout/stderr/stdin capturing behaviour
Setting capturing methods or disabling capturing
Using print statements for debugging
Accessing captured output from a test function
How to capture warnings
Controlling warnings
@pytest.mark.filterwarnings
Setting a maximum number of warnings
Disabling warnings summary
Disabling warning capture entirely
DeprecationWarning and PendingDeprecationWarning
Ensuring code triggers a deprecation warning
Asserting warnings with the warns function
Recording warnings
Additional use cases of warnings in tests
Custom failure messages
Internal pytest warnings
Resource Warnings
How to use skip and xfail to deal with tests that cannot succeed
Skipping test functions
XFail: mark test functions as expected to fail
Skip/xfail with parametrize
How to install and use plugins
Requiring/Loading plugins in a test module or conftest file
Finding out which plugins are active
Deactivating / unregistering a plugin by name
Disabling plugins from autoloading
Writing plugins
Plugin discovery order at tool startup
conftest.py: local per-directory plugins
Writing your own plugin
Making your plugin installable by others
Assertion Rewriting
Requiring/Loading plugins in a test module or conftest file
Accessing another plugin by name
Registering custom markers
Testing plugins
Writing hook functions
hook function validation and execution
firstresult: stop at first non-None result
hook wrappers: executing around other hooks
Hook function ordering / call example
Declaring new hooks
Using hooks in pytest_addoption
Optionally using hooks from 3rd party plugins
Storing data on items across hook functions
How to use pytest with an existing test suite
Running an existing test suite with pytest
How to use
unittest
-based tests with pytest
Benefits out of the box
pytest features in
unittest.TestCase
subclasses
Mixing pytest fixtures into
unittest.TestCase
subclasses using marks
Using autouse fixtures and accessing other fixtures
How to implement xunit-style set-up
Module level setup/teardown
Class level setup/teardown
Method and function level setup/teardown
How to set up bash completion
Reference guides
Fixtures reference
Built-in fixtures
Fixture availability
Fixture instantiation order
Pytest Plugin List
Configuration
Command line options and configuration file settings
Configuration file formats
Initialization: determining rootdir and configfile
Builtin configuration file options
Syntax highlighting theme customization
API Reference
Constants
Functions
Marks
Fixtures
Hooks
Collection tree objects
Objects
Global Variables
Environment Variables
Exceptions
Warnings
Configuration Options
Command-line Flags
Explanation
Anatomy of a test
About fixtures
What fixtures are
Improvements over xUnit-style setup/teardown functions
Fixture errors
Sharing test data
A note about fixture cleanup
Good Integration Practices
Install package with pip
Conventions for Python test discovery
Choosing a test layout
tox
Do not run via setuptools
Checking with flake8-pytest-style
Using pytest’s strict mode
Flaky tests
Why flaky tests are a problem
Potential root causes
Related features
Other general strategies
Research
Resources
pytest import mechanisms and
sys.path
PYTHONPATH
Import modes
prepend
and
append
import modes scenarios
Invoking
pytest
versus
python
-m
pytest
Further topics
Examples and customization tricks
Demo of Python failure reports with pytest
Basic patterns and examples
Parametrizing tests
Working with custom markers
A session-fixture which can look at all collected tests
Changing standard (Python) test discovery
Working with non-python tests
Using a custom directory collector
Backwards Compatibility Policy
History
Focus primarily on smooth transition - stance (pre 6.0)
Python version support
Deprecations and Removals
Deprecated Features
Removed Features and Breaking Changes
Contributing
Feature requests and feedback
Report bugs
Fix bugs
Implement features
Write documentation
Submitting Plugins to pytest-dev
AI/LLM-Assisted Contributions Policy
Preparing Pull Requests
Joining the Development Team
Merge/squash guidelines
Backporting bug fixes for the next patch release
Handling stale issues/PRs
Closing issues
Development Guide
Sponsor
OpenCollective
pytest for enterprise
License
Contact channels
Web
Chat
Microblogging
Mail
Other
History
Historical Notes
Marker revamp and iteration
cache plugin integrated into the core
funcargs and
pytest_funcarg__
@pytest.yield_fixture
decorator
[pytest]
header in
setup.cfg
Applying marks to
@pytest.mark.parametrize
parameters
@pytest.mark.parametrize
argument names as a tuple
setup: is now an “autouse fixture”
Conditions as strings instead of booleans
pytest.set_trace()
“compat” properties
Talks and Tutorials
Books
Talks and blog postings
Release announcements
On this page
Full pytest documentation
Start here
How-to guides
Reference guides
Explanation
Further topics