Introduction

What is PyTest

pytest is a popular testing framework for Python that makes it easy to write simple as well as scalable test cases. It can be used to write various types of software tests including unit tests, integration tests, end-to-end tests, and functional tests.

Running Tests with Pytest

You can run your tests by simply running the following command in your project directory:

pytest

# To get more detailed responses, use verbose option
pytest -v

By default, pytest will automatically:

• Discover test files.
• Run all test functions.
• Report results neatly in the terminal.

NOTE

The part of pytest execution where pytest finds which tests to run is called test discovery.

Writing Your First Test

# content of test_sample.py
def func(x):
    return x + 1

# This test will fail
def test_answer():
    assert func(3) == 5

Naming Conventions (for Test Discovery)

Entity	Convention	Example
Test file	test_*.py or *_test.py	test_math_utils.py
Test method or function	Must start with test_	def test_addition():
Test class	Must start with Test (Classes can't have __init__ method)	class TestDBConnector():

TIP

Add an empty __init__.py in all test folders to prevent module name collisions. This makes each directory a package, giving tests unique import paths.

Possible Outcomes (for Test Results)

When you run tests, these are the possible outcomes:

Symbol	Verbose Name	Description
.	PASSED	The test ran successfully without any issues.
F	FAILED	The test failed (assertion failure or unexpected exception).
E	ERROR	An error occurred while running the test (not an assertion failure).
s	SKIPPED	The test was skipped, usually via @pytest.mark.skip or @pytest.mark.skipif decorator.
x	XFAIL (Expected Failure)	The test was expected to fail and did fail.
X	XPASS (Unexpected Success)	The test was expected to fail but passed instead. With xfail(strict=True), this is treated as a failure, but the symbol remains X.

Assertions in PyTest

In pytest, you can use assert <expression> with any Python expression. If the expression evaluates to False, the test fails.

assert something
assert a == b
assert a <= b

NOTE

In pytest output, > marks the line where the assertion failed, while E labels the error explanation lines.

Command-Line Options

pytest comes with a rich set of command-line options to customize test runs. The most commonly used ones are:

Option	Description
--collect-only	Only collect tests, don't execute them.
-v, --verbose	Enables verbose mode, showing each test name and detailed output.
-q, --quiet	Runs tests in quiet mode with minimal output (decrease verbosity).
-x	Stops execution after the first failure.
--maxfail=N	Stops after N test failures.
--lf, --last-failed	Runs only tests that failed in the previous run (or all if none failed).
-ff, --failed-first	Runs previously failed tests first, then the rest.
-k EXPRESSION	Runs tests matching a given expression.
-m MARKEXPR	Runs tests matching a specific marker expression.
--tb=STYLE	Controls traceback style (auto, short, line, no, etc.).
-l, --showlocals	Show local variables in tracebacks (disabled by default).
-s	Shows print and log output in real time (disables output capture).
--durations=N	Displays the N slowest tests after execution (N=0 for all).
--setup-show	Display the setup and teardown of each fixture and test (useful for debugging fixtures).