proxy.js

1// Copyright 2013 Selenium committers
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15/**
16 * @fileoverview Defines functions for configuring a webdriver proxy:
17 * <pre><code>
18 * var webdriver = require('selenium-webdriver'),
19 * proxy = require('selenium-webdriver/proxy');
20 *
21 * var driver = new webdriver.Builder()
22 * .withCapabilities(webdriver.Capabilities.chrome())
23 * .setProxy(proxy.manual({http: 'host:1234'}))
24 * .build();
25 * </code></pre>
26 */
27
28'use strict';
29
30var util = require('util');
31
32
33/**
34 * Proxy configuration object, as defined by the WebDriver wire protocol.
35 * @typedef {(
36 * {proxyType: string}|
37 * {proxyType: string,
38 * proxyAutoconfigUrl: string}|
39 * {proxyType: string,
40 * ftpProxy: string,
41 * httpProxy: string,
42 * sslProxy: string,
43 * noProxy: string})}
44 */
45var ProxyConfig;
46
47
48
49// PUBLIC API
50
51
52/**
53 * Configures WebDriver to bypass all browser proxies.
54 * @return {!ProxyConfig} A new proxy configuration object.
55 */
56exports.direct = function() {
57 return {proxyType: 'direct'};
58};
59
60
61/**
62 * Manually configures the browser proxy. The following options are
63 * supported:
64 * <ul>
65 * <li>{@code ftp}: Proxy host to use for FTP requests
66 * <li>{@code http}: Proxy host to use for HTTP requests
67 * <li>{@code https}: Proxy host to use for HTTPS requests
68 * <li>{@code bypass}: A list of hosts requests should directly connect to,
69 * bypassing any other proxies for that request. May be specified as a
70 * comma separated string, or a list of strings.
71 * </ul>
72 *
73 * Behavior is undefined for FTP, HTTP, and HTTPS requests if the
74 * corresponding key is omitted from the configuration options.
75 *
76 * @param {{ftp: (string|undefined),
77 * http: (string|undefined),
78 * https: (string|undefined),
79 * bypass: (string|!Array.<string>|undefined)}} options Proxy
80 * configuration options.
81 * @return {!ProxyConfig} A new proxy configuration object.
82 */
83exports.manual = function(options) {
84 return {
85 proxyType: 'manual',
86 ftpProxy: options.ftp,
87 httpProxy: options.http,
88 sslProxy: options.https,
89 noProxy: util.isArray(options.bypass) ?
90 options.bypass.join(',') : options.bypass
91 };
92};
93
94
95/**
96 * Configures WebDriver to configure the browser proxy using the PAC file at
97 * the given URL.
98 * @param {string} url URL for the PAC proxy to use.
99 * @return {!ProxyConfig} A new proxy configuration object.
100 */
101exports.pac = function(url) {
102 return {
103 proxyType: 'pac',
104 proxyAutoconfigUrl: url
105 };
106};
107
108
109/**
110 * Configures WebDriver to use the current system's proxy.
111 * @return {!ProxyConfig} A new proxy configuration object.
112 */
113exports.system = function() {
114 return {proxyType: 'system'};
115};