0
# Dialog Handling
1

2
Browser dialog and alert handling capabilities for managing JavaScript alerts, confirmations, and prompts during test automation.
3

4
## Capabilities
5

6
### Alert Management
7

8
Methods for handling JavaScript alert dialogs that appear during test execution.
9

10
```typescript { .api }
11
/**
12
 * Accept the currently displayed alert/dialog
13
 * @returns Promise that resolves when alert is accepted
14
 */
15
acceptAlert(): Promise<void>;
16

17
/**
18
 * Dismiss/cancel the currently displayed alert/dialog  
19
 * @returns Promise that resolves when alert is dismissed
20
 */
21
dismissAlert(): Promise<void>;
22

23
/**
24
 * Get the text message from the currently displayed alert/dialog
25
 * @returns Promise resolving to the alert message text
26
 */
27
getAlertText(): Promise<string>;
28

29
/**
30
 * Send text to a prompt dialog
31
 * @param text - Text to enter in the prompt dialog
32
 * @returns Promise that resolves when text is sent
33
 */
34
sendAlertText(text: string): Promise<void>;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { remote } from "webdriverio";
41

42
const browser = await remote({ capabilities: { browserName: 'chrome' } });
43
await browser.url('https://example.com');
44

45
// Trigger an alert and handle it
46
await browser.$('#alert-button').click();
47

48
// Get alert text
49
const alertMessage = await browser.getAlertText();
50
console.log('Alert says:', alertMessage);
51

52
// Accept the alert
53
await browser.acceptAlert();
54

55
// Handle a confirmation dialog
56
await browser.$('#confirm-button').click();
57
const confirmText = await browser.getAlertText();
58

59
if (confirmText.includes('Are you sure?')) {
60
  await browser.acceptAlert(); // Click OK
61
} else {
62
  await browser.dismissAlert(); // Click Cancel
63
}
64

65
// Handle a prompt dialog
66
await browser.$('#prompt-button').click();
67
await browser.sendAlertText('My input text');
68
await browser.acceptAlert();
69
```
70

71
### Dialog State Detection
72

73
Methods for detecting and waiting for dialog states.
74

75
```typescript { .api }
76
/**
77
 * Check if an alert dialog is currently displayed
78
 * @returns Promise resolving to true if alert is present
79
 */
80
isAlertOpen(): Promise<boolean>;
81

82
/**
83
 * Wait for an alert dialog to appear
84
 * @param options - Wait options including timeout
85
 * @returns Promise resolving when alert appears
86
 */
87
waitForAlert(options?: {
88
  timeout?: number;
89
  timeoutMsg?: string;
90
  interval?: number;
91
}): Promise<void>;
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
// Check if alert is present before interacting
98
const isPresent = await browser.isAlertOpen();
99
if (isPresent) {
100
  const message = await browser.getAlertText();
101
  await browser.acceptAlert();
102
}
103

104
// Wait for alert to appear after action
105
await browser.$('#async-alert-button').click();
106
await browser.waitForAlert({ timeout: 5000 });
107
await browser.acceptAlert();
108
```
109

110
### Dialog Types
111

112
WebdriverIO handles three main types of JavaScript dialogs:
113

114
#### Alert Dialogs
115
Simple notification dialogs with only an "OK" button.
116

117
```javascript
118
// JavaScript: alert('Hello World!');
119
await browser.getAlertText(); // Returns: 'Hello World!'
120
await browser.acceptAlert();  // Clicks OK
121
```
122

123
#### Confirmation Dialogs  
124
Dialogs with "OK" and "Cancel" buttons for user confirmation.
125

126
```javascript
127
// JavaScript: confirm('Are you sure?');
128
await browser.getAlertText();   // Returns: 'Are you sure?'
129
await browser.acceptAlert();    // Clicks OK (returns true to JavaScript)
130
// OR
131
await browser.dismissAlert();   // Clicks Cancel (returns false to JavaScript)
132
```
133

134
#### Prompt Dialogs
135
Dialogs that request text input from the user.
136

137
```javascript
138
// JavaScript: prompt('Enter your name:', 'Default');
139
await browser.getAlertText();        // Returns: 'Enter your name:'
140
await browser.sendAlertText('John'); // Enter text
141
await browser.acceptAlert();         // Clicks OK (returns 'John' to JavaScript)
142
```
143

144
### Error Handling
145

146
Common patterns for robust dialog handling with error management.
147

148
```typescript
149
/**
150
 * Safely handle dialogs with try-catch pattern
151
 */
152
async function handleDialog(browser: WebdriverIO.Browser, expectedText?: string) {
153
  try {
154
    // Check if dialog is present
155
    const isOpen = await browser.isAlertOpen();
156
    if (!isOpen) {
157
      return false;
158
    }
159

160
    // Get and validate dialog text
161
    const alertText = await browser.getAlertText();
162
    
163
    if (expectedText && !alertText.includes(expectedText)) {
164
      console.warn(`Unexpected dialog text: ${alertText}`);
165
    }
166

167
    // Accept the dialog
168
    await browser.acceptAlert();
169
    return true;
170
    
171
  } catch (error) {
172
    console.error('Error handling dialog:', error);
173
    return false;
174
  }
175
}
176

177
// Usage
178
const handled = await handleDialog(browser, 'Success');
179
```
180

181
### Advanced Dialog Scenarios
182

183
Handling complex dialog scenarios in real-world applications.
184

185
```typescript
186
// Handle multiple sequential dialogs
187
async function handleSequentialDialogs(browser: WebdriverIO.Browser) {
188
  const dialogTexts: string[] = [];
189
  
190
  while (await browser.isAlertOpen()) {
191
    const text = await browser.getAlertText();
192
    dialogTexts.push(text);
193
    
194
    if (text.includes('error')) {
195
      await browser.dismissAlert();
196
      break;
197
    } else {
198
      await browser.acceptAlert();
199
    }
200
    
201
    // Small delay for next dialog to appear
202
    await browser.pause(100);
203
  }
204
  
205
  return dialogTexts;
206
}
207

208
// Handle dialogs with dynamic timeouts
209
async function handleDialogWithTimeout(browser: WebdriverIO.Browser, maxWait: number = 3000) {
210
  try {
211
    await browser.waitForAlert({ timeout: maxWait });
212
    const text = await browser.getAlertText();
213
    await browser.acceptAlert();
214
    return text;
215
  } catch (error) {
216
    console.log('No dialog appeared within timeout');
217
    return null;
218
  }
219
}
220
```
221

222
## Browser Compatibility
223

224
Dialog handling support varies by browser:
225

226
- **Chrome/Chromium**: Full support for all dialog types
227
- **Firefox**: Full support for all dialog types  
228
- **Safari**: Full support for all dialog types
229
- **Edge**: Full support for all dialog types
230
- **Mobile browsers**: Limited support, varies by platform
231

232
## Notes
233

234
- JavaScript dialogs are modal and block all interaction until handled
235
- Only one dialog can be active at a time in a browser context
236
- WebdriverIO automatically waits for dialogs to appear when commands are executed
237
- Dialog text and default values depend on the browser's language settings
238
- Some modern web applications use custom modal dialogs instead of native JavaScript dialogs