0
# Screen
1

2
Global query object bound to `document.body` for convenient document-wide queries without passing containers.
3

4
## Screen Object
5

6
```typescript
7
const screen: Screen;
8

9
interface Screen {
10
  // All query methods without container parameter
11
  // Signature: method(text, options?, waitOptions?) => element
12
  
13
  // Role queries
14
  getByRole(role, options?): HTMLElement;
15
  getAllByRole(role, options?): HTMLElement[];
16
  queryByRole(role, options?): HTMLElement | null;
17
  queryAllByRole(role, options?): HTMLElement[];
18
  findByRole(role, options?, waitOptions?): Promise<HTMLElement>;
19
  findAllByRole(role, options?, waitOptions?): Promise<HTMLElement[]>;
20
  
21
  // All other query types follow same pattern
22
  getByLabelText, queryByLabelText, findByLabelText, ...
23
  getByPlaceholderText, queryByPlaceholderText, findByPlaceholderText, ...
24
  getByText, queryByText, findByText, ...
25
  getByAltText, queryByAltText, findByAltText, ...
26
  getByTitle, queryByTitle, findByTitle, ...
27
  getByDisplayValue, queryByDisplayValue, findByDisplayValue, ...
28
  getByTestId, queryByTestId, findByTestId, ...
29
  
30
  // Debug utilities
31
  debug(element?, maxLength?, options?): void;
32
  logTestingPlaygroundURL(element?): string;
33
}
34
```
35

36
Usage:
37
```javascript
38
import {screen} from '@testing-library/dom';
39

40
// Query entire document
41
const button = screen.getByRole('button', {name: /submit/i});
42
const heading = screen.getByRole('heading', {level: 1});
43
const input = screen.getByLabelText('Email');
44

45
// Async queries
46
const message = await screen.findByText('Success');
47

48
// Debug
49
screen.debug();  // Pretty print document.body
50
```
51

52
## When to Use Screen vs Container
53

54
**Use `screen` (preferred):**
55
- Querying entire document
56
- Simple test cases
57
- Readable, concise code
58

59
**Use container queries:**
60
- Scoping to specific regions with `within`
61
- Multiple similar elements need disambiguation
62
- Testing components in isolation
63

64
Comparison:
65
```javascript
66
// Using screen
67
const button = screen.getByRole('button', {name: /submit/i});
68

69
// Using container (equivalent but verbose)
70
import {getByRole} from '@testing-library/dom';
71
const button = getByRole(document.body, 'button', {name: /submit/i});
72

73
// Use screen + within for scoping
74
const form = screen.getByRole('form');
75
const email = within(form).getByLabelText('Email');
76
```
77

78
## Debug Methods
79

80
```javascript
81
// Pretty print entire document
82
screen.debug();
83

84
// Debug specific element
85
const form = screen.getByRole('form');
86
screen.debug(form);
87

88
// Debug multiple elements
89
const buttons = screen.getAllByRole('button');
90
screen.debug(buttons);
91

92
// With options
93
screen.debug(form, 10000, {
94
  filterNode: (node) => node.nodeType === 1  // Only show elements
95
});
96
```
97

98
## Testing Playground
99

100
```javascript
101
// Get URL for query suggestions
102
const url = screen.logTestingPlaygroundURL();
103
console.log('Open in browser:', url);
104

105
// For specific element
106
const container = screen.getByTestId('app');
107
const url = screen.logTestingPlaygroundURL(container);
108
```
109

110