0
# Window & Frame Management
1

2
Multi-window and frame handling for complex web applications, including window switching, sizing, and iframe navigation.
3

4
## Capabilities
5

6
### Window Control
7

8
Manage browser windows, tabs, and their properties.
9

10
```javascript { .api }
11
/**
12
 * Open new window with URL and name
13
 * @param url - URL to open in new window
14
 * @param name - Window name/target
15
 * @param cb - Callback receiving (err)
16
 */
17
newWindow(url: string, name: string, cb?: callback): void;
18

19
/**
20
 * Close current window
21
 * @param cb - Callback receiving (err)
22
 */
23
close(cb?: callback): void;
24

25
/**
26
 * Switch to window by handle
27
 * @param windowHandle - Window handle identifier
28
 * @param cb - Callback receiving (err)
29
 */
30
window(windowHandle: string, cb?: callback): void;
31

32
/**
33
 * Get current window handle
34
 * @param cb - Callback receiving (err, windowHandle)
35
 */
36
windowHandle(cb?: callback): string;
37

38
/**
39
 * Get all window handles
40
 * @param cb - Callback receiving (err, windowHandles)
41
 */
42
windowHandles(cb?: callback): string[];
43

44
/**
45
 * Get window name
46
 * @param cb - Callback receiving (err, windowName)
47
 */
48
windowName(cb?: callback): string;
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
// Get all open windows
55
browser.windowHandles(function(err, handles) {
56
  console.log('Open windows:', handles.length);
57
  handles.forEach((handle, index) => {
58
    console.log(`Window ${index}: ${handle}`);
59
  });
60
});
61

62
// Switch between windows
63
browser.windowHandles(function(err, handles) {
64
  if (handles.length > 1) {
65
    // Switch to second window
66
    browser.window(handles[1], function(err) {
67
      console.log('Switched to second window');
68
      
69
      browser.title(function(err, title) {
70
        console.log('Second window title:', title);
71
      });
72
    });
73
  }
74
});
75

76
// Open new window and switch to it
77
browser.newWindow('https://example.com', 'example', function(err) {
78
  browser.windowHandles(function(err, handles) {
79
    // Switch to the newly opened window (usually the last one)
80
    browser.window(handles[handles.length - 1]);
81
  });
82
});
83

84
// Promise chain window management
85
browser
86
  .windowHandles()
87
  .then(handles => {
88
    console.log('Available windows:', handles);
89
    if (handles.length > 1) {
90
      return browser.window(handles[1]);
91
    }
92
  })
93
  .title()
94
  .then(title => console.log('Window title:', title));
95
```
96

97
### Window Sizing and Positioning
98

99
Control window dimensions and screen position.
100

101
```javascript { .api }
102
/**
103
 * Set window size
104
 * @param windowHandle - Window handle (or current window)
105
 * @param width - Window width in pixels
106
 * @param height - Window height in pixels
107
 * @param cb - Callback receiving (err)
108
 */
109
windowSize(windowHandle: string, width: number, height: number, cb?: callback): void;
110

111
/**
112
 * Get window size
113
 * @param windowHandle - Window handle (or current window)
114
 * @param cb - Callback receiving (err, size)
115
 */
116
getWindowSize(windowHandle: string, cb?: callback): {width: number, height: number};
117

118
/**
119
 * Set current window size
120
 * @param width - Window width in pixels
121
 * @param height - Window height in pixels
122
 * @param cb - Callback receiving (err)
123
 */
124
setWindowSize(width: number, height: number, cb?: callback): void;
125

126
/**
127
 * Get window position
128
 * @param windowHandle - Window handle
129
 * @param cb - Callback receiving (err, position)
130
 */
131
getWindowPosition(windowHandle: string, cb?: callback): {x: number, y: number};
132

133
/**
134
 * Set window position
135
 * @param x - X coordinate on screen
136
 * @param y - Y coordinate on screen
137
 * @param cb - Callback receiving (err)
138
 */
139
setWindowPosition(x: number, y: number, cb?: callback): void;
140

141
/**
142
 * Maximize window
143
 * @param windowHandle - Window handle
144
 * @param cb - Callback receiving (err)
145
 */
146
maximize(windowHandle: string, cb?: callback): void;
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
// Set window to specific size for responsive testing
153
browser.setWindowSize(1024, 768, function(err) {
154
  console.log('Window resized to tablet size');
155
  
156
  // Take screenshot at this size
157
  browser.saveScreenshot('tablet-view.png');
158
});
159

160
// Get current window dimensions
161
browser.getWindowSize('current', function(err, size) {
162
  console.log('Current window size:', size.width, 'x', size.height);
163
});
164

165
// Position window on screen
166
browser.setWindowPosition(100, 100, function(err) {
167
  console.log('Window moved to position 100,100');
168
});
169

170
// Maximize window for full-screen testing
171
browser.maximize('current', function(err) {
172
  console.log('Window maximized');
173
});
174

175
// Multi-size testing
176
const testSizes = [
177
  {width: 320, height: 568, name: 'mobile'},
178
  {width: 768, height: 1024, name: 'tablet'},
179
  {width: 1920, height: 1080, name: 'desktop'}
180
];
181

182
testSizes.forEach(size => {
183
  browser.setWindowSize(size.width, size.height);
184
  browser.saveScreenshot(`${size.name}-view.png`);
185
});
186

187
// Promise chain window sizing
188
browser
189
  .setWindowSize(1366, 768)
190
  .getWindowSize('current')
191
  .then(size => {
192
    console.log('Verified size:', size);
193
    return browser.maximize('current');
194
  })
195
  .getWindowSize('current')
196
  .then(maxSize => {
197
    console.log('Maximized size:', maxSize);
198
  });
199
```
200

201
### Frame Management
202

203
Navigate between frames and iframes within web pages.
204

205
```javascript { .api }
206
/**
207
 * Switch to frame
208
 * @param frameRef - Frame reference (index, name, id, WebElement, or null for default)
209
 * @param cb - Callback receiving (err)
210
 */
211
frame(frameRef: string | number | Element | null, cb?: callback): void;
212
```
213

214
**Usage Examples:**
215

216
```javascript
217
// Switch to frame by index
218
browser.frame(0, function(err) {
219
  console.log('Switched to first frame');
220
  
221
  // Interact with elements inside the frame
222
  browser.elementById('frame-button', function(err, button) {
223
    button.click();
224
  });
225
});
226

227
// Switch to frame by name or id
228
browser.frame('payment-frame', function(err) {
229
  console.log('Switched to payment frame');
230
  
231
  // Fill payment form inside frame
232
  browser.elementById('credit-card-number', function(err, input) {
233
    input.type('4111111111111111');
234
  });
235
});
236

237
// Switch to frame by element reference
238
browser.elementByTagName('iframe', function(err, iframe) {
239
  browser.frame(iframe, function(err) {
240
    console.log('Switched to iframe element');
241
  });
242
});
243

244
// Switch back to default content (main page)
245
browser.frame(null, function(err) {
246
  console.log('Switched back to main page');
247
});
248

249
// Nested frame navigation
250
browser
251
  .frame('outer-frame')           // Enter outer frame
252
  .frame('inner-frame')           // Enter nested frame
253
  .elementById('nested-content')  // Interact with nested content
254
  .text()
255
  .then(text => {
256
    console.log('Nested frame content:', text);
257
    return browser.frame(null);   // Back to main page
258
  });
259

260
// Complex frame interaction
261
browser.frame('settings-frame', function(err) {
262
  browser.elementById('save-settings', function(err, button) {
263
    button.click(function(err) {
264
      // Wait for save to complete
265
      browser.waitForElementById('success-message', 5000, function(err, message) {
266
        message.text(function(err, text) {
267
          console.log('Settings saved:', text);
268
          
269
          // Switch back to main page
270
          browser.frame(null);
271
        });
272
      });
273
    });
274
  });
275
});
276
```
277

278
### Multi-Window Testing Patterns
279

280
Advanced patterns for testing multi-window applications.
281

282
**Usage Examples:**
283

284
```javascript
285
// Handle popup windows
286
browser.elementById('open-popup', function(err, button) {
287
  button.click(function(err) {
288
    // Wait for popup to open
289
    browser.sleep(1000, function() {
290
      browser.windowHandles(function(err, handles) {
291
        if (handles.length > 1) {
292
          // Switch to popup
293
          browser.window(handles[1], function(err) {
294
            // Interact with popup
295
            browser.elementById('popup-content', function(err, content) {
296
              content.text(function(err, text) {
297
                console.log('Popup content:', text);
298
                
299
                // Close popup
300
                browser.close(function(err) {
301
                  // Switch back to main window
302
                  browser.window(handles[0]);
303
                });
304
              });
305
            });
306
          });
307
        }
308
      });
309
    });
310
  });
311
});
312

313
// Tab management helper
314
function switchToTab(tabIndex, callback) {
315
  browser.windowHandles(function(err, handles) {
316
    if (err) return callback(err);
317
    if (tabIndex >= handles.length) {
318
      return callback(new Error('Tab index out of range'));
319
    }
320
    browser.window(handles[tabIndex], callback);
321
  });
322
}
323

324
// Usage of tab helper
325
switchToTab(1, function(err) {
326
  browser.title(function(err, title) {
327
    console.log('Second tab title:', title);
328
  });
329
});
330

331
// Window cleanup utility
332
function closeAllWindowsExceptMain(callback) {
333
  browser.windowHandles(function(err, handles) {
334
    if (err) return callback(err);
335
    
336
    const mainWindow = handles[0];
337
    let closed = 0;
338
    
339
    // Close all windows except the first one
340
    for (let i = 1; i < handles.length; i++) {
341
      browser.window(handles[i], function(err) {
342
        if (err) return callback(err);
343
        
344
        browser.close(function(err) {
345
          if (err) return callback(err);
346
          
347
          closed++;
348
          if (closed === handles.length - 1) {
349
            // Switch back to main window
350
            browser.window(mainWindow, callback);
351
          }
352
        });
353
      });
354
    }
355
    
356
    // If no windows to close, just ensure we're on main window
357
    if (handles.length === 1) {
358
      browser.window(mainWindow, callback);
359
    }
360
  });
361
}
362

363
// Promise-based window management
364
class WindowManager {
365
  constructor(browser) {
366
    this.browser = browser;
367
    this.originalWindow = null;
368
  }
369
  
370
  async saveCurrentWindow() {
371
    this.originalWindow = await this.browser.windowHandle();
372
    return this.originalWindow;
373
  }
374
  
375
  async openNewTab(url) {
376
    await this.browser.execute(`window.open('${url}', '_blank')`);
377
    const handles = await this.browser.windowHandles();
378
    return handles[handles.length - 1];
379
  }
380
  
381
  async switchToWindow(handle) {
382
    await this.browser.window(handle);
383
    return handle;
384
  }
385
  
386
  async closeCurrentWindow() {
387
    await this.browser.close();
388
  }
389
  
390
  async returnToOriginal() {
391
    if (this.originalWindow) {
392
      await this.browser.window(this.originalWindow);
393
    }
394
  }
395
  
396
  async closeAllExceptOriginal() {
397
    const handles = await this.browser.windowHandles();
398
    for (const handle of handles) {
399
      if (handle !== this.originalWindow) {
400
        await this.browser.window(handle);
401
        await this.browser.close();
402
      }
403
    }
404
    await this.returnToOriginal();
405
  }
406
}
407

408
// Usage of WindowManager
409
const windowManager = new WindowManager(browser);
410

411
async function testMultipleWindows() {
412
  await windowManager.saveCurrentWindow();
413
  
414
  // Open multiple tabs
415
  const tab1 = await windowManager.openNewTab('https://example.com');
416
  const tab2 = await windowManager.openNewTab('https://google.com');
417
  
418
  // Test each tab
419
  await windowManager.switchToWindow(tab1);
420
  const title1 = await browser.title();
421
  console.log('Tab 1 title:', title1);
422
  
423
  await windowManager.switchToWindow(tab2);
424
  const title2 = await browser.title();
425
  console.log('Tab 2 title:', title2);
426
  
427
  // Clean up
428
  await windowManager.closeAllExceptOriginal();
429
}
430
```