Recommended Free Tools
Use @pytest.mark.skip(reason="...") to always skip a test, @pytest.mark.skipif(condition, reason="...") to skip it when a condition is true, and pytest.skip("...") when the reason is discovered while the test runs. For a missing optional dependency, use pytest.importorskip().
Choose the right way to skip a test
| Need | Use | When it applies |
|---|---|---|
| Always skip a test | @pytest.mark.skip(reason="...") |
The test is collected but not executed. |
| Skip when a known condition is true | @pytest.mark.skipif(condition, reason="...") |
Use for conditions such as platform or version that can be checked during collection. |
| Decide during setup or test execution | pytest.skip("...") |
Use when the condition is only known at runtime. |
| Skip if an optional module is unavailable | pytest.importorskip("module_name") |
Use where a test requires an optional import. |
| Keep a test that is expected to fail | @pytest.mark.xfail |
The test runs by default and is reported as XFAIL or XPASS. |
| Prevent files or directories from being collected | Collection configuration or hooks | Skipping applies to collected test items; it is not the mechanism for excluding paths. |
How do I skip a test in pytest every time?
Mark the test with pytest.mark.skip and give a concise reason. The reason appears in skip reporting and helps explain why the test is disabled.
import pytest
@pytest.mark.skip(reason="waiting for the service endpoint")
def test_service_endpoint():
...How do I skip a test if a condition is true?
Use pytest.mark.skipif when the condition can be determined during collection. In this example, the test is only applicable on Windows:
import sys
import pytest
@pytest.mark.skipif(sys.platform != "win32", reason="requires Windows")
def test_windows_feature():
...You can apply the marker to an individual test, a test class, or an entire module. To apply it to every test in a module, assign it to pytestmark:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
import sys
import pytest
pytestmark = pytest.mark.skipif(
sys.platform != "win32",
reason="tests in this module require Windows",
)If multiple applicable skipif conditions are present, pytest skips the test if any condition is true. Prefer a boolean condition; condition strings are retained mainly for backward compatibility.
How do I skip a test when the condition is only known at runtime?
Call pytest.skip() from the test or setup code after checking the condition. This is useful when configuration or resource availability cannot be evaluated during collection:
import pytest
def test_feature():
if not valid_config():
pytest.skip("configuration is unavailable")To skip an entire module while it is being imported, pass allow_module_level=True:
import pytest
if not environment_is_ready():
pytest.skip("environment is unavailable", allow_module_level=True)How do I skip tests when an optional dependency is missing?
Use pytest.importorskip(). It imports the named module and returns it if available; if the import fails, pytest skips the test or module. You can use it at module level, inside a test, or in setup.
import pytest
optional_lib = pytest.importorskip("optional_lib")
def test_optional_integration():
assert optional_lib is not NoneTo require a minimum dependency version, provide minversion=. The current API documentation specifies ModuleNotFoundError as the default exception type. To skip for other ImportError exceptions too, pass exc_type=ImportError. This behavior has changed across pytest versions, so check the API documentation matching the pytest version installed in your project before relying on exc_type.
What is the difference between skip and xfail?
A skip means the test should not run under the current conditions—for example, because its platform is unsupported or a required external resource is unavailable. An xfail means the test is still worth running even though failure is expected, such as while a known bug remains unresolved.
@pytest.mark.xfailruns the test by default and reports XFAIL if it fails as expected, or XPASS if it unexpectedly passes.@pytest.mark.xfail(run=False)records the expected-failure status without executing the test.strict=Truemakes an XPASS fail the suite; thexfail_strictconfiguration can make that behavior the default.
Use skip when execution is inapplicable; use xfail when running the assertion still provides useful information.
How do I see why pytest skipped a test?
Run pytest with -rs to include skip reasons in the short test summary:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
pytest -rsTo include details for xfailed and xpassed tests as well as skipped tests, use:
pytest -rxXsThe -r option controls which outcomes appear in the short test summary report.
How do I exclude a test file or directory entirely?
A skip marker acts on collected test items; it does not prevent pytest from collecting a file or directory. If you need to exclude paths, use pytest’s test-collection configuration or hooks. The exact configuration depends on how your project collects tests.
Or skip the browser setup:
pytest is for Python tests; if your work also needs website screenshots, ScreenshotNeo provides a one-request screenshot API. Its consent-banner, newsletter-popup, and chat-widget removal steps can be turned off, and bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. It also has an MCP server for AI agents, including Claude, Cursor, and other MCP clients.
Install requests, set your API key, and run this Python example. See the ScreenshotNeo API documentation for request options.
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 screenshots. Sign up for the free plan.
Quick Recap
Troubleshooting common skip issues
- The test still runs despite a skip condition: Check whether the condition is actually true for the current environment and whether the marker is attached to the test, class, or module you intend to affect.
- The test is skipped before your runtime check: Use
pytest.skip()for conditions discovered during setup or execution rather than a collection-time marker. - An optional import raises instead of skipping: Check the installed pytest version and the exception type. The current API defaults to catching
ModuleNotFoundError; useexc_type=ImportErrorto include other import errors where supported. - The file still appears in collection: A skip marker does not exclude a file or directory. Configure collection or use a collection hook.
- You cannot find a skip reason in output: Run
pytest -rsto show skipped-test details in the summary.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
