Define a test case marked as expected to fail, providing specific input parameters and an identifier for test reporting.

Indicate to developers and test runners that this test case is anticipated to fail, often used to document known invalid input handling or track outstanding bugs.

When writing tests for validation or error‑handling logic, to record known failing cases, or to track bugs that are expected to fail until fixed.

Inside pytest test functions marked with @pytest.mark.parametrize, within test modules that validate error conditions or invalid inputs.

pytest.param(<arg1>, <arg2>, id='<identifier>', marks=pytest.mark.xfail)

pytest.param(arg1, arg2, id='identifier', marks=pytest.mark.xfail)

arg1: any test input, arg2: any test input or None, id: string, marks: pytest mark (e.g., xfail)

• pytest.mark
• param
• xfail
• id
• parametrize
• test
• fixture

• arg1 and arg2 can be any test data (e.g.
• invalid input
• None
• empty string)
• id can be any descriptive string
• marks can be pytest.mark.skip or other marks.

Forgetting to import pytest → NameError when pytest is not defined; Using wrong mark (e.g., skip instead of xfail) → test is skipped instead of expected failure; Omitting the id → test reports lack identifier, making reports harder to read; Providing incorrect number of arguments to test function → TypeError due to argument mismatch; Applying xfail when test actually passes → test reported as XPASS (unexpected pass) indicating a false expectation.

regular pytest.param without xfail: expected to pass; pytest.param marked with skip: test is omitted; @pytest.mark.xfail on test function: applies xfail to all cases in that test.

Coming from Python's unittest: may expect skip instead of xfail → use pytest.mark.xfail for expected failures; Coming from JUnit: may use @Ignore instead of @Test(expected=…) → use pytest.mark.xfail.

• pytest-param-xfail

Do not use xfail for tests that are expected to pass, as it masks real failures; No measurable performance impact, but overuse can obscure test suite clarity; Boundary: xfail only marks the test as expected to fail; if the test passes unexpectedly, it is reported as XPASS, indicating a false expectation.

Communicates to readers and test runners that this test case documents a known invalid input scenario, encouraging proper error handling and future fix tracking.

Using pytest.param with xfail is like placing a 'wet floor' sign: it warns everyone that the area is known to be slippery, so they proceed cautiously without being surprised by a fall.

This example shows an invalid input 'invalid' paired with None, marked as expected to fail and labeled 'invalid_input'.

Progress to using multiple xfail cases within a single parametrize, or apply @pytest.mark.xfail at the test function level for broader expectations.