selenium-webdriver 4.0.0-alpha.8 → 4.0.0-beta.4

package/testing/index.js

@@ -0,0 +1,504 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+/**
+ * @fileoverview Provides extensions for
+ * [Jasmine](https://jasmine.github.io) and [Mocha](https://mochajs.org).
+ *
+ * You may conditionally suppress a test function using the exported
+ * "ignore" function. If the provided predicate returns true, the attached
+ * test case will be skipped:
+ *
+ *     test.ignore(maybe()).it('is flaky', function() {
+ *       if (Math.random() < 0.5) throw Error();
+ *     });
+ *
+ *     function maybe() { return Math.random() < 0.5; }
+ */
+
+'use strict'
+
+const { isatty } = require('tty')
+const chrome = require('../chrome')
+const edge = require('../edge')
+const firefox = require('../firefox')
+const ie = require('../ie')
+const remote = require('../remote')
+const safari = require('../safari')
+const opera = require('../opera')
+const { Browser } = require('../lib/capabilities')
+const { Builder } = require('../index')
+
+/**
+ * Describes a browser targeted by a {@linkplain suite test suite}.
+ * @record
+ */
+function TargetBrowser() { }
+
+/**
+ * The {@linkplain Browser name} of the targeted browser.
+ * @type {string}
+ */
+TargetBrowser.prototype.name
+
+/**
+ * The specific version of the targeted browser, if any.
+ * @type {(string|undefined)}
+ */
+TargetBrowser.prototype.version
+
+/**
+ * The specific {@linkplain ../lib/capabilities.Platform platform} for the
+ * targeted browser, if any.
+ * @type {(string|undefined)}.
+ */
+TargetBrowser.prototype.platform
+
+/** @suppress {checkTypes} */
+function color(c, s) {
+  return isatty(process.stdout) ? `\u001b[${c}m${s}\u001b[0m` : s
+}
+function green(s) {
+  return color(32, s)
+}
+function cyan(s) {
+  return color(36, s)
+}
+function info(msg) {
+  console.info(`${green('[INFO]')} ${msg}`)
+}
+function warn(msg) {
+  console.warn(`${cyan('[WARNING]')} ${msg}`)
+}
+
+/**
+ * Extracts the browsers for a test suite to target from the `SELENIUM_BROWSER`
+ * environment variable.
+ *
+ * @return {!Array<!TargetBrowser>} the browsers to target.
+ */
+function getBrowsersToTestFromEnv() {
+  let browsers = process.env['SELENIUM_BROWSER']
+  if (!browsers) {
+    return []
+  }
+  return browsers.split(',').map((spec) => {
+    const parts = spec.split(/:/, 3)
+    let name = parts[0]
+    if (name === 'ie') {
+      name = Browser.INTERNET_EXPLORER
+    } else if (name === 'edge') {
+      name = Browser.EDGE
+    }
+    let version = parts[1]
+    let platform = parts[2]
+    return { name, version, platform }
+  })
+}
+
+/**
+ * @return {!Array<!TargetBrowser>} the browsers available for testing on this
+ *     system.
+ */
+function getAvailableBrowsers() {
+  info(`Searching for WebDriver executables installed on the current system...`)
+
+  let targets = [
+    [chrome.locateSynchronously, Browser.CHROME],
+    [edge.locateSynchronously, Browser.EDGE],
+    [firefox.locateSynchronously, Browser.FIREFOX],
+    [ie.locateSynchronously, Browser.INTERNET_EXPLORER],
+    [safari.locateSynchronously, Browser.SAFARI],
+    [opera.locateSynchronously, Browser.OPERA],
+  ]
+
+  let availableBrowsers = []
+  for (let pair of targets) {
+    const fn = pair[0]
+    const name = pair[1]
+    const capabilities = pair[2]
+    if (fn()) {
+      info(`... located ${name}`)
+      availableBrowsers.push({ name, capabilities })
+    }
+  }
+
+  if (availableBrowsers.length === 0) {
+    warn(`Unable to locate any WebDriver executables for testing`)
+  }
+
+  return availableBrowsers
+}
+
+let wasInit
+let targetBrowsers
+let seleniumJar
+let seleniumUrl
+let seleniumServer
+
+/**
+ * Initializes this module by determining which browsers a
+ * {@linkplain ./index.suite test suite} should run against. The default
+ * behavior is to run tests against every browser with a WebDriver executables
+ * (chromedriver, firefoxdriver, etc.) are installed on the system by `PATH`.
+ *
+ * Specific browsers can be selected at runtime by setting the
+ * `SELENIUM_BROWSER` environment variable. This environment variable has the
+ * same semantics as  with the WebDriver {@link ../index.Builder Builder},
+ * except you may use a comma-delimited list to run against multiple browsers:
+ *
+ *     SELENIUM_BROWSER=chrome,firefox mocha --recursive tests/
+ *
+ * The `SELENIUM_REMOTE_URL` environment variable may be set to configure tests
+ * to run against an externally managed (usually remote) Selenium server. When
+ * set, the WebDriver builder provided by each
+ * {@linkplain TestEnvironment#builder TestEnvironment} will automatically be
+ * configured to use this server instead of starting a browser driver locally.
+ *
+ * The `SELENIUM_SERVER_JAR` environment variable may be set to the path of a
+ * standalone Selenium server on the local machine that should be used for
+ * WebDriver sessions. When set, the WebDriver builder provided by each
+ * {@linkplain TestEnvironment} will automatically be configured to use the
+ * started server instead of using a browser driver directly. It should only be
+ * necessary to set the `SELENIUM_SERVER_JAR` when testing locally against
+ * browsers not natively supported by the WebDriver
+ * {@link ../index.Builder Builder}.
+ *
+ * When either of the `SELENIUM_REMOTE_URL` or `SELENIUM_SERVER_JAR` environment
+ * variables are set, the `SELENIUM_BROWSER` variable must also be set.
+ *
+ * @param {boolean=} force whether to force this module to re-initialize and
+ *     scan `process.env` again to determine which browsers to run tests
+ *     against.
+ */
+function init(force = false) {
+  if (wasInit && !force) {
+    return
+  }
+  wasInit = true
+
+  // If force re-init, kill the current server if there is one.
+  if (seleniumServer) {
+    seleniumServer.kill()
+    seleniumServer = null
+  }
+
+  seleniumJar = process.env['SELENIUM_SERVER_JAR']
+  seleniumUrl = process.env['SELENIUM_REMOTE_URL']
+  if (seleniumJar) {
+    info(`Using Selenium server jar: ${seleniumJar}`)
+  }
+
+  if (seleniumUrl) {
+    info(`Using Selenium remote end: ${seleniumUrl}`)
+  }
+
+  if (seleniumJar && seleniumUrl) {
+    throw Error(
+      'Ambiguous test configuration: both SELENIUM_REMOTE_URL' +
+      ' && SELENIUM_SERVER_JAR environment variables are set'
+    )
+  }
+
+  const envBrowsers = getBrowsersToTestFromEnv()
+  if ((seleniumJar || seleniumUrl) && envBrowsers.length === 0) {
+    throw Error(
+      'Ambiguous test configuration: when either the SELENIUM_REMOTE_URL or' +
+      ' SELENIUM_SERVER_JAR environment variable is set, the' +
+      ' SELENIUM_BROWSER variable must also be set.'
+    )
+  }
+
+  targetBrowsers = envBrowsers.length > 0 ? envBrowsers : getAvailableBrowsers()
+  info(
+    `Running tests against [${targetBrowsers.map((b) => b.name).join(', ')}]`
+  )
+
+  after(function () {
+    if (seleniumServer) {
+      return seleniumServer.kill()
+    }
+  })
+}
+
+const TARGET_MAP = /** !WeakMap<!Environment, !TargetBrowser> */ new WeakMap()
+const URL_MAP = /** !WeakMap<!Environment, ?(string|remote.SeleniumServer)> */ new WeakMap()
+
+/**
+ * Defines the environment a {@linkplain suite test suite} is running against.
+ * @final
+ */
+class Environment {
+  /**
+   * @param {!TargetBrowser} browser the browser targetted in this environment.
+   * @param {?(string|remote.SeleniumServer)=} url remote URL of an existing
+   *     Selenium server to test against.
+   */
+  constructor(browser, url = undefined) {
+    browser = /** @type {!TargetBrowser} */ (Object.seal(
+      Object.assign({}, browser)
+    ))
+
+    TARGET_MAP.set(this, browser)
+    URL_MAP.set(this, url || null)
+  }
+
+  /** @return {!TargetBrowser} the target browser for this test environment. */
+  get browser() {
+    return TARGET_MAP.get(this)
+  }
+
+  /**
+   * Returns a predicate function that will suppress tests in this environment
+   * if the {@linkplain #browser current browser} is in the list of
+   * `browsersToIgnore`.
+   *
+   * @param {...(string|!Browser)} browsersToIgnore the browsers that should
+   *     be ignored.
+   * @return {function(): boolean} a new predicate function.
+   */
+  browsers(...browsersToIgnore) {
+    return () => browsersToIgnore.indexOf(this.browser.name) != -1
+  }
+
+  /**
+   * @return {!Builder} a new WebDriver builder configured to target this
+   *     environment's {@linkplain #browser browser}.
+   */
+  builder() {
+    const browser = this.browser
+    const urlOrServer = URL_MAP.get(this)
+
+    const builder = new Builder()
+    builder.disableEnvironmentOverrides()
+
+    const realBuild = builder.build
+    builder.build = function () {
+
+      builder.forBrowser(browser.name, browser.version, browser.platform)
+
+      if (browser.capabilities) {
+        builder.getCapabilities().merge(browser.capabilities)
+      }
+
+      if (typeof urlOrServer === 'string') {
+        builder.usingServer(urlOrServer)
+      } else if (urlOrServer) {
+        builder.usingServer(urlOrServer.address())
+      }
+      return realBuild.call(builder)
+    }
+
+    return builder
+  }
+}
+
+/**
+ * Configuration options for a {@linkplain ./index.suite test suite}.
+ * @record
+ */
+function SuiteOptions() { }
+
+/**
+ * The browsers to run the test suite against.
+ * @type {!Array<!(Browser|TargetBrowser)>}
+ */
+SuiteOptions.prototype.browsers
+
+let inSuite = false
+
+/**
+ * Defines a test suite by calling the provided function once for each of the
+ * target browsers. If a suite is not limited to a specific set of browsers in
+ * the provided {@linkplain ./index.SuiteOptions suite options}, the suite will
+ * be configured to run against each of the {@linkplain ./index.init runtime
+ * target browsers}.
+ *
+ * Sample usage:
+ *
+ *     const {By, Key, until} = require('selenium-webdriver');
+ *     const {suite} = require('selenium-webdriver/testing');
+ *
+ *     suite(function(env) {
+ *       describe('Google Search', function() {
+ *         let driver;
+ *
+ *         before(async function() {
+ *           driver = await env.builder().build();
+ *         });
+ *
+ *         after(() => driver.quit());
+ *
+ *         it('demo', async function() {
+ *           await driver.get('http://www.google.com/ncr');
+ *
+ *           let q = await driver.findElement(By.name('q'));
+ *           await q.sendKeys('webdriver', Key.RETURN);
+ *           await driver.wait(
+ *               until.titleIs('webdriver - Google Search'), 1000);
+ *         });
+ *       });
+ *     });
+ *
+ * By default, this example suite will run against every WebDriver-enabled
+ * browser on the current system. Alternatively, the `SELENIUM_BROWSER`
+ * environment variable may be used to run against a specific browser:
+ *
+ *     SELENIUM_BROWSER=firefox mocha -t 120000 example_test.js
+ *
+ * @param {function(!Environment)} fn the function to call to build the test
+ *     suite.
+ * @param {SuiteOptions=} options configuration options.
+ */
+function suite(fn, options = undefined) {
+  if (inSuite) {
+    throw Error('Calls to suite() may not be nested')
+  }
+  try {
+    init()
+    inSuite = true
+
+    const suiteBrowsers = new Map()
+    if (options && options.browsers) {
+      for (let browser of options.browsers) {
+        if (typeof browser === 'string') {
+          suiteBrowsers.set(browser, { name: browser })
+        } else {
+          suiteBrowsers.set(browser.name, browser)
+        }
+      }
+    }
+
+    for (let browser of targetBrowsers) {
+      if (suiteBrowsers.size > 0 && !suiteBrowsers.has(browser.name)) {
+        continue
+      }
+
+      describe(`[${browser.name}]`, function () {
+        if (!seleniumUrl && seleniumJar && !seleniumServer) {
+          seleniumServer = new remote.SeleniumServer(seleniumJar)
+
+          const startTimeout = 65 * 1000
+          // eslint-disable-next-line no-inner-declarations
+          function startSelenium() {
+            if (typeof this.timeout === 'function') {
+              this.timeout(startTimeout) // For mocha.
+            }
+
+            info(`Starting selenium server ${seleniumJar}`)
+            return seleniumServer.start(60 * 1000)
+          }
+
+          const /** !Function */ beforeHook = global.beforeAll || global.before
+          beforeHook(startSelenium, startTimeout)
+        }
+
+        fn(new Environment(browser, seleniumUrl || seleniumServer))
+      })
+    }
+  } finally {
+    inSuite = false
+  }
+}
+
+/**
+ * Returns an object with wrappers for the standard mocha/jasmine test
+ * functions: `describe` and `it`, which will redirect to `xdescribe` and `xit`,
+ * respectively, if provided predicate function returns false.
+ *
+ * Sample usage:
+ *
+ *     const {Browser} = require('selenium-webdriver');
+ *     const {suite, ignore} = require('selenium-webdriver/testing');
+ *
+ *     suite(function(env) {
+ *
+ *         // Skip tests the current environment targets Chrome.
+ *         ignore(env.browsers(Browser.CHROME)).
+ *         describe('something', async function() {
+ *           let driver = await env.builder().build();
+ *           // etc.
+ *         });
+ *     });
+ *
+ * @param {function(): boolean} predicateFn A predicate to call to determine
+ *     if the test should be suppressed. This function MUST be synchronous.
+ * @return {{describe: !Function, it: !Function}} an object with wrapped
+ *     versions of the `describe` and `it` wtest functions.
+ */
+function ignore(predicateFn) {
+  const isJasmine = global.jasmine && typeof global.jasmine === 'object'
+
+  const hooks = {
+    describe: getTestHook('describe'),
+    xdescribe: getTestHook('xdescribe'),
+    it: getTestHook('it'),
+    xit: getTestHook('xit'),
+  }
+  hooks.fdescribe = isJasmine ? getTestHook('fdescribe') : hooks.describe.only
+  hooks.fit = isJasmine ? getTestHook('fit') : hooks.it.only
+
+  let describe = wrap(hooks.xdescribe, hooks.describe)
+  let fdescribe = wrap(hooks.xdescribe, hooks.fdescribe)
+  //eslint-disable-next-line no-only-tests/no-only-tests
+  describe.only = fdescribe
+
+  let it = wrap(hooks.xit, hooks.it)
+  let fit = wrap(hooks.xit, hooks.fit)
+  //eslint-disable-next-line no-only-tests/no-only-tests
+  it.only = fit
+
+  return { describe, it }
+
+  function wrap(onSkip, onRun) {
+    return function (...args) {
+      if (predicateFn()) {
+        onSkip(...args)
+      } else {
+        onRun(...args)
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} name
+ * @return {!Function}
+ * @throws {TypeError}
+ */
+function getTestHook(name) {
+  let fn = global[name]
+  let type = typeof fn
+  if (type !== 'function') {
+    throw TypeError(
+      `Expected global.${name} to be a function, but is ${type}.` +
+      ' This can happen if you try using this module when running with' +
+      ' node directly instead of using jasmine or mocha'
+    )
+  }
+  return fn
+}
+
+// PUBLIC API
+
+module.exports = {
+  Environment,
+  SuiteOptions,
+  init,
+  ignore,
+  suite,
+}

package/.eslintrc.js

@@ -1,27 +0,0 @@
-module.exports = {
-  env: {
-    mocha: true,
-    node: true,
-    es6: true,
-  },
-  extends: ['eslint:recommended', 'plugin:node/recommended', 'prettier'],
-  plugins: ['prettier', 'no-only-tests'],
-  rules: {
-    'prettier/prettier': 'error',
-    'no-const-assign': 'error',
-    'no-this-before-super': 'error',
-    'no-undef': 'error',
-    'no-unreachable': 'error',
-    'no-unused-vars': [
-      'error',
-      { varsIgnorePattern: '^_', args: 'all', argsIgnorePattern: '^_' },
-    ],
-    'constructor-super': 'error',
-    'valid-typeof': 'error',
-    'no-only-tests/no-only-tests': 'error',
-    'node/no-unpublished-require': 'error',
-    'node/no-unsupported-features/es-syntax': 0,
-    'node/no-unsupported-features/node-builtins': 0,
-    'node/no-missing-import': 'error',
-  },
-}

package/.prettierrc

@@ -1,4 +0,0 @@
-{
-  "semi": false,
-  "singleQuote": true
-}