selenium-webdriver 4.19.0 → 4.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/CHANGES.md +21 -0
  2. package/README.md +1 -1
  3. package/bidi/addInterceptParameters.js +28 -2
  4. package/bidi/browser.js +17 -0
  5. package/bidi/browsingContext.js +206 -39
  6. package/bidi/browsingContextInspector.js +51 -0
  7. package/bidi/browsingContextTypes.js +31 -0
  8. package/bidi/captureScreenshotParameters.js +96 -0
  9. package/bidi/clipRectangle.js +127 -0
  10. package/bidi/continueRequestParameters.js +39 -0
  11. package/bidi/continueResponseParameters.js +40 -0
  12. package/bidi/cookieFilter.js +60 -0
  13. package/bidi/createContextParameters.js +73 -0
  14. package/bidi/evaluateResult.js +17 -0
  15. package/bidi/index.js +0 -1
  16. package/bidi/input.js +27 -3
  17. package/bidi/interceptPhase.js +4 -0
  18. package/bidi/logEntries.js +66 -0
  19. package/bidi/network.js +102 -0
  20. package/bidi/networkTypes.js +346 -1
  21. package/bidi/partialCookie.js +48 -0
  22. package/bidi/partitionDescriptor.js +33 -0
  23. package/bidi/partitionKey.js +17 -0
  24. package/bidi/protocolType.js +20 -0
  25. package/bidi/protocolValue.js +129 -2
  26. package/bidi/provideResponseParameters.js +40 -0
  27. package/bidi/realmInfo.js +27 -0
  28. package/bidi/resultOwnership.js +4 -0
  29. package/bidi/scriptManager.js +119 -1
  30. package/bidi/scriptTypes.js +36 -0
  31. package/bidi/storage.js +30 -0
  32. package/bidi/urlPattern.js +35 -0
  33. package/bin/linux/selenium-manager +0 -0
  34. package/bin/macos/selenium-manager +0 -0
  35. package/bin/windows/selenium-manager.exe +0 -0
  36. package/chromium.js +12 -9
  37. package/common/driverFinder.js +36 -4
  38. package/common/seleniumManager.js +7 -39
  39. package/eslint.config.js +107 -0
  40. package/firefox.js +20 -6
  41. package/http/index.js +6 -6
  42. package/ie.js +8 -4
  43. package/index.js +11 -0
  44. package/io/exec.js +1 -1
  45. package/io/index.js +3 -2
  46. package/io/zip.js +1 -1
  47. package/lib/atoms/find-elements.js +2 -2
  48. package/lib/http.js +5 -4
  49. package/lib/input.js +0 -1
  50. package/lib/pinnedScript.js +1 -1
  51. package/lib/select.js +102 -60
  52. package/lib/until.js +3 -3
  53. package/lib/util.js +1 -0
  54. package/lib/webdriver.js +2 -2
  55. package/net/index.js +1 -1
  56. package/net/portprober.js +1 -1
  57. package/package.json +13 -7
  58. package/remote/index.js +1 -1
  59. package/remote/util.js +2 -2
  60. package/safari.js +3 -3
  61. package/testing/index.js +12 -8
package/CHANGES.md CHANGED
@@ -1,3 +1,24 @@
1
+ ## 4.21.0
2
+
3
+ - Add CDP for Chrome 125 and remove 122
4
+ - Ensure 'selectVisibleByText' method is same as other languages (#13899)
5
+ - Ensure parity in the locators used by methods (#13902)
6
+
7
+ ## 4.20.0
8
+
9
+ - Add CDP for Chrome 124 and remove 121
10
+ - [bidi] Update capture screenshot APIs to include all parameters and remove scroll parameter (
11
+ #13744)
12
+ - [bidi] Implement functionality to retrieve all top-level browsing contexts
13
+ - Set browserName by default when browserOptions are used
14
+ - Implement fullPageScreenshot functionality for Firefox (#13301)
15
+ - Nightly JS builds are now pushed to GitHub packages
16
+ - Making Selenium Manager a thin wrapper (#13853)
17
+ - This change has been made to make it easier to maintain and improve, the interface has
18
+ changed and if users were invoking it, they might experience issues. Selenium Manager is
19
+ still in beta and these type of changes are expected.
20
+ - [bidi] Update browsing context create method (#13766)
21
+
1
22
  ## 4.19.0
2
23
 
3
24
  - Add CDP for Chrome 123 and remove 120
package/README.md CHANGED
@@ -218,7 +218,7 @@ under the License.
218
218
  [LTS]: https://github.com/nodejs/LTS
219
219
  [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
220
220
  [api]: http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/
221
- [chrome]: http://chromedriver.storage.googleapis.com/index.html
221
+ [chrome]: https://googlechromelabs.github.io/chrome-for-testing/#stable
222
222
  [gh]: https://github.com/SeleniumHQ/selenium/
223
223
  [issues]: https://github.com/SeleniumHQ/selenium/issues
224
224
  [edge]: http://go.microsoft.com/fwlink/?LinkId=619687
@@ -29,6 +29,13 @@ class AddInterceptParameters {
29
29
  }
30
30
  }
31
31
 
32
+ /**
33
+ * Adds a URL pattern to intercept.
34
+ *
35
+ * @param {UrlPattern} pattern - The URL pattern to add.
36
+ * @returns {AddInterceptParameters} - Returns the current instance of the class AddInterceptParameters for chaining.
37
+ * @throws {Error} - Throws an error if the pattern is not an instance of UrlPattern.
38
+ */
32
39
  urlPattern(pattern) {
33
40
  if (!(pattern instanceof UrlPattern)) {
34
41
  throw new Error(`Pattern must be an instance of UrlPattern. Received: '${pattern})'`)
@@ -37,6 +44,13 @@ class AddInterceptParameters {
37
44
  return this
38
45
  }
39
46
 
47
+ /**
48
+ * Adds array of URL patterns to intercept.
49
+ *
50
+ * @param {UrlPattern[]} patterns - An array of UrlPattern instances representing the URL patterns to intercept.
51
+ * @returns {AddInterceptParameters} - Returns the instance of AddInterceptParameters for chaining.
52
+ * @throws {Error} - Throws an error if the pattern is not an instance of UrlPattern.
53
+ */
40
54
  urlPatterns(patterns) {
41
55
  patterns.forEach((pattern) => {
42
56
  if (!(pattern instanceof UrlPattern)) {
@@ -47,8 +61,15 @@ class AddInterceptParameters {
47
61
  return this
48
62
  }
49
63
 
64
+ /**
65
+ * Adds string URL to intercept.
66
+ *
67
+ * @param {string} pattern - The URL pattern to be added.
68
+ * @returns {AddInterceptParameters} - Returns the instance of AddInterceptParameters for chaining..
69
+ * @throws {Error} - If the pattern is not an instance of String.
70
+ */
50
71
  urlStringPattern(pattern) {
51
- if (!(pattern instanceof String)) {
72
+ if (typeof pattern !== 'string') {
52
73
  throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
53
74
  }
54
75
 
@@ -56,9 +77,14 @@ class AddInterceptParameters {
56
77
  return this
57
78
  }
58
79
 
80
+ /**
81
+ * Adds array of string URLs to intercept.
82
+ * @param {string[]} patterns - An array of URL string patterns.
83
+ * @returns {this} - Returns the instance of AddInterceptParameters for chaining.
84
+ */
59
85
  urlStringPatterns(patterns) {
60
86
  patterns.forEach((pattern) => {
61
- if (!(pattern instanceof String)) {
87
+ if (typeof pattern !== 'string') {
62
88
  throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
63
89
  }
64
90
  this.#urlPatterns.push({ type: 'string', pattern: pattern })
package/bidi/browser.js CHANGED
@@ -15,6 +15,10 @@
15
15
  // specific language governing permissions and limitations
16
16
  // under the License.
17
17
 
18
+ /**
19
+ * Represents the commands and events under Browser Module.
20
+ * Described in https://w3c.github.io/webdriver-bidi/#module-browser
21
+ */
18
22
  class Browser {
19
23
  constructor(driver) {
20
24
  this._driver = driver
@@ -28,6 +32,10 @@ class Browser {
28
32
  this.bidi = await this._driver.getBidi()
29
33
  }
30
34
 
35
+ /**
36
+ * Creates a new user context.
37
+ * @returns {Promise<string>} A promise that resolves to the user context id.
38
+ */
31
39
  async createUserContext() {
32
40
  const command = {
33
41
  method: 'browser.createUserContext',
@@ -39,6 +47,10 @@ class Browser {
39
47
  return response.result.userContext
40
48
  }
41
49
 
50
+ /**
51
+ * Gets the list of all user contexts.
52
+ * @returns {Promise<string[]>} A promise that resolves to an array of user context ids.
53
+ */
42
54
  async getUserContexts() {
43
55
  const command = {
44
56
  method: 'browser.getUserContexts',
@@ -58,6 +70,11 @@ class Browser {
58
70
  return userContexts
59
71
  }
60
72
 
73
+ /**
74
+ * Removes a user context.
75
+ * @param {string} userContext The user context id to be removed.
76
+ * @returns {Promise<void>}
77
+ */
61
78
  async removeUserContext(userContext) {
62
79
  const command = {
63
80
  method: 'browser.removeUserContext',
@@ -19,7 +19,13 @@ const { InvalidArgumentError, NoSuchFrameError } = require('../lib/error')
19
19
  const { BrowsingContextInfo } = require('./browsingContextTypes')
20
20
  const { SerializationOptions, ReferenceValue, RemoteValue } = require('./protocolValue')
21
21
  const { WebElement } = require('../lib/webdriver')
22
+ const { CaptureScreenshotParameters } = require('./captureScreenshotParameters')
23
+ const { CreateContextParameters } = require('./createContextParameters')
22
24
 
25
+ /**
26
+ * Represents the locator to locate nodes in the browsing context.
27
+ * Described in https://w3c.github.io/webdriver-bidi/#type-browsingContext-Locator.
28
+ */
23
29
  class Locator {
24
30
  static Type = Object.freeze({
25
31
  CSS: 'css',
@@ -41,14 +47,35 @@ class Locator {
41
47
  this.#maxDepth = maxDepth
42
48
  }
43
49
 
50
+ /**
51
+ * Creates a new Locator object with CSS selector type.
52
+ *
53
+ * @param {string} value - The CSS selector value.
54
+ * @returns {Locator} A new Locator object with CSS selector type.
55
+ */
44
56
  static css(value) {
45
57
  return new Locator(Locator.Type.CSS, value)
46
58
  }
47
59
 
60
+ /**
61
+ * Creates a new Locator object with the given XPath value.
62
+ *
63
+ * @param {string} value - The XPath value.
64
+ * @returns {Locator} A new Locator object.
65
+ */
48
66
  static xpath(value) {
49
67
  return new Locator(Locator.Type.XPATH, value)
50
68
  }
51
69
 
70
+ /**
71
+ * Creates a new Locator object with the specified inner text value.
72
+ *
73
+ * @param {string} value - The inner text value to locate.
74
+ * @param {boolean|undefined} [ignoreCase] - Whether to ignore the case when matching the inner text value.
75
+ * @param {string|undefined} [matchType] - The type of matching to perform (full or partial).
76
+ * @param {number|undefined} [maxDepth] - The maximum depth to search for the inner text value.
77
+ * @returns {Locator} A new Locator object with the specified inner text value.
78
+ */
52
79
  static innerText(value, ignoreCase = undefined, matchType = undefined, maxDepth = undefined) {
53
80
  return new Locator(Locator.Type.INNER_TEXT, value, ignoreCase, matchType, maxDepth)
54
81
  }
@@ -66,6 +93,12 @@ class Locator {
66
93
  }
67
94
  }
68
95
 
96
+ /**
97
+ * Represents the contains under BrowsingContext module commands.
98
+ * Described in https://w3c.github.io/webdriver-bidi/#module-browsingContext
99
+ * Each browsing context command requires a browsing context id.
100
+ * Hence, this class represent browsing context lifecycle.
101
+ */
69
102
  class BrowsingContext {
70
103
  constructor(driver) {
71
104
  this._driver = driver
@@ -78,11 +111,19 @@ class BrowsingContext {
78
111
  return this._id
79
112
  }
80
113
 
81
- async init({ browsingContextId, type, referenceContext }) {
114
+ async init({ browsingContextId = undefined, type = undefined, createParameters = undefined }) {
82
115
  if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
83
116
  throw Error('WebDriver instance must support BiDi protocol')
84
117
  }
85
118
 
119
+ if (browsingContextId === undefined && type === undefined && createParameters === undefined) {
120
+ throw Error('Either BrowsingContextId or Type or CreateParameters must be provided')
121
+ }
122
+
123
+ if (type === undefined && createParameters !== undefined) {
124
+ throw Error('Type must be provided with CreateParameters')
125
+ }
126
+
86
127
  if (type !== undefined && !['window', 'tab'].includes(type)) {
87
128
  throw Error(`Valid types are 'window' & 'tab'. Received: ${type}`)
88
129
  }
@@ -90,22 +131,33 @@ class BrowsingContext {
90
131
  this.bidi = await this._driver.getBidi()
91
132
  this._id =
92
133
  browsingContextId === undefined
93
- ? (await this.create(type, referenceContext))['result']['context']
134
+ ? (await this.create(type, createParameters))['result']['context']
94
135
  : browsingContextId
95
136
  }
96
137
 
97
138
  /**
98
- * Creates a browsing context for the given type and referenceContext
139
+ * Creates a browsing context for the given type with the given parameters
99
140
  */
100
- async create(type, referenceContext) {
141
+ async create(type, createParameters = undefined) {
142
+ if (createParameters !== undefined && (!createParameters) instanceof CreateContextParameters) {
143
+ throw Error(`Pass in the instance of CreateContextParameters. Received: ${createParameters}`)
144
+ }
145
+
146
+ let parameters = new Map()
147
+ parameters.set('type', type)
148
+
149
+ if (createParameters !== undefined) {
150
+ createParameters.asMap().forEach((value, key) => {
151
+ parameters.set(key, value)
152
+ })
153
+ }
154
+
101
155
  const params = {
102
156
  method: 'browsingContext.create',
103
- params: {
104
- type: type,
105
- referenceContext: referenceContext,
106
- },
157
+ params: Object.fromEntries(parameters),
107
158
  }
108
- return await this.bidi.send(params)
159
+ const res = await this.bidi.send(params)
160
+ return res
109
161
  }
110
162
 
111
163
  /**
@@ -153,6 +205,27 @@ class BrowsingContext {
153
205
  return new BrowsingContextInfo(result['context'], result['url'], result['children'], result['parent'])
154
206
  }
155
207
 
208
+ /**
209
+ * @returns {Promise<Array<BrowsingContextInfo>>} A Promise that resolves to an array of BrowsingContextInfo objects representing the top-level browsing contexts.
210
+ */
211
+ async getTopLevelContexts() {
212
+ const params = {
213
+ method: 'browsingContext.getTree',
214
+ params: {},
215
+ }
216
+
217
+ let result = await this.bidi.send(params)
218
+ if ('error' in result) {
219
+ throw Error(result['error'])
220
+ }
221
+
222
+ const contexts = result['result']['contexts']
223
+ const browsingContexts = contexts.map((context) => {
224
+ return new BrowsingContextInfo(context['id'], context['url'], context['children'], context['parent'])
225
+ })
226
+ return browsingContexts
227
+ }
228
+
156
229
  /**
157
230
  * Closes the browsing context
158
231
  * @returns {Promise<void>}
@@ -203,12 +276,34 @@ class BrowsingContext {
203
276
  return new PrintResult(response.result.data)
204
277
  }
205
278
 
206
- async captureScreenshot() {
279
+ /**
280
+ * Captures a screenshot of the browsing context.
281
+ *
282
+ * @param {CaptureScreenshotParameters|undefined} [captureScreenshotParameters] - Optional parameters for capturing the screenshot.
283
+ * @returns {Promise<string>} - A promise that resolves to the base64-encoded string representation of the captured screenshot.
284
+ * @throws {InvalidArgumentError} - If the provided captureScreenshotParameters is not an instance of CaptureScreenshotParameters.
285
+ */
286
+ async captureScreenshot(captureScreenshotParameters = undefined) {
287
+ if (
288
+ captureScreenshotParameters !== undefined &&
289
+ !(captureScreenshotParameters instanceof CaptureScreenshotParameters)
290
+ ) {
291
+ throw new InvalidArgumentError(
292
+ `Pass in a CaptureScreenshotParameters object. Received: ${captureScreenshotParameters}`,
293
+ )
294
+ }
295
+
296
+ const screenshotParams = new Map()
297
+ screenshotParams.set('context', this._id)
298
+ if (captureScreenshotParameters !== undefined) {
299
+ captureScreenshotParameters.asMap().forEach((value, key) => {
300
+ screenshotParams.set(key, value)
301
+ })
302
+ }
303
+
207
304
  let params = {
208
305
  method: 'browsingContext.captureScreenshot',
209
- params: {
210
- context: this._id,
211
- },
306
+ params: Object.fromEntries(screenshotParams),
212
307
  }
213
308
 
214
309
  const response = await this.bidi.send(params)
@@ -231,15 +326,18 @@ class BrowsingContext {
231
326
  },
232
327
  }
233
328
 
234
- console.log(JSON.stringify(params))
235
-
236
329
  const response = await this.bidi.send(params)
237
- console.log(JSON.stringify(response))
238
330
  this.checkErrorInScreenshot(response)
239
331
  return response['result']['data']
240
332
  }
241
333
 
242
- async captureElementScreenshot(sharedId, handle = undefined, scrollIntoView = undefined) {
334
+ /**
335
+ * Captures a screenshot of a specific element within the browsing context.
336
+ * @param {string} sharedId - The shared ID of the element to capture.
337
+ * @param {string} [handle] - The handle of the element to capture (optional).
338
+ * @returns {Promise<string>} A promise that resolves to the base64-encoded screenshot data.
339
+ */
340
+ async captureElementScreenshot(sharedId, handle = undefined) {
243
341
  let params = {
244
342
  method: 'browsingContext.captureScreenshot',
245
343
  params: {
@@ -250,7 +348,6 @@ class BrowsingContext {
250
348
  sharedId: sharedId,
251
349
  handle: handle,
252
350
  },
253
- scrollIntoView: scrollIntoView,
254
351
  },
255
352
  },
256
353
  }
@@ -274,6 +371,11 @@ class BrowsingContext {
274
371
  }
275
372
  }
276
373
 
374
+ /**
375
+ * Activates and focuses the top-level browsing context.
376
+ * @returns {Promise<void>} A promise that resolves when the browsing context is activated.
377
+ * @throws {Error} If there is an error while activating the browsing context.
378
+ */
277
379
  async activate() {
278
380
  const params = {
279
381
  method: 'browsingContext.activate',
@@ -288,6 +390,13 @@ class BrowsingContext {
288
390
  }
289
391
  }
290
392
 
393
+ /**
394
+ * Handles a user prompt in the browsing context.
395
+ *
396
+ * @param {boolean} [accept] - Optional. Indicates whether to accept or dismiss the prompt.
397
+ * @param {string} [userText] - Optional. The text to enter.
398
+ * @throws {Error} If an error occurs while handling the user prompt.
399
+ */
291
400
  async handleUserPrompt(accept = undefined, userText = undefined) {
292
401
  const params = {
293
402
  method: 'browsingContext.handleUserPrompt',
@@ -304,6 +413,15 @@ class BrowsingContext {
304
413
  }
305
414
  }
306
415
 
416
+ /**
417
+ * Reloads the current browsing context.
418
+ *
419
+ * @param {boolean} [ignoreCache] - Whether to ignore the cache when reloading.
420
+ * @param {string} [readinessState] - The readiness state to wait for before returning.
421
+ * Valid readiness states are 'none', 'interactive', and 'complete'.
422
+ * @returns {Promise<NavigateResult>} - A promise that resolves to the result of the reload operation.
423
+ * @throws {Error} - If an invalid readiness state is provided.
424
+ */
307
425
  async reload(ignoreCache = undefined, readinessState = undefined) {
308
426
  if (readinessState !== undefined && !['none', 'interactive', 'complete'].includes(readinessState)) {
309
427
  throw Error(`Valid readiness states are 'none', 'interactive' & 'complete'. Received: ${readinessState}`)
@@ -322,6 +440,13 @@ class BrowsingContext {
322
440
  return new NavigateResult(navigateResult['url'], navigateResult['navigation'])
323
441
  }
324
442
 
443
+ /**
444
+ * Sets the viewport size and device pixel ratio for the browsing context.
445
+ * @param {number} width - The width of the viewport.
446
+ * @param {number} height - The height of the viewport.
447
+ * @param {number} [devicePixelRatio] - The device pixel ratio (optional)
448
+ * @throws {Error} If an error occurs while setting the viewport.
449
+ */
325
450
  async setViewport(width, height, devicePixelRatio = undefined) {
326
451
  const params = {
327
452
  method: 'browsingContext.setViewport',
@@ -337,6 +462,12 @@ class BrowsingContext {
337
462
  }
338
463
  }
339
464
 
465
+ /**
466
+ * Traverses the browsing context history by a given delta.
467
+ *
468
+ * @param {number} delta - The delta value to traverse the history. A positive value moves forward, while a negative value moves backward.
469
+ * @returns {Promise<void>} - A promise that resolves when the history traversal is complete.
470
+ */
340
471
  async traverseHistory(delta) {
341
472
  const params = {
342
473
  method: 'browsingContext.traverseHistory',
@@ -348,18 +479,39 @@ class BrowsingContext {
348
479
  await this.bidi.send(params)
349
480
  }
350
481
 
482
+ /**
483
+ * Moves the browsing context forward by one step in the history.
484
+ * @returns {Promise<void>} A promise that resolves when the browsing context has moved forward.
485
+ */
351
486
  async forward() {
352
487
  await this.traverseHistory(1)
353
488
  }
354
489
 
490
+ /**
491
+ * Navigates the browsing context to the previous page in the history.
492
+ * @returns {Promise<void>} A promise that resolves when the navigation is complete.
493
+ */
355
494
  async back() {
356
495
  await this.traverseHistory(-1)
357
496
  }
358
497
 
498
+ /**
499
+ * Locates nodes in the browsing context.
500
+ *
501
+ * @param {Locator} locator - The locator object used to locate the nodes.
502
+ * @param {number} [maxNodeCount] - The maximum number of nodes to locate (optional).
503
+ * @param {string} [sandbox] - The sandbox name for locating nodes (optional).
504
+ * @param {SerializationOptions} [serializationOptions] - The serialization options for locating nodes (optional).
505
+ * @param {ReferenceValue[]} [startNodes] - The array of start nodes for locating nodes (optional).
506
+ * @returns {Promise<RemoteValue[]>} - A promise that resolves to the arrays of located nodes.
507
+ * @throws {Error} - If the locator is not an instance of Locator.
508
+ * @throws {Error} - If the serializationOptions is provided but not an instance of SerializationOptions.
509
+ * @throws {Error} - If the startNodes is provided but not an array of ReferenceValue objects.
510
+ * @throws {Error} - If any of the startNodes is not an instance of ReferenceValue.
511
+ */
359
512
  async locateNodes(
360
513
  locator,
361
514
  maxNodeCount = undefined,
362
- ownership = undefined,
363
515
  sandbox = undefined,
364
516
  serializationOptions = undefined,
365
517
  startNodes = undefined,
@@ -372,10 +524,6 @@ class BrowsingContext {
372
524
  throw Error(`Pass in SerializationOptions object. Received: ${serializationOptions} `)
373
525
  }
374
526
 
375
- if (ownership !== undefined && !['root', 'none'].includes(ownership)) {
376
- throw Error(`Valid types are 'root' and 'none. Received: ${ownership}`)
377
- }
378
-
379
527
  if (startNodes !== undefined && !Array.isArray(startNodes)) {
380
528
  throw Error(`Pass in an array of ReferenceValue objects. Received: ${startNodes}`)
381
529
  }
@@ -394,7 +542,6 @@ class BrowsingContext {
394
542
  context: this._id,
395
543
  locator: Object.fromEntries(locator.toMap()),
396
544
  maxNodeCount: maxNodeCount,
397
- ownership: ownership,
398
545
  sandbox: sandbox,
399
546
  serializationOptions: serializationOptions,
400
547
  startNodes: startNodes,
@@ -415,14 +562,17 @@ class BrowsingContext {
415
562
  return remoteValues
416
563
  }
417
564
 
418
- async locateNode(
419
- locator,
420
- ownership = undefined,
421
- sandbox = undefined,
422
- serializationOptions = undefined,
423
- startNodes = undefined,
424
- ) {
425
- const elements = await this.locateNodes(locator, 1, ownership, sandbox, serializationOptions, startNodes)
565
+ /**
566
+ * Locates a single node in the browsing context.
567
+ *
568
+ * @param {Locator} locator - The locator used to find the node.
569
+ * @param {string} [sandbox] - The sandbox of the node (optional).
570
+ * @param {SerializationOptions} [serializationOptions] - The serialization options for the node (optional).
571
+ * @param {Array} [startNodes] - The starting nodes for the search (optional).
572
+ * @returns {Promise<RemoteValue>} - A promise that resolves to the located node.
573
+ */
574
+ async locateNode(locator, sandbox = undefined, serializationOptions = undefined, startNodes = undefined) {
575
+ const elements = await this.locateNodes(locator, 1, sandbox, serializationOptions, startNodes)
426
576
  return elements[0]
427
577
  }
428
578
 
@@ -442,26 +592,44 @@ class BrowsingContext {
442
592
  }
443
593
  }
444
594
 
595
+ /**
596
+ * Represents the result of a navigation operation.
597
+ */
445
598
  class NavigateResult {
446
599
  constructor(url, navigationId) {
447
600
  this._url = url
448
601
  this._navigationId = navigationId
449
602
  }
450
603
 
604
+ /**
605
+ * Gets the URL of the navigated page.
606
+ * @returns {string} The URL of the navigated page.
607
+ */
451
608
  get url() {
452
609
  return this._url
453
610
  }
454
611
 
612
+ /**
613
+ * Gets the ID of the navigation operation.
614
+ * @returns {number} The ID of the navigation operation.
615
+ */
455
616
  get navigationId() {
456
617
  return this._navigationId
457
618
  }
458
619
  }
459
620
 
621
+ /**
622
+ * Represents a print result.
623
+ */
460
624
  class PrintResult {
461
625
  constructor(data) {
462
626
  this._data = data
463
627
  }
464
628
 
629
+ /**
630
+ * Gets the data associated with the print result.
631
+ * @returns {any} The data associated with the print result.
632
+ */
465
633
  get data() {
466
634
  return this._data
467
635
  }
@@ -472,18 +640,17 @@ class PrintResult {
472
640
  * @param driver
473
641
  * @param browsingContextId The browsing context of current window/tab
474
642
  * @param type "window" or "tab"
475
- * @param referenceContext To get a browsing context for this reference if passed
643
+ * @param createParameters The parameters for creating a new browsing context
476
644
  * @returns {Promise<BrowsingContext>}
477
645
  */
478
- async function getBrowsingContextInstance(driver, { browsingContextId, type, referenceContext }) {
646
+ async function getBrowsingContextInstance(
647
+ driver,
648
+ { browsingContextId = undefined, type = undefined, createParameters = undefined },
649
+ ) {
479
650
  let instance = new BrowsingContext(driver)
480
- await instance.init({ browsingContextId, type, referenceContext })
651
+ await instance.init({ browsingContextId, type, createParameters })
481
652
  return instance
482
653
  }
483
654
 
484
- /**
485
- * API
486
- * @type {function(*, {*,*,*}): Promise<BrowsingContext>}
487
- */
488
655
  module.exports = getBrowsingContextInstance
489
656
  module.exports.Locator = Locator
@@ -17,6 +17,12 @@
17
17
 
18
18
  const { BrowsingContextInfo, NavigationInfo } = require('./browsingContextTypes')
19
19
 
20
+ /**
21
+ * Represents a browsing context related events.
22
+ * Described in https://w3c.github.io/webdriver-bidi/#module-contexts-events.
23
+ * While BrowsingContext class represents a browsing context lifecycle and related commands.
24
+ * This class is specific to listening to events. Events can be subscribed to multiple browsing contexts or all of them.
25
+ */
20
26
  class BrowsingContextInspector {
21
27
  constructor(driver, browsingContextIds) {
22
28
  this._driver = driver
@@ -27,34 +33,79 @@ class BrowsingContextInspector {
27
33
  this.bidi = await this._driver.getBidi()
28
34
  }
29
35
 
36
+ /**
37
+ * Subscribes to the 'browsingContext.contextCreated' event.
38
+ * @param {Function} callback - The callback function to handle the event.
39
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
40
+ */
30
41
  async onBrowsingContextCreated(callback) {
31
42
  await this.subscribeAndHandleEvent('browsingContext.contextCreated', callback)
32
43
  }
33
44
 
45
+ /**
46
+ * Subscribes to the 'browsingContext.contextDestroyed' event.
47
+ * @param {Function} callback - The callback function to handle the event.
48
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
49
+ */
34
50
  async onBrowsingContextDestroyed(callback) {
35
51
  await this.subscribeAndHandleEvent('browsingContext.contextDestroyed', callback)
36
52
  }
37
53
 
54
+ /**
55
+ * Subscribe to the 'browsingContext.navigationStarted' event.
56
+ * @param {Function} callback - The callback function to handle the event.
57
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
58
+ */
38
59
  async onNavigationStarted(callback) {
39
60
  await this.subscribeAndHandleEvent('browsingContext.navigationStarted', callback)
40
61
  }
41
62
 
63
+ /**
64
+ * Subscribes to the 'browsingContext.fragmentNavigated' event.
65
+ *
66
+ * @param {Function} callback - The callback function to handle the event.
67
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
68
+ */
42
69
  async onFragmentNavigated(callback) {
43
70
  await this.subscribeAndHandleEvent('browsingContext.fragmentNavigated', callback)
44
71
  }
45
72
 
73
+ /**
74
+ * Subscribes to the 'browsingContext.userPromptClosed' event.
75
+ *
76
+ * @param {Function} callback - The callback function to handle the event.
77
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
78
+ */
46
79
  async onUserPromptClosed(callback) {
47
80
  await this.subscribeAndHandleEvent('browsingContext.userPromptClosed', callback)
48
81
  }
49
82
 
83
+ /**
84
+ * Subscribes to the 'browsingContext.userPromptOpened' event.
85
+ *
86
+ * @param {Function} callback - The callback function to handle the event.
87
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
88
+ */
50
89
  async onUserPromptOpened(callback) {
51
90
  await this.subscribeAndHandleEvent('browsingContext.userPromptOpened', callback)
52
91
  }
53
92
 
93
+ /**
94
+ * Subscribes to the 'browsingContext.domContentLoaded' event.
95
+ *
96
+ * @param {Function} callback - The callback function to handle the event.
97
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
98
+ */
54
99
  async onDomContentLoaded(callback) {
55
100
  await this.subscribeAndHandleEvent('browsingContext.domContentLoaded', callback)
56
101
  }
57
102
 
103
+ /**
104
+ * Subscribes to the 'browsingContext.load' event.
105
+ *
106
+ * @param {Function} callback - The callback function to handle the event.
107
+ * @returns {Promise<void>} - A promise that resolves when the event is emitted.
108
+ */
58
109
  async onBrowsingContextLoaded(callback) {
59
110
  await this.subscribeAndHandleEvent('browsingContext.load', callback)
60
111
  }