1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Contains several classes for handling commands.
20
 */
21

22
'use strict'
23

24
/**
25
 * Describes a command to execute.
26
 * @final
27
 */
28
class Command {
29
  /** @param {string} name The name of this command. */
30
  constructor(name) {
31
    /** @private {string} */
32
    this.name_ = name
33

34
    /** @private {!Object<*>} */
35
    this.parameters_ = {}
36
  }
37

38
  /** @return {string} This command's name. */
39
  getName() {
40
    return this.name_
41
  }
42

43
  /**
44
   * Sets a parameter to send with this command.
45
   * @param {string} name The parameter name.
46
   * @param {*} value The parameter value.
47
   * @return {!Command} A self reference.
48
   */
49
  setParameter(name, value) {
50
    this.parameters_[name] = value
51
    return this
52
  }
53

54
  /**
55
   * Sets the parameters for this command.
56
   * @param {!Object<*>} parameters The command parameters.
57
   * @return {!Command} A self reference.
58
   */
59
  setParameters(parameters) {
60
    this.parameters_ = parameters
61
    return this
62
  }
63

64
  /**
65
   * Returns a named command parameter.
66
   * @param {string} key The parameter key to look up.
67
   * @return {*} The parameter value, or undefined if it has not been set.
68
   */
69
  getParameter(key) {
70
    return this.parameters_[key]
71
  }
72

73
  /**
74
   * @return {!Object<*>} The parameters to send with this command.
75
   */
76
  getParameters() {
77
    return this.parameters_
78
  }
79
}
80

81
/**
82
 * Enumeration of predefined names command names that all command processors
83
 * will support.
84
 * @enum {string}
85
 */
86
const Name = {
87
  GET_SERVER_STATUS: 'getStatus',
88

89
  NEW_SESSION: 'newSession',
90
  GET_SESSIONS: 'getSessions',
91

92
  CLOSE: 'close',
93
  QUIT: 'quit',
94

95
  GET_CURRENT_URL: 'getCurrentUrl',
96
  GET: 'get',
97
  GO_BACK: 'goBack',
98
  GO_FORWARD: 'goForward',
99
  REFRESH: 'refresh',
100

101
  ADD_COOKIE: 'addCookie',
102
  GET_COOKIE: 'getCookie',
103
  GET_ALL_COOKIES: 'getCookies',
104
  DELETE_COOKIE: 'deleteCookie',
105
  DELETE_ALL_COOKIES: 'deleteAllCookies',
106

107
  GET_ACTIVE_ELEMENT: 'getActiveElement',
108
  FIND_ELEMENT: 'findElement',
109
  FIND_ELEMENTS: 'findElements',
110
  FIND_ELEMENTS_RELATIVE: 'findElementsRelative',
111
  FIND_CHILD_ELEMENT: 'findChildElement',
112
  FIND_CHILD_ELEMENTS: 'findChildElements',
113

114
  CLEAR_ELEMENT: 'clearElement',
115
  CLICK_ELEMENT: 'clickElement',
116
  SEND_KEYS_TO_ELEMENT: 'sendKeysToElement',
117

118
  GET_CURRENT_WINDOW_HANDLE: 'getCurrentWindowHandle',
119
  GET_WINDOW_HANDLES: 'getWindowHandles',
120
  GET_WINDOW_RECT: 'getWindowRect',
121
  SET_WINDOW_RECT: 'setWindowRect',
122
  MAXIMIZE_WINDOW: 'maximizeWindow',
123
  MINIMIZE_WINDOW: 'minimizeWindow',
124
  FULLSCREEN_WINDOW: 'fullscreenWindow',
125

126
  SWITCH_TO_WINDOW: 'switchToWindow',
127
  SWITCH_TO_NEW_WINDOW: 'newWindow',
128
  SWITCH_TO_FRAME: 'switchToFrame',
129
  SWITCH_TO_FRAME_PARENT: 'switchToFrameParent',
130
  GET_PAGE_SOURCE: 'getPageSource',
131
  GET_TITLE: 'getTitle',
132

133
  EXECUTE_SCRIPT: 'executeScript',
134
  EXECUTE_ASYNC_SCRIPT: 'executeAsyncScript',
135

136
  GET_ELEMENT_TEXT: 'getElementText',
137
  GET_COMPUTED_ROLE: 'getAriaRole',
138
  GET_COMPUTED_LABEL: 'getAccessibleName',
139
  GET_ELEMENT_TAG_NAME: 'getElementTagName',
140
  IS_ELEMENT_SELECTED: 'isElementSelected',
141
  IS_ELEMENT_ENABLED: 'isElementEnabled',
142
  IS_ELEMENT_DISPLAYED: 'isElementDisplayed',
143
  GET_ELEMENT_RECT: 'getElementRect',
144
  GET_ELEMENT_ATTRIBUTE: 'getElementAttribute',
145
  GET_DOM_ATTRIBUTE: 'getDomAttribute',
146
  GET_ELEMENT_VALUE_OF_CSS_PROPERTY: 'getElementValueOfCssProperty',
147
  GET_ELEMENT_PROPERTY: 'getElementProperty',
148

149
  SCREENSHOT: 'screenshot',
150
  TAKE_ELEMENT_SCREENSHOT: 'takeElementScreenshot',
151

152
  PRINT_PAGE: 'printPage',
153

154
  GET_TIMEOUT: 'getTimeout',
155
  SET_TIMEOUT: 'setTimeout',
156

157
  ACCEPT_ALERT: 'acceptAlert',
158
  DISMISS_ALERT: 'dismissAlert',
159
  GET_ALERT_TEXT: 'getAlertText',
160
  SET_ALERT_TEXT: 'setAlertValue',
161

162
  // Shadow DOM Commands
163
  GET_SHADOW_ROOT: 'getShadowRoot',
164
  FIND_ELEMENT_FROM_SHADOWROOT: 'findElementFromShadowRoot',
165
  FIND_ELEMENTS_FROM_SHADOWROOT: 'findElementsFromShadowRoot',
166

167
  // Virtual Authenticator Commands
168
  ADD_VIRTUAL_AUTHENTICATOR: 'addVirtualAuthenticator',
169
  REMOVE_VIRTUAL_AUTHENTICATOR: 'removeVirtualAuthenticator',
170
  ADD_CREDENTIAL: 'addCredential',
171
  GET_CREDENTIALS: 'getCredentials',
172
  REMOVE_CREDENTIAL: 'removeCredential',
173
  REMOVE_ALL_CREDENTIALS: 'removeAllCredentials',
174
  SET_USER_VERIFIED: 'setUserVerified',
175

176
  GET_AVAILABLE_LOG_TYPES: 'getAvailableLogTypes',
177
  GET_LOG: 'getLog',
178

179
  // Non-standard commands used by the standalone Selenium server.
180
  UPLOAD_FILE: 'uploadFile',
181

182
  ACTIONS: 'actions',
183
  CLEAR_ACTIONS: 'clearActions',
184

185
  GET_DOWNLOADABLE_FILES: 'getDownloadableFiles',
186
  DOWNLOAD_FILE: 'downloadFile',
187
  DELETE_DOWNLOADABLE_FILES: 'deleteDownloadableFiles',
188

189
  // Federated Credential Management API
190
  // https://www.w3.org/TR/fedcm/#automation
191
  CANCEL_DIALOG: 'cancelDialog',
192
  SELECT_ACCOUNT: 'selectAccount',
193
  GET_ACCOUNTS: 'getAccounts',
194
  GET_FEDCM_TITLE: 'getFedCmTitle',
195
  GET_FEDCM_DIALOG_TYPE: 'getFedCmDialogType',
196
  SET_DELAY_ENABLED: 'setDelayEnabled',
197
  RESET_COOLDOWN: 'resetCooldown',
198
  CLICK_DIALOG_BUTTON: 'clickdialogbutton',
199
}
200

201
/**
202
 * Handles the execution of WebDriver {@link Command commands}.
203
 * @record
204
 */
205
class Executor {
206
  /**
207
   * Executes the given {@code command}. If there is an error executing the
208
   * command, the provided callback will be invoked with the offending error.
209
   * Otherwise, the callback will be invoked with a null Error and non-null
210
   * response object.
211
   *
212
   * @param {!Command} command The command to execute.
213
   * @return {!Promise<?>} A promise that will be fulfilled with the command
214
   *     result.
215
   */
216
  execute(command) {} // eslint-disable-line
217
}
218

219
// PUBLIC API
220

221
module.exports = {
222
  Command,
223
  Name,
224
  Executor,
225
}
226

227