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 WebDriver client for Safari.
20
 *
21
 * @module selenium-webdriver/safari
22
 */
23

24
'use strict'
25

26
const http = require('./http')
27
const remote = require('./remote')
28
const webdriver = require('./lib/webdriver')
29
const { Browser, Capabilities } = require('./lib/capabilities')
30
const { getBinaryPaths } = require('./common/driverFinder')
31

32
/**
33
 * Creates {@link remote.DriverService} instances that manage
34
 * a [safaridriver] server in a child process.
35
 *
36
 * [safaridriver]: https://developer.apple.com/library/prerelease/content/releasenotes/General/WhatsNewInSafari/Articles/Safari_10_0.html#//apple_ref/doc/uid/TP40014305-CH11-DontLinkElementID_28
37
 */
38
class ServiceBuilder extends remote.DriverService.Builder {
39
  /**
40
   * @param {string=} opt_exe Path to the server executable to use. If omitted,
41
   *     the builder will attempt to locate the safaridriver on the system PATH.
42
   */
43
  constructor(opt_exe) {
44
    super(opt_exe)
45
    this.setLoopback(true) // Required.
46
  }
47
}
48

49
const OPTIONS_CAPABILITY_KEY = 'safari:options'
50
const TECHNOLOGY_PREVIEW_OPTIONS_KEY = 'technologyPreview'
51

52
/**
53
 * Configuration options specific to the {@link Driver SafariDriver}.
54
 */
55
class Options extends Capabilities {
56
  /**
57
   * @param {(Capabilities|Map<string, ?>|Object)=} other Another set of
58
   *     capabilities to initialize this instance from.
59
   */
60
  constructor(other = undefined) {
61
    super(other)
62

63
    /** @private {!Object} */
64
    this.options_ = this.get(OPTIONS_CAPABILITY_KEY) || {}
65

66
    this.set(OPTIONS_CAPABILITY_KEY, this.options_)
67
    this.setBrowserName(Browser.SAFARI)
68
  }
69

70
  /**
71
   * Instruct the SafariDriver to use the Safari Technology Preview if true.
72
   * Otherwise, use the release version of Safari. Defaults to using the release version of Safari.
73
   *
74
   * @param {boolean} useTechnologyPreview
75
   * @return {!Options} A self reference.
76
   */
77
  setTechnologyPreview(useTechnologyPreview) {
78
    this.options_[TECHNOLOGY_PREVIEW_OPTIONS_KEY] = !!useTechnologyPreview
79
    return this
80
  }
81

82
  /**
83
   * Enables diagnostic logging for Safari.
84
   *
85
   * This method sets the `safari:diagnose` option to `true` in the current configuration.
86
   * It is used to enable additional logging or diagnostic features specific to Safari.
87
   *
88
   * @returns {Options} Returns the current instance
89
   */
90
  enableLogging() {
91
    this.set('safari:diagnose', true)
92
    return this
93
  }
94
}
95

96
/**
97
 * @param  {(Capabilities|Object<string, *>)=} o The options object
98
 * @return {boolean}
99
 */
100
function useTechnologyPreview(o) {
101
  if (o instanceof Capabilities) {
102
    let options = o.get(OPTIONS_CAPABILITY_KEY)
103
    return !!(options && options[TECHNOLOGY_PREVIEW_OPTIONS_KEY])
104
  }
105

106
  if (o && typeof o === 'object') {
107
    return !!o[TECHNOLOGY_PREVIEW_OPTIONS_KEY]
108
  }
109

110
  return false
111
}
112

113
const SAFARIDRIVER_TECHNOLOGY_PREVIEW_EXE = '/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver'
114

115
/**
116
 * A WebDriver client for Safari. This class should never be instantiated
117
 * directly; instead, use the {@linkplain ./builder.Builder Builder}:
118
 *
119
 *     var driver = new Builder()
120
 *         .forBrowser('safari')
121
 *         .build();
122
 *
123
 */
124
class Driver extends webdriver.WebDriver {
125
  /**
126
   * Creates a new Safari session.
127
   *
128
   * @param {(Options|Capabilities)=} options The configuration options.
129
   * @return {!Driver} A new driver instance.
130
   */
131
  static createSession(options) {
132
    let caps = options || new Options()
133

134
    let exe
135
    if (useTechnologyPreview(caps.get(OPTIONS_CAPABILITY_KEY))) {
136
      exe = SAFARIDRIVER_TECHNOLOGY_PREVIEW_EXE
137
    }
138

139
    let service = new ServiceBuilder(exe).build()
140
    if (!service.getExecutable()) {
141
      service.setExecutable(getBinaryPaths(caps).driverPath)
142
    }
143
    let executor = new http.Executor(service.start().then((url) => new http.HttpClient(url)))
144

145
    return /** @type {!Driver} */ (super.createSession(executor, caps, () => service.kill()))
146
  }
147
}
148

149
// Public API
150

151
exports.Driver = Driver
152
exports.Options = Options
153
exports.ServiceBuilder = ServiceBuilder
154

155