0
# Test Fixtures
1

2
Pytest fixtures that enable tests to add rich multimedia content and metadata to HTML reports. These fixtures provide a way to include additional context, debugging information, screenshots, logs, and other relevant data alongside test results.
3

4
## Capabilities
5

6
### extras Fixture
7

8
The primary fixture for adding extra content to test reports. Provides a list that tests can append extra content items to, which will be displayed in the HTML report.
9

10
```python { .api }
11
@pytest.fixture
12
def extras(pytestconfig):
13
    """
14
    Add details to the HTML reports.
15

16
    This fixture provides a list that tests can append extra content to.
17
    Content added via extras will be displayed in the HTML report for
18
    the specific test.
19

20
    Parameters:
21
    - pytestconfig: pytest configuration object
22

23
    Yields:
24
    - list: List to append extra content items to
25

26
    Usage:
27
        def test_example(extras):
28
            extras.append(pytest_html.extras.url("https://example.com"))
29
            extras.append(pytest_html.extras.text("Debug info"))
30
    """
31
```
32

33
**Usage Example:**
34

35
```python
36
import pytest_html
37

38
def test_with_extras(extras):
39
    # Add a URL for reference
40
    extras.append(pytest_html.extras.url("https://api.example.com/status"))
41
    
42
    # Add debugging text
43
    extras.append(pytest_html.extras.text("Database connection: OK"))
44
    
45
    # Add a screenshot (base64 encoded)
46
    with open("screenshot.png", "rb") as f:
47
        screenshot_data = base64.b64encode(f.read()).decode()
48
        extras.append(pytest_html.extras.png(screenshot_data, "Test Screenshot"))
49
    
50
    # Add JSON data
51
    debug_data = {"user_id": 123, "session": "abc123"}
52
    extras.append(pytest_html.extras.json(debug_data, "Debug Data"))
53
    
54
    # Test logic here
55
    assert True
56
```
57

58
### extra Fixture (Deprecated)
59

60
Legacy fixture that provides the same functionality as `extras`. This fixture is deprecated and will be removed in a future release.
61

62
```python { .api }
63
@pytest.fixture
64
def extra(pytestconfig):
65
    """
66
    DEPRECATED: Add details to the HTML reports.
67
    
68
    This fixture is deprecated and will be removed in a future release.
69
    Use 'extras' instead.
70

71
    Parameters:
72
    - pytestconfig: pytest configuration object
73

74
    Yields:
75
    - list: List to append extra content items to
76
    """
77
```
78

79
## Integration with pytest-html
80

81
The fixtures work by storing extra content in pytest's stash system using a special key. The content is then processed during report generation and embedded into the HTML output.
82

83
### Internal Implementation
84

85
```python { .api }
86
# Stash key for storing extras data
87
extras_stash_key = pytest.StashKey[list]()
88
```
89

90
The fixtures store data in `pytestconfig.stash[extras_stash_key]` which is then accessed by the plugin during report generation via the `pytest_runtest_makereport` hook.
91

92
### Content Processing
93

94
Extra content added through fixtures is processed during the `pytest_runtest_makereport` hook:
95

96
1. Fixture extras are retrieved from the stash
97
2. Plugin extras are retrieved from the report object  
98
3. Deprecated extras are retrieved from `report.extra` (with deprecation warning)
99
4. All extras are combined and stored in `report.extras`
100
5. The HTML report generator processes the extras during rendering
101

102
This ensures that all extra content from various sources is properly included in the final HTML report.