0
# Locators & Waiting
1

2
Modern element selection with automatic waiting, retries, and fluent interface for reliable element interactions.
3

4
## Capabilities
5

6
### Locator Class
7

8
Modern element locator with built-in waiting and retry mechanisms.
9

10
```typescript { .api }
11
/**
12
 * Modern element locator with automatic waiting and retries
13
 */
14
class Locator<T> {
15
  /** Set timeout for all operations */
16
  setTimeout(timeout: number): Locator<T>;
17
  
18
  /** Set visibility requirement */
19
  setVisibility(visibility: VisibilityOption): Locator<T>;
20
  
21
  /** Set wait for enabled requirement */
22
  setWaitForEnabled(wait: boolean): Locator<T>;
23
  
24
  /** Set viewport requirement */
25
  setEnsureElementIsInTheViewport(ensure: boolean): Locator<T>;
26
  
27
  /** Set stable bounding box requirement */
28
  setWaitForStableBoundingBox(wait: boolean): Locator<T>;
29
  
30
  /** Wait for element handle */
31
  waitHandle(options?: ActionOptions): Promise<HandleFor<T>>;
32
  
33
  /** Wait for element */
34
  wait(options?: ActionOptions): Promise<T>;
35
  
36
  /** Click element with automatic waiting */
37
  click(options?: LocatorClickOptions): Promise<void>;
38
  
39
  /** Fill input field */
40
  fill(value: string, options?: ActionOptions): Promise<void>;
41
  
42
  /** Focus element */
43
  focus(options?: ActionOptions): Promise<void>;
44
  
45
  /** Hover over element */
46
  hover(options?: ActionOptions): Promise<void>;
47
  
48
  /** Scroll element */
49
  scroll(options?: LocatorScrollOptions): Promise<void>;
50
  
51
  /** Filter locator results */
52
  filter<U extends T>(predicate: Predicate<T, U>): Locator<U>;
53
  
54
  /** Map locator results */
55
  map<To>(mapper: Mapper<T, To>): Locator<To>;
56
  
57
  /** Race multiple locators */
58
  static race<T>(locators: T[]): RaceLocator<AwaitedLocator<T[number]>>;
59
}
60

61
type VisibilityOption = "visible" | "hidden";
62

63
interface ActionOptions {
64
  timeout?: number;
65
}
66

67
interface LocatorClickOptions extends ActionOptions {
68
  button?: "left" | "right" | "middle";
69
  clickCount?: number;
70
  delay?: number;
71
}
72

73
interface LocatorScrollOptions extends ActionOptions {
74
  behavior?: "auto" | "instant" | "smooth";
75
  block?: "start" | "center" | "end" | "nearest";
76
  inline?: "start" | "center" | "end" | "nearest";
77
}
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
// Create locator
84
const submitButton = page.locator("#submit-button");
85

86
// Configure locator
87
const stableButton = submitButton
88
  .setTimeout(10000)
89
  .setVisibility("visible")
90
  .setWaitForEnabled(true)
91
  .setWaitForStableBoundingBox(true);
92

93
// Use locator with automatic retries
94
await stableButton.click();
95

96
// Filter and map locators
97
const visibleLinks = page.locator("a")
98
  .filter(async (el) => await el.isVisible())
99
  .map(async (el) => await el.getAttribute("href"));
100

101
// Race multiple locators
102
const firstButton = Locator.race([
103
  page.locator("#button1"),
104
  page.locator("#button2"),
105
  page.locator("#button3")
106
]);
107
await firstButton.click();
108
```
109

110
### Page Locator Methods
111

112
Create locators from page context.
113

114
```typescript { .api }
115
/**
116
 * Create locator for selector
117
 * @param selector - CSS selector
118
 * @returns Locator instance
119
 */
120
locator(selector: string): Locator;
121

122
/**
123
 * Race multiple locators
124
 * @param locators - Array of locators to race
125
 * @returns Racing locator
126
 */
127
locatorRace(locators: Locator[]): Locator;
128
```
129

130
**Usage Examples:**
131

132
```typescript
133
// Create locators
134
const searchBox = page.locator("#search");
135
const results = page.locator(".search-result");
136

137
// Race for first available action
138
const quickAction = page.locatorRace([
139
  page.locator("#quick-save"),
140
  page.locator("#quick-cancel"),
141
  page.locator("#quick-submit")
142
]);
143

144
await quickAction.click();
145
```
146

147
### Waiting Utilities
148

149
Traditional waiting methods for various conditions.
150

151
```typescript { .api }
152
/**
153
 * Wait for selector to appear
154
 */
155
waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle>;
156

157
/**
158
 * Wait for function condition
159
 */
160
waitForFunction<R>(
161
  pageFunction: (...args: any[]) => R,
162
  options?: WaitForFunctionOptions,
163
  ...args: any[]
164
): Promise<JSHandle<R>>;
165

166
/**
167
 * Wait for timeout
168
 */
169
waitForTimeout(milliseconds: number): Promise<void>;
170

171
/**
172
 * Wait for file chooser dialog
173
 */
174
waitForFileChooser(options?: WaitTimeoutOptions): Promise<FileChooser>;
175

176
interface WaitForSelectorOptions {
177
  visible?: boolean;
178
  hidden?: boolean;
179
  timeout?: number;
180
}
181

182
interface WaitForFunctionOptions {
183
  timeout?: number;
184
  polling?: "raf" | "mutation" | number;
185
}
186
```
187

188
**Usage Examples:**
189

190
```typescript
191
// Wait for elements
192
await page.waitForSelector(".loading", { hidden: true });
193
await page.waitForSelector("#content", { visible: true, timeout: 5000 });
194

195
// Wait for conditions
196
await page.waitForFunction(() => window.dataReady === true);
197
await page.waitForFunction(
198
  (text) => document.body.innerText.includes(text),
199
  { polling: 1000 },
200
  "Success"
201
);
202

203
// Wait for file chooser
204
const fileChooserPromise = page.waitForFileChooser();
205
await page.click("#upload-button");
206
const fileChooser = await fileChooserPromise;
207
await fileChooser.accept(["path/to/file.pdf"]);
208
```
209

210
### FileChooser Class
211

212
Handle file chooser dialogs for file upload interactions.
213

214
```typescript { .api }
215
/**
216
 * File chooser dialog for file uploads
217
 */
218
class FileChooser {
219
  /** Check if multiple file selection is allowed */
220
  isMultiple(): boolean;
221
  
222
  /** Accept file chooser with file paths */
223
  accept(filePaths: string[]): Promise<void>;
224
  
225
  /** Cancel file chooser */
226
  cancel(): Promise<void>;
227
}
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
// Handle file upload
234
const fileChooserPromise = page.waitForFileChooser();
235
await page.click("#file-upload-button");
236
const fileChooser = await fileChooserPromise;
237

238
// Check if multiple files allowed
239
if (fileChooser.isMultiple()) {
240
  // Upload multiple files
241
  await fileChooser.accept([
242
    "/path/to/file1.pdf",
243
    "/path/to/file2.jpg",
244
    "/path/to/file3.txt"
245
  ]);
246
} else {
247
  // Upload single file
248
  await fileChooser.accept(["/path/to/document.pdf"]);
249
}
250

251
// Cancel file chooser
252
// await fileChooser.cancel();
253
```