Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 38 ยท Parametrization and Marks

Skip, skipif and xfail

Learn when and how to skip tests, run them conditionally with skipif, mark known bugs with xfail and strict mode, and use importorskip and pytest.skip inside tests.

Not every test should run in every situation. A test for a Windows-only feature is meaningless on Linux. A test for a library you may not have installed should not crash the suite. And when you discover a bug you cannot fix today, you want the test that documents it without turning the whole run red.

pytest has two ideas for this. Skipping means "this test does not apply here". Expected failure (xfail) means "this test is supposed to fail right now, and that is okay". Both appear in the report as separate outcomes, so nothing gets hidden.

skip: do not run this test

The skip mark always skips the test. Give a reason; it appears in the report and future readers will thank you.

Python pytest.mark.skip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first test is reported as SKIPPED, and -rs prints the reason in the summary. Skipped tests are never run, so the failing assert does not matter.

skipif: skip under a condition

skipif takes a condition (a boolean expression) and a reason. It is evaluated when the module is imported, so typical conditions are the Python version, the platform, or the presence of a library:

Python pytest.mark.skipif

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Define a condition once and reuse it, so reasons stay consistent:

Python
requires_posix = pytest.mark.skipif(sys.platform == "win32", reason="POSIX only")

@requires_posix
def test_symlinks(): ...

@requires_posix
def test_permissions(): ...

Skipping inside a test: pytest.skip

If you discover at run time that a test cannot proceed (a service is down, a data file is missing), call pytest.skip("reason"). It raises immediately, so nothing after it runs:

Python pytest.skip inside a test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Skipping inside a fixture skips every test that uses it, which is a neat way to guard a family of tests that need an external service.

importorskip: optional dependencies

pytest.importorskip("module") imports a module and skips the test (or the whole file, when called at module level) if it is missing:

Python pytest.importorskip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Used at the top of a file, it makes the entire module skipped when the dependency is absent. You can also demand a version: pytest.importorskip("numpy", minversion="2.0").

xfail: expected failure

Use xfail when you know a test fails and you want the suite to stay green while you track the problem: a known bug, an unfinished feature, a flaky external system. The outcomes are:

Outcome Meaning
XFAIL (lowercase x in the dot line: x) it failed, as expected
XPASS (X) it passed although expected to fail
Python pytest.mark.xfail

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first fails as predicted (XFAIL) and the run stays green. The second unexpectedly passes (XPASS). By default an XPASS is not a failure either, which can hide the fact that the bug was fixed.

strict xfail

To be told when an expected failure starts passing, make it strict. An XPASS then fails the run, forcing you to remove the mark:

Python
@pytest.mark.xfail(reason="bug #42", strict=True)

You can enable strict mode for every xfail with xfail_strict = true in your config file. Recommended: it keeps the list of known problems honest.

Python strict xfail

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output says [XPASS(strict)] and the run fails with exit code 1.

xfail options

  • raises=SomeError: expect failure only through that exception; any other exception is a real failure.
  • run=False: do not execute the test at all (useful if it crashes or hangs the interpreter).
  • A condition as first argument: @pytest.mark.xfail(sys.platform == "win32", reason="...").
  • Inside a test: pytest.xfail("reason") stops the test immediately as expected failure.
Python xfail with raises

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second test raises IndexError, not the declared ZeroDivisionError, so it is reported as a normal failure. That precision stops xfail from hiding unrelated bugs.

skip versus xfail: which one?

Situation Use
Test is not applicable (wrong OS, version, missing optional library) skip / skipif / importorskip
Test applies, code is currently wrong, a fix is planned xfail (strict)
Test is flaky and unreliable fix it, or quarantine with a marker and a ticket, not silent xfail
Test is obsolete delete it

Skipping and xfailing are debts. Review -rsx output regularly; a suite with hundreds of skips teaches the team to ignore the report.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which mark runs a test only on non-Windows systems?

    skipif evaluates a condition at import time and skips the test when it is true.
  2. 2. What does XPASS mean?

    XPASS is an unexpected pass: the test was expected to fail but succeeded.
  3. 3. What does strict=True change for xfail?

    Strict xfail turns an unexpected pass into a failure, forcing you to remove the stale mark.
  4. 4. A test needs the optional library yaml. Which call skips it when the library is missing?

    importorskip imports the module or skips the test or module when the import fails.

Summary

  • skip never runs a test; skipif(condition, reason=...) skips when a condition holds; pytest.skip() and importorskip() skip from inside code.
  • xfail records a known failure; set strict=True (or xfail_strict) so unexpected passes are noticed.
  • Use raises= to limit which exception counts as the expected one.
  • Always give a reason, and show them with -rs and -rx.
  • Skips and xfails are technical debt: review them and delete stale ones.

Next: Custom Marks and Strict Markers