Python Pytest: Run Specific Tests and Filters

python pytest run specific tests and filters requires a clear understanding of the core syntax, runtime behavior, and practical implementation patterns demonstrated in the examples below.

When you need to run specific tests and filters with python pytest, the command line gives you several selection mechanisms that go beyond running the whole suite. The most direct way is to pass a file path or a node ID. A node ID is the full path to a test, including the module, class, and function name, separated by ::. For example:

pytest tests/test_user.py
pytest tests/test_user.py::test_login
pytest tests/test_user.py::TestUser::test_profile

The first command runs every test in that file. The second runs a single test function. The third runs a single test method inside a class. Node IDs are useful when you know exactly which test failed and want to reproduce the failure quickly.

Filtering with -k by Test Name or Substring

The -k option selects tests based on a substring or a Python expression that matches against the test name, class name, and module name. This is helpful when you want to run all tests that relate to a feature without listing each file individually.

pytest -k "login"
pytest -k "login or signup"
pytest -k "not slow"

The expression supports and, or, and not, and it is case-sensitive. The substring match is not a regular expression; it is a plain substring check. So -k "login" matches test_login, TestLogin, and test_user_login. This can cause surprises if you have similarly named tests, so check the selection with --collect-only before running:

pytest -k "login" --collect-only

Using Markers with -m to Select by Category

Markers are a way to tag tests with metadata. You can define custom markers in pytest.ini or pyproject.toml, then use -m to select tests that carry a specific marker. This is the cleanest approach for grouping tests by category, such as slow, integration, or smoke.

# pytest.ini
[pytest]
markers =
    slow: marks tests as slow
    integration: requires external services

pytest -m "slow"
pytest -m "not integration"
pytest -m "smoke and not slow"

Markers are evaluated as expressions similar to -k, and you can combine them with and, or, and not. Unlike -k, -m matches against the marker names, not the test names. Markers must be registered to avoid warnings, and they can be applied to classes or modules as well as individual functions.

Combining Filters and Excluding Tests

The real power of pytest selection comes from combining -k and -m, and from using --ignore and --deselect to remove tests from the run. For example, you can run all login tests except those marked as slow:

pytest -k "login" -m "not slow"

If you need to skip an entire file or a specific test, use --ignore for directories or files and --deselect for individual node IDs:

pytest --ignore=tests/test_legacy.py
pytest --deselect tests/test_user.py::test_deprecated

These options are particularly useful in CI when you want to run a subset of tests for a pull request without editing the test files.

Common Pitfalls When Filtering Tests

Several mistakes are easy to make when filtering tests. The -k expression matches against the full node ID, including the module and class names, so a substring like "user" will match many tests. Quoting the expression is essential when it contains spaces or operators, otherwise the shell will split it. Also, -k is case-sensitive, so -k "Login" will not match test_login. When you use -m, remember that markers must be registered, otherwise pytest will emit a warning and the marker will not be recognized. Finally, combining -k and -m with and/or can lead to confusing precedence; wrap expressions in parentheses when necessary, as in -k "(login or signup) and not slow".

Keeping Test Selection Maintainable in Large Suites

As the suite grows, relying on complex -k expressions becomes fragile. Prefer markers for stable categories and use naming conventions for features. For example, prefix integration tests with test_integration_ or apply the integration marker. Document the standard selection commands in your CI configuration or a Makefile so that everyone uses the same filters. When you need to run a specific test, use the node ID directly rather than a broad substring. This reduces the chance of accidentally running unrelated tests and keeps the feedback loop short. If you notice that a filter expression is repeated often, consider creating a custom pytest option or a script that wraps the selection logic, but first make sure the built-in features are sufficient.