0
# Testing Functions
1

2
Core functions for controlling test execution flow and outcomes. These functions provide the fundamental building blocks for managing test behavior, conditional execution, and early termination scenarios.
3

4
## Capabilities
5

6
### Test Skipping
7

8
Skip test execution with optional reason and support for module-level skipping.
9

10
```python { .api }
11
def skip(reason: str = "", *, allow_module_level: bool = False):
12
    """
13
    Imperatively skip a test with optional reason.
14
    
15
    Parameters:
16
    - reason: Explanation for why the test is skipped
17
    - allow_module_level: Whether to allow skipping at module level (outside test functions)
18
    
19
    Raises:
20
    pytest.skip.Exception (Skipped)
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
import pytest
28

29
def test_conditional_skip():
30
    if not has_network():
31
        pytest.skip("Network not available")
32
    # test code here
33

34
# Module-level skip
35
if not sys.platform.startswith("linux"):
36
    pytest.skip("Linux-only tests", allow_module_level=True)
37
```
38

39
### Expected Failures
40

41
Mark tests as expected to fail with optional reason.
42

43
```python { .api }
44
def xfail(reason: str = ""):
45
    """
46
    Mark test as expected to fail.
47
    
48
    Parameters:
49
    - reason: Explanation for why the test is expected to fail
50
    
51
    Raises:
52
    pytest.xfail.Exception (XFailed)
53
    """
54
```
55

56
**Usage Example:**
57

58
```python
59
import pytest
60

61
def test_known_bug():
62
    if bug_exists():
63
        pytest.xfail("Bug #123 not fixed yet")
64
    assert complex_calculation() == expected_result
65
```
66

67
### Test Failures
68

69
Explicitly fail tests with custom messages and traceback control.
70

71
```python { .api }
72
def fail(reason: str = "", pytrace: bool = True):
73
    """
74
    Explicitly fail a test with message and traceback control.
75
    
76
    Parameters:
77
    - reason: Failure message to display
78
    - pytrace: Whether to show pytest traceback (True) or just the message (False)
79
    
80
    Raises:
81
    pytest.fail.Exception (Failed)
82
    """
83
```
84

85
**Usage Example:**
86

87
```python
88
import pytest
89

90
def test_validation():
91
    result = validate_data(data)
92
    if not result.is_valid:
93
        pytest.fail(f"Validation failed: {result.errors}")
94
```
95

96
### Test Suite Exit
97

98
Exit the entire test suite immediately with reason and exit code.
99

100
```python { .api }
101
def exit(reason: str = "", returncode: int | None = None):
102
    """
103
    Exit testing process immediately.
104
    
105
    Parameters:
106
    - reason: Explanation for early exit
107
    - returncode: Exit code to use (defaults to appropriate pytest exit code)
108
    
109
    Raises:
110
    pytest.exit.Exception (Exit)
111
    """
112
```
113

114
**Usage Example:**
115

116
```python
117
import pytest
118

119
def test_critical_setup():
120
    if not critical_system_available():
121
        pytest.exit("Critical system unavailable, cannot continue testing")
122
```
123

124
### Conditional Imports
125

126
Import modules or skip tests if import fails, with version checking support.
127

128
```python { .api }
129
def importorskip(
130
    modname: str, 
131
    minversion: str | None = None, 
132
    reason: str | None = None, 
133
    *, 
134
    exc_type: type[ImportError] | None = None
135
):
136
    """
137
    Import module or skip test if import fails.
138
    
139
    Parameters:
140
    - modname: Name of module to import
141
    - minversion: Minimum required version (if module has __version__)
142
    - reason: Custom skip reason if import/version check fails
143
    - exc_type: Specific exception type to catch (defaults to ImportError)
144
    
145
    Returns:
146
    The imported module
147
    
148
    Raises:
149
    pytest.skip.Exception if import fails or version insufficient
150
    """
151
```
152

153
**Usage Example:**
154

155
```python
156
import pytest
157

158
# Skip test if numpy not available
159
numpy = pytest.importorskip("numpy")
160

161
# Skip if version too old
162
requests = pytest.importorskip("requests", minversion="2.20.0")
163

164
def test_with_numpy():
165
    array = numpy.array([1, 2, 3])
166
    assert len(array) == 3
167

168
def test_with_requests():
169
    response = requests.get("https://httpbin.org/get")
170
    assert response.status_code == 200
171
```
172

173
## Exception Types
174

175
```python { .api }
176
# These are the exceptions raised by the testing functions
177
class skip.Exception(Exception):
178
    """Raised by pytest.skip()"""
179

180
class xfail.Exception(Exception):
181
    """Raised by pytest.xfail()"""
182
    
183
class fail.Exception(Exception):
184
    """Raised by pytest.fail()"""
185
    
186
class exit.Exception(Exception):
187
    """Raised by pytest.exit()"""
188
```