0
# Test Discovery and Execution
1
2
Core functionality for discovering, loading, and running tests with extensive customization options through command-line arguments, configuration files, and plugin integration.
3
4
## Capabilities
5
6
### Main Entry Points
7
8
Primary functions for running tests and test discovery.
9
10
```python { .api }
11
def main(*args, **kwargs):
12
"""
13
Main entry point for running tests.
14
15
Parameters:
16
- module: Module in which to run tests (default: __main__)
17
- defaultTest: Default test name (default: None)
18
- argv: Command line args (default: sys.argv)
19
- exit: Exit after running tests (default: True)
20
- verbosity: Base verbosity level
21
- plugins: List of additional plugin modules to load
22
- excludePlugins: List of plugin modules to exclude
23
- extraHooks: List of (hook name, plugin instance) tuples
24
25
Returns:
26
PluggableTestProgram instance
27
"""
28
29
def discover(*args, **kwargs):
30
"""
31
Main entry point for test discovery.
32
33
Runs PluggableTestProgram with module=None to force test discovery.
34
All arguments are passed through except module.
35
36
Returns:
37
PluggableTestProgram instance
38
"""
39
```
40
41
### Test Program Class
42
43
Main test program that coordinates the entire test execution process.
44
45
```python { .api }
46
class PluggableTestProgram:
47
"""
48
TestProgram that enables plugins.
49
50
Accepts the same parameters as unittest.TestProgram but most are ignored
51
as their functions are handled by plugins.
52
"""
53
54
sessionClass = Session
55
loaderClass = PluggableTestLoader
56
runnerClass = PluggableTestRunner
57
defaultPlugins: tuple
58
excludePlugins: tuple
59
60
def __init__(self, **kwargs):
61
"""
62
Initialize test program.
63
64
Parameters:
65
- module: Module in which to run tests
66
- defaultTest: Default test name
67
- argv: Command line args
68
- exit: Exit after running tests
69
- verbosity: Base verbosity
70
- plugins: Additional plugin modules
71
- excludePlugins: Plugin modules to exclude
72
- extraHooks: (hook name, plugin instance) pairs
73
"""
74
75
def parseArgs(self, argv):
76
"""
77
Parse command line args and create configuration session.
78
79
Parameters:
80
- argv: Command line arguments
81
"""
82
83
def loadPlugins(self):
84
"""
85
Load available plugins.
86
87
Uses defaultPlugins and excludePlugins to alter plugin list.
88
Also registers extraHooks plugin pairs.
89
"""
90
91
def createTests(self):
92
"""Create top-level test suite."""
93
94
def runTests(self):
95
"""Run tests using configured runner."""
96
97
@classmethod
98
def getCurrentSession(cls):
99
"""
100
Get the current session.
101
102
Returns:
103
Current Session instance or None if no session running
104
"""
105
```
106
107
### Test Loader
108
109
Pluggable test loader that defers all loading operations to plugins.
110
111
```python { .api }
112
class PluggableTestLoader:
113
"""
114
Test loader that defers all loading to plugins.
115
116
Parameters:
117
- session: Test run session
118
"""
119
120
suiteClass = unittest.TestSuite
121
122
def __init__(self, session):
123
"""Initialize with test session."""
124
125
def loadTestsFromModule(self, module):
126
"""
127
Load tests from module.
128
129
Fires loadTestsFromModule hook.
130
131
Parameters:
132
- module: Python module to load tests from
133
134
Returns:
135
TestSuite containing loaded tests
136
"""
137
138
def loadTestsFromNames(self, testNames, module=None):
139
"""
140
Load tests from test names.
141
142
Fires loadTestsFromNames hook.
143
144
Parameters:
145
- testNames: List of test names to load
146
- module: Optional module context
147
148
Returns:
149
TestSuite containing loaded tests
150
"""
151
152
def loadTestsFromName(self, name, module=None):
153
"""
154
Load tests from test name.
155
156
Fires loadTestsFromName hook.
157
158
Parameters:
159
- name: Test name to load
160
- module: Optional module context
161
162
Returns:
163
TestSuite containing loaded tests
164
"""
165
166
def discover(self, start_dir=None, pattern=None):
167
"""
168
Compatibility shim for load_tests protocol.
169
170
Parameters:
171
- start_dir: Directory to start discovery
172
- pattern: Pattern to match test files
173
174
Returns:
175
TestSuite containing discovered tests
176
"""
177
178
def failedImport(self, name):
179
"""
180
Make test case representing a failed import.
181
182
Parameters:
183
- name: Name of module that failed to import
184
185
Returns:
186
TestCase representing the import failure
187
"""
188
189
def failedLoadTests(self, name, exception):
190
"""
191
Make test case representing a failed test load.
192
193
Parameters:
194
- name: Name of test that failed to load
195
- exception: Exception that occurred during loading
196
197
Returns:
198
TestCase representing the load failure
199
"""
200
```
201
202
### Test Result
203
204
Pluggable test result that defers all outcome recording to plugins.
205
206
```python { .api }
207
class PluggableTestResult:
208
"""
209
Test result that defers to plugins.
210
211
All test outcome recording and reporting is deferred to plugins,
212
which implement startTest, stopTest, testOutcome, and wasSuccessful.
213
214
Parameters:
215
- session: Test run session
216
"""
217
218
shouldStop: bool # When True, test run should stop
219
failfast: bool # TestCase.subTest expects this attribute
220
221
def __init__(self, session):
222
"""Initialize with test session."""
223
224
def startTest(self, test):
225
"""
226
Start a test case.
227
228
Fires startTest hook.
229
230
Parameters:
231
- test: Test case being started
232
"""
233
234
def stopTest(self, test):
235
"""
236
Stop a test case.
237
238
Fires stopTest hook.
239
240
Parameters:
241
- test: Test case being stopped
242
"""
243
244
def addError(self, test, err):
245
"""
246
Test case resulted in error.
247
248
Fires setTestOutcome and testOutcome hooks.
249
250
Parameters:
251
- test: Test case
252
- err: Error tuple (type, value, traceback)
253
"""
254
255
def addFailure(self, test, err):
256
"""
257
Test case resulted in failure.
258
259
Fires setTestOutcome and testOutcome hooks.
260
261
Parameters:
262
- test: Test case
263
- err: Failure tuple (type, value, traceback)
264
"""
265
266
def addSuccess(self, test):
267
"""
268
Test case resulted in success.
269
270
Fires setTestOutcome and testOutcome hooks.
271
272
Parameters:
273
- test: Test case
274
"""
275
276
def addSkip(self, test, reason):
277
"""
278
Test case was skipped.
279
280
Fires setTestOutcome and testOutcome hooks.
281
282
Parameters:
283
- test: Test case
284
- reason: Skip reason string
285
"""
286
287
def addSubTest(self, test, subtest, err):
288
"""
289
Called at the end of a subtest.
290
291
Fires setTestOutcome and testOutcome hooks.
292
293
Parameters:
294
- test: Parent test case
295
- subtest: Subtest case
296
- err: Error tuple or None for success
297
"""
298
```
299
300
## Usage Examples
301
302
### Basic Test Discovery
303
304
```python
305
import nose2
306
307
# Discover and run all tests in current directory
308
nose2.discover()
309
310
# Discover tests with custom start directory
311
nose2.discover(argv=['nose2', '--start-dir', 'tests'])
312
```
313
314
### Custom Test Program
315
316
```python
317
from nose2.main import PluggableTestProgram
318
319
# Create custom test program
320
program = PluggableTestProgram(
321
module=None, # Force discovery
322
argv=['test', '--verbose', '--start-dir', 'tests'],
323
exit=False, # Don't exit after running
324
plugins=['nose2.plugins.coverage', 'nose2.plugins.junitxml']
325
)
326
```
327
328
### Programmatic Test Loading
329
330
```python
331
from nose2.session import Session
332
from nose2.loader import PluggableTestLoader
333
334
# Create session and loader
335
session = Session()
336
loader = PluggableTestLoader(session)
337
338
# Load tests from specific module
339
import my_test_module
340
suite = loader.loadTestsFromModule(my_test_module)
341
342
# Load tests by name
343
suite = loader.loadTestsFromNames(['test_module.TestClass.test_method'])
344
```