Running Tests and Reading Output

Executing a Basic Test Suite

To begin running tests, you invoke the command in your terminal. When you simply execute the command without arguments, the engine recursively searches the current directory and subdirectories for files starting with 'test_' or ending with '_test.py'. Once these files are identified, the runner scans them for functions prefixed with 'test_' and executes them. This automatic discovery mechanism relies on standard naming conventions, which eliminates the need for manual configuration files. The engine acts as a discovery service that inspects the module namespace, imports your code, and runs the identified functions sequentially. By understanding that this is a dynamic process rather than a static one, you can reason that adding a new test file simply requires following the naming pattern for it to be integrated automatically into your existing test suite execution without any additional setup or registration steps required by the developer.

# Save as test_math.py
# Run with: pytest test_math.py

def test_addition():
    # The runner executes functions starting with 'test_'
    assert 1 + 1 == 2

def test_subtraction():
    # Each assert failure will stop execution of that specific function
    assert 5 - 2 == 3

Interpreting Test Results and Indicators

When your suite finishes execution, the output provides a visual summary composed of specific symbols. A dot represents a successful test, while an 'F' indicates a failure, an 'E' denotes an error during setup or teardown, and an 's' signifies a skipped test. These symbols represent the internal state of each test case after completion. A failure occurs when an assertion statement evaluates to False, whereas an error typically happens when an unexpected exception is raised outside of an assertion, often due to faulty test setup or environment issues. The runner uses these indicators to provide immediate high-level feedback on the health of your codebase. By observing this status line, you can quickly assess the scale of a regression. If you see many 'E' symbols, your infrastructure or fixtures likely have issues, while 'F' symbols point specifically to logic errors within your application code or test assertions.

# Save as test_status.py
# Run with: pytest -v test_status.py

def test_pass():
    assert True # Shows as '.'

def test_fail():
    assert 1 == 2 # Shows as 'F'

def test_error():
    raise ValueError('Setup issue') # Shows as 'E'

Analyzing Assertion Failures

When a test fails, the engine provides a detailed 'AssertionError' traceback. The real power of the output lies in the 'assert' introspection. Instead of just showing that an assertion failed, the output decomposes the expression to show the specific values that caused the discrepancy. For instance, if you compare two lists or dictionaries, the runner highlights exactly which elements differ, making it much easier to debug complex data structures. This works by inspecting the abstract syntax tree of your assertion expression during runtime, capturing the values of the components before the final comparison fails. Because the engine interprets the assertion directly, you do not need to manually write detailed error messages for every check. Relying on this native introspection allows you to write concise, readable test code while still receiving highly descriptive failure reports that pinpoint the exact source of logic bugs.

# Save as test_analysis.py
# Run with: pytest test_analysis.py

def test_list_comparison():
    expected = [1, 2, 3]
    actual = [1, 2, 4]
    # The engine will show the diff between 3 and 4
    assert actual == expected

Targeting Specific Tests and Modules

Often, you will not want to run the entire suite, especially as your project grows. You can target specific files, directories, or even individual test functions by providing their names as arguments to the runner. By passing a path to a specific file, you isolate the scope, ensuring that only tests relevant to your current task are executed. Furthermore, you can use the '-k' flag to run tests that match a specific substring, which is invaluable when you have multiple tests related to a single feature but spread across various files. This filtering mechanism works by applying a regex-like match against the collection of identified test names. Understanding this allows you to reason about how to build custom workflows, such as running only the 'login' tests before pushing your code to production. It optimizes your feedback loop, allowing you to focus on specific logic without waiting for the entire project's validation process to conclude.

# Run only the login file:
# pytest test_auth.py

# Run only tests containing 'signup':
# pytest -k "signup"

def test_user_signup():
    assert True

def test_admin_login():
    assert True

Controlling Verbosity and Output

The default output provides a minimal summary, but sometimes you need more detail to understand exactly what is happening during a test run. The '-v' (verbose) flag increases the detail level, listing every individual test function that was executed alongside its status. Adding '-s' is another common requirement; it allows you to see the output from 'print' statements during test execution, which are captured and suppressed by default to keep the console clean. These flags are not just for display; they change how the runner manages standard streams and reports progress. By combining these flags, you can tailor the level of diagnostic information to match your debugging needs. Learning to control the output format ensures that you remain productive whether you need a quick 'pass/fail' summary or a deep dive into the internal state of a failing integration test that requires logging output for visibility.

# Run with verbose output and visible print statements:
# pytest -v -s test_verbose.py

def test_data_logging():
    data = {'key': 'value'}
    print(f"Debugging: {data}") # Visible only with -s
    assert data['key'] == 'value'

Interview questions

All pytest & Testing interview questions →

Check yourself

Take the full pytest & Testing quiz →