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 functions for configuring a webdriver proxy:
|
20 | *
|
21 | * const proxy = require('selenium-webdriver/proxy');
|
22 | * const {Capabilities} = require('selenium-webdriver');
|
23 | *
|
24 | * let capabilities = new Capabilities();
|
25 | * capabilities.setProxy(proxy.manual({http: 'host:1234'});
|
26 | */
|
27 |
|
28 |
|
29 |
|
30 | /**
|
31 | * Supported {@linkplain Config proxy configuration} types.
|
32 | *
|
33 | * @enum {string}
|
34 | */
|
35 | const Type = {
|
36 | AUTODETECT: 'autodetect',
|
37 | DIRECT: 'direct',
|
38 | MANUAL: 'manual',
|
39 | PAC: 'pac',
|
40 | SYSTEM: 'system',
|
41 | }
|
42 |
|
43 | /**
|
44 | * Describes how a proxy should be configured for a WebDriver session.
|
45 | * @record
|
46 | */
|
47 | function Config() {}
|
48 |
|
49 | /**
|
50 | * The proxy type.
|
51 | * @type {Type}
|
52 | */
|
53 | Config.prototype.proxyType
|
54 |
|
55 | /**
|
56 | * Describes how to configure a PAC proxy.
|
57 | * @record
|
58 | * @extends {Config}
|
59 | */
|
60 | function PacConfig() {}
|
61 |
|
62 | /**
|
63 | * URL for the PAC file to use.
|
64 | *
|
65 | * @type {string}
|
66 | */
|
67 | PacConfig.prototype.proxyAutoconfigUrl
|
68 |
|
69 | /**
|
70 | * Record object that defines a manual proxy configuration. Manual
|
71 | * configurations can be easily created using either the
|
72 | * {@link ./proxy.manual proxy.manual()} or {@link ./proxy.socks proxy.socks()}
|
73 | * factory method.
|
74 | *
|
75 | * @record
|
76 | * @extends {Config}
|
77 | */
|
78 | function ManualConfig() {}
|
79 |
|
80 | /**
|
81 | * The proxy host for FTP requests.
|
82 | *
|
83 | * @type {(string|undefined)}
|
84 | */
|
85 | ManualConfig.prototype.ftpProxy
|
86 |
|
87 | /**
|
88 | * The proxy host for HTTP requests.
|
89 | *
|
90 | * @type {(string|undefined)}
|
91 | */
|
92 | ManualConfig.prototype.httpProxy
|
93 |
|
94 | /**
|
95 | * An array of hosts which should bypass all proxies.
|
96 | *
|
97 | * @type {(Array<string>|undefined)}
|
98 | */
|
99 | ManualConfig.prototype.noProxy
|
100 |
|
101 | /**
|
102 | * The proxy host for HTTPS requests.
|
103 | *
|
104 | * @type {(string|undefined)}
|
105 | */
|
106 | ManualConfig.prototype.sslProxy
|
107 |
|
108 | /**
|
109 | * Defines the host and port for the SOCKS proxy to use.
|
110 | *
|
111 | * @type {(number|undefined)}
|
112 | */
|
113 | ManualConfig.prototype.socksProxy
|
114 |
|
115 | /**
|
116 | * Defines the SOCKS proxy version. Must be a number in the range [0, 255].
|
117 | *
|
118 | * @type {(number|undefined)}
|
119 | */
|
120 | ManualConfig.prototype.socksVersion
|
121 |
|
122 | // PUBLIC API
|
123 |
|
124 | /** @const */ exports.Config = Config
|
125 | /** @const */ exports.ManualConfig = ManualConfig
|
126 | /** @const */ exports.PacConfig = PacConfig
|
127 | /** @const */ exports.Type = Type
|
128 |
|
129 | /**
|
130 | * Configures WebDriver to bypass all browser proxies.
|
131 | * @return {!Config} A new proxy configuration object.
|
132 | */
|
133 | exports.direct = function () {
|
134 | return { proxyType: Type.DIRECT }
|
135 | }
|
136 |
|
137 | /**
|
138 | * Manually configures the browser proxy. The following options are
|
139 | * supported:
|
140 | *
|
141 | * - `ftp`: Proxy host to use for FTP requests
|
142 | * - `http`: Proxy host to use for HTTP requests
|
143 | * - `https`: Proxy host to use for HTTPS requests
|
144 | * - `bypass`: A list of hosts requests should directly connect to,
|
145 | * bypassing any other proxies for that request. May be specified as a
|
146 | * comma separated string, or a list of strings.
|
147 | *
|
148 | * Behavior is undefined for FTP, HTTP, and HTTPS requests if the
|
149 | * corresponding key is omitted from the configuration options.
|
150 | *
|
151 | * @param {{ftp: (string|undefined),
|
152 | * http: (string|undefined),
|
153 | * https: (string|undefined),
|
154 | * bypass: (Array<string>|undefined)}} options Proxy
|
155 | * configuration options.
|
156 | * @return {!ManualConfig} A new proxy configuration object.
|
157 | */
|
158 | exports.manual = function ({ ftp, http, https, bypass }) {
|
159 | return {
|
160 | proxyType: Type.MANUAL,
|
161 | ftpProxy: ftp,
|
162 | httpProxy: http,
|
163 | sslProxy: https,
|
164 | noProxy: bypass,
|
165 | }
|
166 | }
|
167 |
|
168 | /**
|
169 | * Creates a proxy configuration for a socks proxy.
|
170 | *
|
171 | * __Example:__
|
172 | *
|
173 | * const {Capabilities} = require('selenium-webdriver');
|
174 | * const proxy = require('selenium-webdriver/lib/proxy');
|
175 | *
|
176 | * let capabilities = new Capabilities();
|
177 | * capabilities.setProxy(proxy.socks('localhost:1234'));
|
178 | *
|
179 | * // Or, to include authentication.
|
180 | * capabilities.setProxy(proxy.socks('bob:password@localhost:1234'));
|
181 | *
|
182 | *
|
183 | * @param {string} socksProxy The proxy host, in the form `hostname:port`.
|
184 | * @param {number=} socksVersion The SOCKS proxy version.
|
185 | * @return {!ManualConfig} A new proxy configuration object.
|
186 | * @see https://en.wikipedia.org/wiki/SOCKS
|
187 | */
|
188 | exports.socks = function (socksProxy, socksVersion = undefined) {
|
189 | return /** @type {!Config} */ ({
|
190 | proxyType: Type.MANUAL,
|
191 | socksProxy,
|
192 | socksVersion,
|
193 | })
|
194 | }
|
195 |
|
196 | /**
|
197 | * Configures WebDriver to configure the browser proxy using the PAC file at
|
198 | * the given URL.
|
199 | * @param {string} proxyAutoconfigUrl URL for the PAC proxy to use.
|
200 | * @return {!PacConfig} A new proxy configuration object.
|
201 | */
|
202 | exports.pac = function (proxyAutoconfigUrl) {
|
203 | return { proxyType: Type.PAC, proxyAutoconfigUrl }
|
204 | }
|
205 |
|
206 | /**
|
207 | * Configures WebDriver to use the current system's proxy.
|
208 | * @return {!Config} A new proxy configuration object.
|
209 | */
|
210 | exports.system = function () {
|
211 | return { proxyType: Type.SYSTEM }
|
212 | }
|