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 Defines a {@linkplain Driver WebDriver} client for
20
 * Microsoft's Edge web browser. Edge (Chromium) is supported and support
21
 * for Edge Legacy (EdgeHTML) as part of https://github.com/SeleniumHQ/selenium/issues/9166.
22
 * Before using this module, you must download and install the correct
23
 * [WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) server.
24
 *
25
 * Ensure that the msedgedriver (Chromium)
26
 * is on your [PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29).
27
 *
28
 * You may use {@link Options} to specify whether Edge Chromium options should be used:
29

30
 *     const edge = require('selenium-webdriver/edge');
31
 *     const options = new edge.Options();
32

33
 * There are three primary classes exported by this module:
34
 *
35
 * 1. {@linkplain ServiceBuilder}: configures the
36
 *     {@link ./remote.DriverService remote.DriverService}
37
 *     that manages the [WebDriver] child process.
38
 *
39
 * 2. {@linkplain Options}: defines configuration options for each new
40
 *     WebDriver session, such as which
41
 *     {@linkplain Options#setProxy proxy} to use when starting the browser.
42
 *
43
 * 3. {@linkplain Driver}: the WebDriver client; each new instance will control
44
 *     a unique browser session.
45
 *
46
 * __Customizing the WebDriver Server__ <a id="custom-server"></a>
47
 *
48
 * By default, every MicrosoftEdge session will use a single driver service,
49
 * which is started the first time a {@link Driver} instance is created and
50
 * terminated when this process exits. The default service will inherit its
51
 * environment from the current process.
52
 * You may obtain a handle to this default service using
53
 * {@link #getDefaultService getDefaultService()} and change its configuration
54
 * with {@link #setDefaultService setDefaultService()}.
55
 *
56
 * You may also create a {@link Driver} with its own driver service. This is
57
 * useful if you need to capture the server's log output for a specific session:
58
 *
59
 *     const edge = require('selenium-webdriver/edge');
60
 *
61
 *     const service = new edge.ServiceBuilder()
62
 *         .setPort(55555)
63
 *         .build();
64
 *
65
 *     let options = new edge.Options();
66
 *     // configure browser options ...
67
 *
68
 *     let driver = edge.Driver.createSession(options, service);
69
 *
70
 * Users should only instantiate the {@link Driver} class directly when they
71
 * need a custom driver service configuration (as shown above). For normal
72
 * operation, users should start msedgedriver using the
73
 * {@link ./builder.Builder selenium-webdriver.Builder}.
74
 *
75
 * [WebDriver (Chromium)]: https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium
76
 *
77
 * @module selenium-webdriver/edge
78
 */
79

80
'use strict'
81

82
const { Browser } = require('./lib/capabilities')
83
const chromium = require('./chromium')
84
const EDGE_CAPABILITY_KEY = 'ms:edgeOptions'
85

86
/** @type {remote.DriverService} */
87

88
/**
89
 * Creates {@link selenium-webdriver/remote.DriverService} instances that manage
90
 * a [MSEdgeDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/)
91
 * server in a child process.
92
 */
93
class ServiceBuilder extends chromium.ServiceBuilder {
94
  /**
95
   * @param {string=} opt_exe Path to the server executable to use. If omitted,
96
   *     the builder will attempt to locate the msedgedriver on the current
97
   *     PATH.
98
   * @throws {Error} If provided executable does not exist, or the msedgedriver
99
   *     cannot be found on the PATH.
100
   */
101
  constructor(opt_exe) {
102
    super(opt_exe)
103
    this.setLoopback(true)
104
  }
105
}
106

107
/**
108
 * Class for managing edge chromium specific options.
109
 */
110
class Options extends chromium.Options {
111
  /**
112
   * Sets the path to the edge binary to use
113
   *
114
   * The binary path be absolute or relative to the msedgedriver server
115
   * executable, but it must exist on the machine that will launch edge chromium.
116
   *
117
   * @param {string} path The path to the msedgedriver binary to use.
118
   * @return {!Options} A self reference.
119
   */
120
  setEdgeChromiumBinaryPath(path) {
121
    return this.setBinaryPath(path)
122
  }
123

124
  /**
125
   * Changes the browser name to 'webview2' to enable
126
   * <a href="https://learn.microsoft.com/en-us/microsoft-edge/webview2/how-to/webdriver">
127
   *   test automation of WebView2 apps with Microsoft Edge WebDriver
128
   * </a>
129
   *
130
   * @param {boolean} enable  flag to enable or disable the 'webview2' usage
131
   */
132
  useWebView(enable) {
133
    const browserName = enable ? 'webview2' : Browser.EDGE
134
    return this.setBrowserName(browserName)
135
  }
136
}
137

138
/**
139
 * Creates a new WebDriver client for Microsoft's Edge.
140
 */
141
class Driver extends chromium.Driver {
142
  /**
143
   * Creates a new browser session for Microsoft's Edge browser.
144
   *
145
   * @param {(Capabilities|Options)=} opt_config The configuration options.
146
   * @param {remote.DriverService=} opt_serviceExecutor The service to use; will create
147
   *     a new Legacy or Chromium service based on {@linkplain Options} by default.
148
   * @return {!Driver} A new driver instance.
149
   */
150
  static createSession(opt_config, opt_serviceExecutor) {
151
    let caps = opt_config || new Options()
152
    return /** @type {!Driver} */ (super.createSession(caps, opt_serviceExecutor, 'ms', EDGE_CAPABILITY_KEY))
153
  }
154

155
  /**
156
   * returns new instance of edge driver service
157
   * @returns {remote.DriverService}
158
   */
159
  static getDefaultService() {
160
    return new ServiceBuilder().build()
161
  }
162

163
  /**
164
   * This function is a no-op as file detectors are not supported by this
165
   * implementation.
166
   * @override
167
   */
168
  setFileDetector() {}
169
}
170

171
Options.prototype.BROWSER_NAME_VALUE = Browser.EDGE
172
Options.prototype.CAPABILITY_KEY = EDGE_CAPABILITY_KEY
173

174
// PUBLIC API
175

176
module.exports = {
177
  Driver,
178
  Options,
179
  ServiceBuilder,
180
}
181

182