0
# nose2
1

2
A powerful Python testing framework that extends the built-in unittest module with enhanced discovery capabilities, parameterized testing, BDD-style test writing, extensive plugin system, and advanced features like coverage reporting, multiprocessing, and custom test runners.
3

4
## Package Information
5

6
- **Package Name**: nose2
7
- **Language**: Python  
8
- **Installation**: `pip install nose2`
9

10
## Core Imports
11

12
```python
13
import nose2
14
```
15

16
Test runner imports:
17

18
```python
19
from nose2 import main, discover
20
```
21

22
Testing tools and utilities:
23

24
```python
25
from nose2.tools import params, cartesian_params, such
26
from nose2.tools.decorators import with_setup, with_teardown
27
```
28

29
Plugin development:
30

31
```python
32
from nose2.events import Plugin
33
from nose2.session import Session
34
```
35

36
## Basic Usage
37

38
```python
39
# Simple test discovery and execution
40
import nose2
41
nose2.discover()
42

43
# Custom test program
44
from nose2.main import PluggableTestProgram
45

46
if __name__ == '__main__':
47
    # Run tests with custom configuration
48
    PluggableTestProgram(
49
        argv=['prog', '-v', '--start-dir', 'tests'],
50
        plugins=['nose2.plugins.coverage']
51
    )
52

53
# Using parameterized tests
54
from nose2.tools import params
55

56
@params(1, 2, 3, 4)
57
def test_is_positive(num):
58
    assert num > 0
59

60
# BDD-style testing with such
61
from nose2.tools import such
62

63
with such.A('math calculator') as it:
64
    
65
    @it.has_setup
66
    def setup():
67
        it.calc = Calculator()
68
    
69
    @it.should('add two numbers correctly')
70
    def test_addition(case):
71
        result = it.calc.add(2, 3)
72
        case.assertEqual(result, 5)
73
        
74
    it.createTests(globals())
75
```
76

77
## Architecture
78

79
nose2 follows a plugin-based architecture that provides extensive customization and extension capabilities:
80

81
- **Session**: Central configuration manager that handles command-line arguments, config files, and plugin lifecycle
82
- **PluggableTestProgram**: Main test runner that coordinates discovery, loading, and execution through plugins
83
- **Plugin System**: Hook-based architecture allowing plugins to modify behavior at every stage of test execution
84
- **Event-driven**: All plugin interactions happen through well-defined events and hooks
85
- **Loaders**: Pluggable test discovery and loading system supporting various test types and patterns
86

87
## Capabilities
88

89
### Test Discovery and Execution
90

91
Core functionality for discovering, loading, and running tests with extensive customization options through command-line arguments and configuration files.
92

93
```python { .api }
94
__version__: str
95

96
def discover(*args, **kwargs): ...
97
def main(*args, **kwargs): ...
98

99
class PluggableTestProgram:
100
    def __init__(self, **kwargs): ...
101
    def parseArgs(self, argv): ...
102
    def loadPlugins(self): ...
103
    def createTests(self): ...
104
    def runTests(self): ...
105
```
106

107
[Test Discovery and Execution](./test-discovery.md)
108

109
### Test Tools and Decorators  
110

111
Utilities for writing parameterized tests, BDD-style specifications, and enhanced test setup/teardown functionality.
112

113
```python { .api }
114
def params(*paramList): ...
115
def cartesian_params(*paramList): ...
116
def with_setup(setup): ...
117
def with_teardown(teardown): ...
118

119
class Scenario:
120
    def having(self, description): ...
121
    def should(self, desc): ...
122
    def has_setup(self, func): ...
123
    def has_teardown(self, func): ...
124
```
125

126
[Test Tools and Decorators](./test-tools.md)
127

128
### Plugin Development  
129

130
Framework for creating custom plugins that extend nose2's functionality through a comprehensive hook system and event-driven architecture.
131

132
```python { .api }
133
class Plugin:
134
    def __init__(self, **kwargs): ...
135
    def register(self): ...
136
    def addOption(self, callback, short_opt, long_opt, help): ...
137

138
class Session:
139
    def get(self, section): ...
140
    def loadPlugins(self, plugins, exclude): ...
141
    def loadConfigFiles(self, *filenames): ...
142
```
143

144
[Plugin Development](./plugin-development.md)
145

146
### Configuration Management
147

148
System for managing test configuration through command-line arguments, configuration files, and programmatic settings.
149

150
```python { .api }
151
class Config:
152
    def as_bool(self, key, default=None): ...
153
    def as_int(self, key, default=None): ...
154
    def as_str(self, key, default=None): ...
155
    def as_list(self, key, default=None): ...
156
```
157

158
[Configuration Management](./configuration.md)
159

160
## Types
161

162
```python { .api }
163
class PluggableTestLoader:
164
    """Test loader that defers all loading to plugins."""
165
    suiteClass = unittest.TestSuite
166
    
167
    def loadTestsFromModule(self, module): ...
168
    def loadTestsFromNames(self, testNames, module=None): ...
169
    def loadTestsFromName(self, name, module=None): ...
170

171
class PluggableTestResult:
172
    """Test result that defers to plugins."""
173
    shouldStop: bool
174
    failfast: bool
175
    
176
    def startTest(self, test): ...
177
    def stopTest(self, test): ...
178
    def addError(self, test, err): ...
179
    def addFailure(self, test, err): ...
180
    def addSuccess(self, test): ...
181
```