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
  • 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 expected exceptions
  • Assertions about expected warnings
  • Making use of context-sensitive comparisons
  • Defining your own explanation for failed assertions
  • 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
  • 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
• 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
• 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 primary 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
  • 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
  • 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