Bug 1772484 - [marionette] Update JSDoc @throws entries for WebDriver commands. r=webdriver-reviewers,jdescottes

Differential Revision: https://phabricator.services.mozilla.com/D149266

remote/marionette/driver.js

@@ -640,11 +640,16 @@ GeckoDriver.prototype.getContext = function() {
  *
  * @throws {JavaScriptError}
  *     If an {@link Error} was thrown whilst evaluating the script.
+ * @throws {NoSuchElementError}
+ *     If an element that was passed as part of <var>args</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
  * @throws {ScriptTimeoutError}
  *     If the script was interrupted due to reaching the session's
  *     script timeout.
+ * @throws {StaleElementReferenceError}
+ *     If an element that was passed as part of <var>args</var> or that is
+ *     returned as result has gone stale.
  */
 GeckoDriver.prototype.executeScript = async function(cmd) {
   let { script, args } = cmd.parameters;
@@ -707,11 +712,16 @@ GeckoDriver.prototype.executeScript = async function(cmd) {
  *
  * @throws {JavaScriptError}
  *     If an Error was thrown whilst evaluating the script.
+ * @throws {NoSuchElementError}
+ *     If an element that was passed as part of <var>args</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
  * @throws {ScriptTimeoutError}
  *     If the script was interrupted due to reaching the session's
  *     script timeout.
+ * @throws {StaleElementReferenceError}
+ *     If an element that was passed as part of <var>args</var> or that is
+ *     returned as result has gone stale.
  */
 GeckoDriver.prototype.executeAsyncScript = async function(cmd) {
   let { script, args } = cmd.parameters;
@@ -1186,6 +1196,8 @@ GeckoDriver.prototype.setWindowRect = async function(cmd) {
  *     A boolean value which determines whether to focus
  *     the window. Defaults to true.
  *
+ * @throws {InvalidArgumentError}
+ *     If <var>handle</var> is not a string or <var>focus</var> not a boolean.
  * @throws {NoSuchWindowError}
  *     Top-level browsing context has been discarded.
  */
@@ -1319,8 +1331,12 @@ GeckoDriver.prototype.switchToParentFrame = async function() {
  *     The index of the frame to switch to.
  *     If both element and id are not defined, switch to top-level frame.
  *
+ * @throws {NoSuchElementError}
+ *     If element represented by reference <var>element</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>element</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1399,8 +1415,12 @@ GeckoDriver.prototype.singleTap = async function(cmd) {
  * @param {Array.<?>} actions
  *     Array of objects that each represent an action sequence.
  *
+ * @throws {NoSuchElementError}
+ *     If an element that is used as part of the action chain is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If an element that is used as part of the action chain has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  * @throws {UnsupportedOperationError}
@@ -1438,13 +1458,19 @@ GeckoDriver.prototype.releaseActions = async function() {
 /**
  * Find an element using the indicated search strategy.
  *
+ * @param {string=} element
+ *     Web element reference ID to the element that will be used as start node.
  * @param {string} using
  *     Indicates which search method to use.
  * @param {string} value
  *     Value the client is looking for.
  *
+ * @throws {NoSuchElementError}
+ *     If element represented by reference <var>element</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>element</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1477,13 +1503,21 @@ GeckoDriver.prototype.findElement = async function(cmd) {
 /**
  * Find elements using the indicated search strategy.
  *
+ * @param {string=} element
+ *     Web element reference ID to the element that will be used as start node.
  * @param {string} using
  *     Indicates which search method to use.
  * @param {string} value
  *     Value the client is looking for.
  *
+ * @throws {NoSuchElementError}
+ *     If element represented by reference <var>element</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>element</var> has gone stale.
+ * @throws {UnexpectedAlertOpenError}
+ *     A modal dialog is open, blocking this operation.
  */
 GeckoDriver.prototype.findElements = async function(cmd) {
   const { element: el, using, value } = cmd.parameters;
@@ -1527,6 +1561,8 @@ GeckoDriver.prototype.findElements = async function(cmd) {
  *     Element does not have a shadow root attached.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  * @throws {UnsupportedOperationError}
@@ -1562,7 +1598,7 @@ GeckoDriver.prototype.getShadowRoot = async function(cmd) {
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  * @throws {UnsupportedOperationError}
- *     Not available in current context.
+ *     Not available in chrome context.
  */
 GeckoDriver.prototype.getActiveElement = async function() {
   lazy.assert.content(this.context);
@@ -1584,6 +1620,8 @@ GeckoDriver.prototype.getActiveElement = async function() {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1632,6 +1670,8 @@ GeckoDriver.prototype.clickElement = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1663,6 +1703,8 @@ GeckoDriver.prototype.getElementAttribute = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1693,6 +1735,8 @@ GeckoDriver.prototype.getElementProperty = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1721,6 +1765,8 @@ GeckoDriver.prototype.getElementText = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1782,6 +1828,8 @@ GeckoDriver.prototype.isElementDisplayed = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1811,6 +1859,8 @@ GeckoDriver.prototype.getElementValueOfCssProperty = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1865,6 +1915,8 @@ GeckoDriver.prototype.isElementSelected = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1887,11 +1939,13 @@ GeckoDriver.prototype.getElementRect = async function(cmd) {
  *     Value to send to the element.
  *
  * @throws {InvalidArgumentError}
- *     If `id` or `text` are not strings.
+ *     If <var>id</var> or <var>text</var> are not strings.
  * @throws {NoSuchElementError}
- *     If element represented by reference `id` is unknown.
+ *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1922,6 +1976,8 @@ GeckoDriver.prototype.sendKeysToElement = async function(cmd) {
  *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
  *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  * @throws {UnexpectedAlertOpenError}
  *     A modal dialog is open, blocking this operation.
  */
@@ -1939,7 +1995,7 @@ GeckoDriver.prototype.clearElement = async function(cmd) {
  * Add a single cookie to the cookie store associated with the active
  * document's address.
  *
- * @param {Map.<string, (string|number|boolean)> cookie
+ * @param {Map.<string, (string|number|boolean)>} cookie
  *     Cookie object.
  *
  * @throws {InvalidCookieDomainError}
@@ -2055,6 +2111,8 @@ GeckoDriver.prototype.deleteCookie = async function(cmd) {
  *
  * @throws {NoSuchWindowError}
  *     Top-level browsing context has been discarded.
+ * @throws {UnexpectedAlertOpenError}
+ *     A modal dialog is open, blocking this operation.
  */
 GeckoDriver.prototype.newWindow = async function(cmd) {
   lazy.assert.open(this.getBrowsingContext({ top: true }));
@@ -2262,8 +2320,12 @@ GeckoDriver.prototype.deleteSession = function() {
  *     string.  If <var>hash</var> is true, hex digest of the SHA-256
  *     hash of the Base64 encoded string.
  *
+ * @throws {NoSuchElementError}
+ *     If element represented by reference <var>id</var> is unknown.
  * @throws {NoSuchWindowError}
- *     Top-level browsing context has been discarded.
+ *     Browsing context has been discarded.
+ * @throws {StaleElementReferenceError}
+ *     If element represented by reference <var>id</var> has gone stale.
  */
 GeckoDriver.prototype.takeScreenshot = async function(cmd) {
   lazy.assert.open(this.getBrowsingContext({ top: true }));
@@ -2506,6 +2568,8 @@ GeckoDriver.prototype.fullscreenWindow = async function() {
  * Dismisses a currently displayed tab modal, or returns no such alert if
  * no modal is displayed.
  *
+ * @throws {NoSuchAlertError}
+ *     If there is no current user prompt.
  * @throws {NoSuchWindowError}
  *     Top-level browsing context has been discarded.
  */
@@ -2525,6 +2589,8 @@ GeckoDriver.prototype.dismissDialog = async function() {
  * Accepts a currently displayed tab modal, or returns no such alert if
  * no modal is displayed.
  *
+ * @throws {NoSuchAlertError}
+ *     If there is no current user prompt.
  * @throws {NoSuchWindowError}
  *     Top-level browsing context has been discarded.
  */
@@ -2544,6 +2610,8 @@ GeckoDriver.prototype.acceptDialog = async function() {
  * Returns the message shown in a currently displayed modal, or returns
  * a no such alert error if no modal is currently displayed.
  *
+ * @throws {NoSuchAlertError}
+ *     If there is no current user prompt.
  * @throws {NoSuchWindowError}
  *     Top-level browsing context has been discarded.
  */
@@ -2977,6 +3045,10 @@ GeckoDriver.prototype.teardownReftest = function() {
  *
  * @throws {NoSuchWindowError}
  *     Top-level browsing context has been discarded.
+ * @throws {UnexpectedAlertOpenError}
+ *     A modal dialog is open, blocking this operation.
+ * @throws {UnsupportedOperationError}
+ *     Not available in chrome context.
  */
 GeckoDriver.prototype.print = async function(cmd) {
   lazy.assert.content(this.context);