@oracle/oraclejet-selenium-driver 19.0.0

package/DriverManager/DriverManager.cjs

@@ -0,0 +1,334 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var seleniumWebdriver = require('selenium-webdriver');
+
+/**
+ * @private
+ */
+const defaultConfigName = '';
+/**
+ * @private
+ */
+const defaultCapabilities = new seleniumWebdriver.Capabilities({
+    autoWebview: true,
+    browserName: 'chrome'
+});
+/**
+ * @private
+ */
+const defaultTimeouts = {
+    implicit: 0,
+    pageLoad: 30000,
+    script: 30000
+};
+/**
+ * @private
+ */
+const configs = {};
+/**
+ * @private
+ */
+let currentInstance = {
+    configName: undefined,
+    driver: undefined
+};
+/**
+ * The delay, in milliseconds, that the manager will wait after the driver is
+ * release to see if there are pending requests for a driver instance.  If no
+ * requests exist, then the driver is closed, and subsequent requests will
+ * receive a new instance.
+ * @private
+ */
+const quitDelay = 500;
+/**
+ * @private
+ */
+let builder;
+/**
+ * The NodeJS.Timer used to cleanup the driver instance if no subsequent test
+ * asks for the driver. The type (NodeJS.Timer) cannot be defined here because
+ * typedoc cannot resolve the NodeJS namespace, so we infer it by calling
+ * setTimeout instead.
+ * @private
+ */
+let releaseTimer = setTimeout(() => true, 0);
+/**
+ * Manage instances of [WebDriver](index._internal_.WebDriver.html)
+ * to be used by the tests. DriverManager
+ * allows a single place where the WebDriver instance can be configured and
+ * reused. Traditionally, tests instantiate the WebDriver instance on their own,
+ * passing configurations such as the browser to use:
+ * ```javascript
+ * let driver = new Builder().withCapabilities({
+ *   browserName: "chrome"
+ * }).build()
+ * ```
+ * This boilerplate code then has to be copied to every test. Additionally, if
+ * the capabilities need to change (say, running against a different browser),
+ * that change must be applied to all test files.
+ *
+ * DriverManager addresses this problem by centralizing the place whereby
+ * the configuration is done, and persists that configuration for all
+ * subsequent requests for the WebDriver instance. The configuration only needs
+ * to be set once in a "setup" file, and tests retrieve the configured instance
+ * without needing to define anything else.
+ *
+ * A sample <code>mocha-setup.ts</code> file which configures DriverManager
+ * ```javascript
+ * import { DriverManager } from "@oracle/oraclejet-selenium-driver/DriverManager";
+ *
+ * DriverManager.registerConfig({
+ *   capabilities: new Capabilities({
+ *     browserName: "chrome"
+ *   })
+ * })
+ * ```
+ * This setup test script should be run before any other tests.
+ * ```bash
+ * $ node node_modules/mocha/bin/mocha --require=ts-node/register mocha-setup.ts other-test.spec.ts ...
+ * ```
+ * Test files are agnostic of the driver configuration, and simply get the instance
+ * by calling <code>getDriver()</code>
+ * ```javascript
+ * import { DriverManager } from "@oracle/oraclejet-selenium-driver/DriverManager";
+ *
+ * describe("My test suite", function() {
+ *   let driver: WebDriver;
+ *
+ *   before(async function() {
+ *     driver = await DriverManager.getDriver();
+ *   })
+ *   it("open a page to test", async function() {
+ *     await driver.get("...")
+ *   })
+ *   after(async function() {
+ *     await DriverManager.releaseDriver(driver);
+ *   })
+ * })
+ * ```
+ *
+ * ## Set default timeouts for WebDriver from Mocha.
+ * When Mocha is used to start the WebDriver tests, there are two sets of timeout
+ * values--one from Mocha and one from WebDriver. This causes some confusion as
+ * the command-line argument <code>--timeout=nnn</code> is typically the only one
+ * set and assumed to be the only timeout value in play. However, WebDriver has
+ * its own set of timeout values whose defaults are sometimes longer than what's
+ * set for Mocha. When this happens, WebDriver may be waiting on a condition to
+ * timeout, but Mocha has errored the test because its own timeout was exceeded.
+ * To ensure that WebDriver timeout conditions are properly reported to the test
+ * runner (Mocha), its timeout values must be set to a value shorter than the
+ * runner's. This is typically done in the setup test, and set to some factor of
+ * the Mocha timeout.
+ *
+ * ### Set WebDriver timeout to 1/4 of Mocha
+ * ```javascript
+ * const mochaTimeout = this.timeouts();
+ * const wdTimeout = mochaTimeout / 4;
+ * DriverManager.registerConfig({
+ *   timeouts: {
+ *     pageLoad: wdTimeout,
+ *     script: wdTimeout,
+ *     implicit: wdTimeout
+ *   }
+ * });
+ * ```
+ *
+ */
+class DriverManager {
+    /**
+     * Optionally set the {@link Builder}
+     * instance used by DriverManager to create WebDriver.
+     * The Builder allows different settings for thigns such as the remote server,
+     * proxies, and other runtime options often needed when running in distributed
+     * environments.
+     * The instance can be preconfigured with capabilities, and any additional
+     * capabilities from [[registerConfig]] will also be applied during the
+     * creation process.  If no Builder is explicitly passed, a default one will
+     * be used.
+     * If setting a custom Builder, this function must be called before the first
+     * test calls [[getDriver]], and must only be called once per test run. If called
+     * multiple times or after [[getDriver]], an error will be thrown.
+     * @param b A builder instance
+     */
+    static setBuilder(b) {
+        if (builder) {
+            throw Error('DriverManager Builder instance has already been set, and cannot be set again');
+        }
+        builder = b;
+    }
+    /**
+     * Register a configuration for WebDriver instances. Configurations consist of
+     * {@link Capabilities} and/or {@link Timeouts}.
+     * This configuration is used by [[getDriver]] to retrieve a configured WebDriver
+     * instance.
+     * @param config The driver configuration
+     * @param name An optional name to assocaite with the config. If no name is given,
+     * the config will be the default. If a name is given, its configuration is merged with the default
+     * with its values taking precedence.
+     *
+     * ### Register a default config
+     * ```javascript
+     * DriverManager.registerConfig(
+     *   {
+     *     capabilities: new Capabilities({
+     *       browserName: "chrome"
+     *     }),
+     *     timeouts: {
+     *       implicit: 5000
+     *     }
+     *   }
+     * );
+     * ```
+     * ### Register a Firefox config. These capabilities override any matching ones set in the default
+     * ```javascript
+     * DriverManager.registerConfig(
+     *   {
+     *     capabilities: new Capabilities({
+     *       browserName: "firefox",
+     *       hideAlerts: true
+     *     })
+     *   },
+     *   "firefox-no-alerts"
+     * );
+     * ```
+     */
+    static registerConfig(config, name) {
+        configs[name || defaultConfigName] = config;
+    }
+    /**
+     * Get a {@link WebDriver}
+     * instance for a given configuration. If no configName is given, the returned
+     * driver will use the default configuration.
+     * @see [[registerConfig]]
+     *
+     * ### Get driver with default capabilities
+     * ```javascript
+     * let driver = await DriverManager.getDriver();
+     * ```
+     * ### Configure and get Firefox driver
+     * ```javascript
+     * // mocha-setup.ts
+     * DriverManager.registerConfig(
+     *   {
+     *     browserName: "firefox"
+     *   },
+     *   "firefox-config");
+     * // test.spec.ts
+     * let driver = await DriverManager.getDriver("firefox-config");
+     * ```
+     * @param configName An optional configuration name, registered through
+     * [[registerConfig]], whose set will be applied to the driver instance. If no
+     * name is given, the default configuration with the "chrome" browser
+     * will be used. If the given configName doesn't exist, an error will be thrown.
+     * @return A Promise that resolves to a WebDriver instance, configured with
+     * custom capabilities for the given configName, or the default capabilities
+     * if none is specified.
+     */
+    static async getDriver(configName) {
+        clearTimeout(releaseTimer);
+        configName = configName || defaultConfigName;
+        if (configName === currentInstance.configName) {
+            // Test if current driver is still valid
+            try {
+                if (currentInstance.driver) {
+                    await currentInstance.driver.getCurrentUrl();
+                    return currentInstance.driver;
+                }
+            }
+            catch {
+                // no driver or already quit
+            }
+        }
+        await quitCurrentDriver();
+        return createDriver(configName);
+    }
+    /**
+     * Gets the current driver instance, if one exists, otherwise create and
+     * return the default one. This method is useful for test setups which evaluate
+     * the outcome of the previous test to capture screenshots on failures. After-
+     * scripts call <code>getCurrentDriver</code> to get the instance of the driver
+     * that experienced the test failure, then capture the screenshot from it.
+     */
+    static async getCurrentDriver() {
+        return DriverManager.getDriver(currentInstance.configName);
+    }
+    /**
+     * Release the WebDriver instance from use.  Called when each test is done
+     * with its driver usage, typically, in the <code>after/afterAll</code> function.
+     * If `immediate` is not given, this method will delay a brief time before telling
+     * the driver to quit, allowing subsequent tests to reuse the same instance.
+     * If a call to {@link getDriver} is called before the timeout is reached,
+     * then the release is aborted.
+     * If `immediate` is true, then a Promise<void> will be returned and the driver
+     * told to quit immediately.
+     * @param driver The WebDriver instance
+     * @param immediate Immediately release the driver without delay
+     * @returns Promise<void> A Promise that will resolve when the driver is released if
+     * `immediate` is true, otherwise, void
+     */
+    static releaseDriver(driver, immediate = false) {
+        clearTimeout(releaseTimer);
+        return new Promise((resolve) => {
+            if (immediate) {
+                resolve(quitDriver(driver));
+            }
+            else {
+                releaseTimer = setTimeout(() => quitDriver(driver), quitDelay);
+                resolve();
+            }
+        });
+    }
+}
+DriverManager.registerConfig({ capabilities: defaultCapabilities, timeouts: defaultTimeouts });
+/**
+ * Create a WebDriver instance from the given configuration name. The config should
+ * already be registered via [registerConfig].
+ * @param configName The configuration name used to retrieve the configuration
+ * object for the driver instance
+ * @return A Promise which resolves to the configured WebDriver instance
+ * @private
+ */
+async function createDriver(configName) {
+    const config = configs[configName];
+    if (!config) {
+        throw Error(`No driver configuration exists for "${configName}"`);
+    }
+    // Merge default capabilities with custom ones
+    const caps = new seleniumWebdriver.Capabilities(configs[defaultConfigName].capabilities);
+    if (config.capabilities) {
+        caps.merge(config.capabilities);
+    }
+    // Merge default timeouts with custom ones
+    const timeouts = Object.assign({}, configs[defaultConfigName].timeouts, config.timeouts);
+    if (!builder) {
+        builder = new seleniumWebdriver.Builder();
+    }
+    const driver = builder.withCapabilities(caps).build();
+    currentInstance = { configName, driver };
+    await driver.manage().setTimeouts(timeouts);
+    return driver;
+}
+/**
+ * @private
+ */
+function quitCurrentDriver() {
+    return quitDriver(currentInstance.driver);
+}
+/**
+ * @private
+ */
+function quitDriver(driver) {
+    if (driver) {
+        currentInstance = {
+            configName: undefined,
+            driver: undefined
+        };
+        return driver.quit().catch(console.warn);
+    }
+    return Promise.resolve();
+}
+
+exports.DriverManager = DriverManager;
+//# sourceMappingURL=DriverManager.cjs.map

package/DriverManager/DriverManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"DriverManager.cjs","sources":["../../src/DriverManager/DriverManager.ts"],"sourcesContent":["import { Builder, Capabilities, WebDriver } from 'selenium-webdriver';\n\ninterface Timeouts {\n  /**\n   * The timeout value for script execution.  Default 30000\n   */\n  script?: number;\n  /**\n   * The timeout value for page loading (and to be ready).  Default 30000\n   */\n  pageLoad?: number;\n  /**\n   * The timeout value for finding an element on the page.  Default 0\n   */\n  implicit?: number;\n}\nexport interface DriverConfiguration {\n  /**\n   * The WebDriver Capabilties for the configuration\n   */\n  capabilities?: Capabilities | Record<string, any>;\n  /**\n   * The WebDriver timeout values for the configuration\n   */\n  timeouts?: Timeouts;\n}\n\n/**\n * @private\n */\nconst defaultConfigName = '';\n/**\n * @private\n */\nconst defaultCapabilities = new Capabilities({\n  autoWebview: true,\n  browserName: 'chrome'\n});\n/**\n * @private\n */\nconst defaultTimeouts: Timeouts = {\n  implicit: 0,\n  pageLoad: 30000,\n  script: 30000\n};\n/**\n * @private\n */\nconst configs: Record<string, DriverConfiguration> = {};\n/**\n * @private\n */\nlet currentInstance: { configName: string | undefined; driver: WebDriver | undefined } = {\n  configName: undefined,\n  driver: undefined\n};\n\n/**\n * The delay, in milliseconds, that the manager will wait after the driver is\n * release to see if there are pending requests for a driver instance.  If no\n * requests exist, then the driver is closed, and subsequent requests will\n * receive a new instance.\n * @private\n */\nconst quitDelay = 500;\n/**\n * @private\n */\nlet builder: Builder;\n/**\n * The NodeJS.Timer used to cleanup the driver instance if no subsequent test\n * asks for the driver. The type (NodeJS.Timer) cannot be defined here because\n * typedoc cannot resolve the NodeJS namespace, so we infer it by calling\n * setTimeout instead.\n * @private\n */\nlet releaseTimer = setTimeout(() => true, 0);\n\n/**\n * Manage instances of [WebDriver](index._internal_.WebDriver.html)\n * to be used by the tests. DriverManager\n * allows a single place where the WebDriver instance can be configured and\n * reused. Traditionally, tests instantiate the WebDriver instance on their own,\n * passing configurations such as the browser to use:\n * ```javascript\n * let driver = new Builder().withCapabilities({\n *   browserName: \"chrome\"\n * }).build()\n * ```\n * This boilerplate code then has to be copied to every test. Additionally, if\n * the capabilities need to change (say, running against a different browser),\n * that change must be applied to all test files.\n *\n * DriverManager addresses this problem by centralizing the place whereby\n * the configuration is done, and persists that configuration for all\n * subsequent requests for the WebDriver instance. The configuration only needs\n * to be set once in a \"setup\" file, and tests retrieve the configured instance\n * without needing to define anything else.\n *\n * A sample <code>mocha-setup.ts</code> file which configures DriverManager\n * ```javascript\n * import { DriverManager } from \"@oracle/oraclejet-selenium-driver/DriverManager\";\n *\n * DriverManager.registerConfig({\n *   capabilities: new Capabilities({\n *     browserName: \"chrome\"\n *   })\n * })\n * ```\n * This setup test script should be run before any other tests.\n * ```bash\n * $ node node_modules/mocha/bin/mocha --require=ts-node/register mocha-setup.ts other-test.spec.ts ...\n * ```\n * Test files are agnostic of the driver configuration, and simply get the instance\n * by calling <code>getDriver()</code>\n * ```javascript\n * import { DriverManager } from \"@oracle/oraclejet-selenium-driver/DriverManager\";\n *\n * describe(\"My test suite\", function() {\n *   let driver: WebDriver;\n *\n *   before(async function() {\n *     driver = await DriverManager.getDriver();\n *   })\n *   it(\"open a page to test\", async function() {\n *     await driver.get(\"...\")\n *   })\n *   after(async function() {\n *     await DriverManager.releaseDriver(driver);\n *   })\n * })\n * ```\n *\n * ## Set default timeouts for WebDriver from Mocha.\n * When Mocha is used to start the WebDriver tests, there are two sets of timeout\n * values--one from Mocha and one from WebDriver. This causes some confusion as\n * the command-line argument <code>--timeout=nnn</code> is typically the only one\n * set and assumed to be the only timeout value in play. However, WebDriver has\n * its own set of timeout values whose defaults are sometimes longer than what's\n * set for Mocha. When this happens, WebDriver may be waiting on a condition to\n * timeout, but Mocha has errored the test because its own timeout was exceeded.\n * To ensure that WebDriver timeout conditions are properly reported to the test\n * runner (Mocha), its timeout values must be set to a value shorter than the\n * runner's. This is typically done in the setup test, and set to some factor of\n * the Mocha timeout.\n *\n * ### Set WebDriver timeout to 1/4 of Mocha\n * ```javascript\n * const mochaTimeout = this.timeouts();\n * const wdTimeout = mochaTimeout / 4;\n * DriverManager.registerConfig({\n *   timeouts: {\n *     pageLoad: wdTimeout,\n *     script: wdTimeout,\n *     implicit: wdTimeout\n *   }\n * });\n * ```\n *\n */\nexport class DriverManager {\n  /**\n   * Optionally set the {@link Builder}\n   * instance used by DriverManager to create WebDriver.\n   * The Builder allows different settings for thigns such as the remote server,\n   * proxies, and other runtime options often needed when running in distributed\n   * environments.\n   * The instance can be preconfigured with capabilities, and any additional\n   * capabilities from [[registerConfig]] will also be applied during the\n   * creation process.  If no Builder is explicitly passed, a default one will\n   * be used.\n   * If setting a custom Builder, this function must be called before the first\n   * test calls [[getDriver]], and must only be called once per test run. If called\n   * multiple times or after [[getDriver]], an error will be thrown.\n   * @param b A builder instance\n   */\n  public static setBuilder(b: Builder) {\n    if (builder) {\n      throw Error('DriverManager Builder instance has already been set, and cannot be set again');\n    }\n    builder = b;\n  }\n  /**\n   * Register a configuration for WebDriver instances. Configurations consist of\n   * {@link Capabilities} and/or {@link Timeouts}.\n   * This configuration is used by [[getDriver]] to retrieve a configured WebDriver\n   * instance.\n   * @param config The driver configuration\n   * @param name An optional name to assocaite with the config. If no name is given,\n   * the config will be the default. If a name is given, its configuration is merged with the default\n   * with its values taking precedence.\n   *\n   * ### Register a default config\n   * ```javascript\n   * DriverManager.registerConfig(\n   *   {\n   *     capabilities: new Capabilities({\n   *       browserName: \"chrome\"\n   *     }),\n   *     timeouts: {\n   *       implicit: 5000\n   *     }\n   *   }\n   * );\n   * ```\n   * ### Register a Firefox config. These capabilities override any matching ones set in the default\n   * ```javascript\n   * DriverManager.registerConfig(\n   *   {\n   *     capabilities: new Capabilities({\n   *       browserName: \"firefox\",\n   *       hideAlerts: true\n   *     })\n   *   },\n   *   \"firefox-no-alerts\"\n   * );\n   * ```\n   */\n  public static registerConfig(config: DriverConfiguration, name?: string): void {\n    configs[name || defaultConfigName] = config;\n  }\n\n  /**\n   * Get a {@link WebDriver}\n   * instance for a given configuration. If no configName is given, the returned\n   * driver will use the default configuration.\n   * @see [[registerConfig]]\n   *\n   * ### Get driver with default capabilities\n   * ```javascript\n   * let driver = await DriverManager.getDriver();\n   * ```\n   * ### Configure and get Firefox driver\n   * ```javascript\n   * // mocha-setup.ts\n   * DriverManager.registerConfig(\n   *   {\n   *     browserName: \"firefox\"\n   *   },\n   *   \"firefox-config\");\n   * // test.spec.ts\n   * let driver = await DriverManager.getDriver(\"firefox-config\");\n   * ```\n   * @param configName An optional configuration name, registered through\n   * [[registerConfig]], whose set will be applied to the driver instance. If no\n   * name is given, the default configuration with the \"chrome\" browser\n   * will be used. If the given configName doesn't exist, an error will be thrown.\n   * @return A Promise that resolves to a WebDriver instance, configured with\n   * custom capabilities for the given configName, or the default capabilities\n   * if none is specified.\n   */\n  public static async getDriver(configName?: string): Promise<WebDriver> {\n    clearTimeout(releaseTimer);\n    configName = configName || defaultConfigName;\n\n    if (configName === currentInstance.configName) {\n      // Test if current driver is still valid\n      try {\n        if (currentInstance.driver) {\n          await currentInstance.driver.getCurrentUrl();\n          return currentInstance.driver;\n        }\n      } catch {\n        // no driver or already quit\n      }\n    }\n\n    await quitCurrentDriver();\n    return createDriver(configName);\n  }\n\n  /**\n   * Gets the current driver instance, if one exists, otherwise create and\n   * return the default one. This method is useful for test setups which evaluate\n   * the outcome of the previous test to capture screenshots on failures. After-\n   * scripts call <code>getCurrentDriver</code> to get the instance of the driver\n   * that experienced the test failure, then capture the screenshot from it.\n   */\n  public static async getCurrentDriver(): Promise<WebDriver> {\n    return DriverManager.getDriver(currentInstance.configName);\n  }\n\n  /**\n   * Release the WebDriver instance from use.  Called when each test is done\n   * with its driver usage, typically, in the <code>after/afterAll</code> function.\n   * If `immediate` is not given, this method will delay a brief time before telling\n   * the driver to quit, allowing subsequent tests to reuse the same instance.\n   * If a call to {@link getDriver} is called before the timeout is reached,\n   * then the release is aborted.\n   * If `immediate` is true, then a Promise<void> will be returned and the driver\n   * told to quit immediately.\n   * @param driver The WebDriver instance\n   * @param immediate Immediately release the driver without delay\n   * @returns Promise<void> A Promise that will resolve when the driver is released if\n   * `immediate` is true, otherwise, void\n   */\n  public static releaseDriver(driver: WebDriver, immediate = false): Promise<void> {\n    clearTimeout(releaseTimer);\n    return new Promise((resolve) => {\n      if (immediate) {\n        resolve(quitDriver(driver));\n      } else {\n        releaseTimer = setTimeout(() => quitDriver(driver), quitDelay);\n        resolve();\n      }\n    });\n  }\n}\nDriverManager.registerConfig({ capabilities: defaultCapabilities, timeouts: defaultTimeouts });\n\n/**\n * Create a WebDriver instance from the given configuration name. The config should\n * already be registered via [registerConfig].\n * @param configName The configuration name used to retrieve the configuration\n * object for the driver instance\n * @return A Promise which resolves to the configured WebDriver instance\n * @private\n */\nasync function createDriver(configName: string) {\n  const config = configs[configName];\n  if (!config) {\n    throw Error(`No driver configuration exists for \"${configName}\"`);\n  }\n  // Merge default capabilities with custom ones\n  const caps = new Capabilities(configs[defaultConfigName].capabilities);\n  if (config.capabilities) {\n    caps.merge(config.capabilities);\n  }\n  // Merge default timeouts with custom ones\n  const timeouts = Object.assign({}, configs[defaultConfigName].timeouts, config.timeouts);\n  if (!builder) {\n    builder = new Builder();\n  }\n\n  const driver = builder.withCapabilities(caps).build();\n  currentInstance = { configName, driver };\n  await driver.manage().setTimeouts(timeouts);\n  return driver;\n}\n\n/**\n * @private\n */\nfunction quitCurrentDriver() {\n  return quitDriver(currentInstance.driver);\n}\n\n/**\n * @private\n */\nfunction quitDriver(driver?: WebDriver) {\n  if (driver) {\n    currentInstance = {\n      configName: undefined,\n      driver: undefined\n    };\n    return driver.quit().catch(console.warn);\n  }\n  return Promise.resolve();\n}\n"],"names":["Capabilities","Builder"],"mappings":"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"}

package/DriverManager/DriverManager.d.ts

@@ -0,0 +1,216 @@
+import { Builder, Capabilities, WebDriver } from 'selenium-webdriver';
+interface Timeouts {
+    /**
+     * The timeout value for script execution.  Default 30000
+     */
+    script?: number;
+    /**
+     * The timeout value for page loading (and to be ready).  Default 30000
+     */
+    pageLoad?: number;
+    /**
+     * The timeout value for finding an element on the page.  Default 0
+     */
+    implicit?: number;
+}
+export interface DriverConfiguration {
+    /**
+     * The WebDriver Capabilties for the configuration
+     */
+    capabilities?: Capabilities | Record<string, any>;
+    /**
+     * The WebDriver timeout values for the configuration
+     */
+    timeouts?: Timeouts;
+}
+/**
+ * Manage instances of [WebDriver](index._internal_.WebDriver.html)
+ * to be used by the tests. DriverManager
+ * allows a single place where the WebDriver instance can be configured and
+ * reused. Traditionally, tests instantiate the WebDriver instance on their own,
+ * passing configurations such as the browser to use:
+ * ```javascript
+ * let driver = new Builder().withCapabilities({
+ *   browserName: "chrome"
+ * }).build()
+ * ```
+ * This boilerplate code then has to be copied to every test. Additionally, if
+ * the capabilities need to change (say, running against a different browser),
+ * that change must be applied to all test files.
+ *
+ * DriverManager addresses this problem by centralizing the place whereby
+ * the configuration is done, and persists that configuration for all
+ * subsequent requests for the WebDriver instance. The configuration only needs
+ * to be set once in a "setup" file, and tests retrieve the configured instance
+ * without needing to define anything else.
+ *
+ * A sample <code>mocha-setup.ts</code> file which configures DriverManager
+ * ```javascript
+ * import { DriverManager } from "@oracle/oraclejet-selenium-driver/DriverManager";
+ *
+ * DriverManager.registerConfig({
+ *   capabilities: new Capabilities({
+ *     browserName: "chrome"
+ *   })
+ * })
+ * ```
+ * This setup test script should be run before any other tests.
+ * ```bash
+ * $ node node_modules/mocha/bin/mocha --require=ts-node/register mocha-setup.ts other-test.spec.ts ...
+ * ```
+ * Test files are agnostic of the driver configuration, and simply get the instance
+ * by calling <code>getDriver()</code>
+ * ```javascript
+ * import { DriverManager } from "@oracle/oraclejet-selenium-driver/DriverManager";
+ *
+ * describe("My test suite", function() {
+ *   let driver: WebDriver;
+ *
+ *   before(async function() {
+ *     driver = await DriverManager.getDriver();
+ *   })
+ *   it("open a page to test", async function() {
+ *     await driver.get("...")
+ *   })
+ *   after(async function() {
+ *     await DriverManager.releaseDriver(driver);
+ *   })
+ * })
+ * ```
+ *
+ * ## Set default timeouts for WebDriver from Mocha.
+ * When Mocha is used to start the WebDriver tests, there are two sets of timeout
+ * values--one from Mocha and one from WebDriver. This causes some confusion as
+ * the command-line argument <code>--timeout=nnn</code> is typically the only one
+ * set and assumed to be the only timeout value in play. However, WebDriver has
+ * its own set of timeout values whose defaults are sometimes longer than what's
+ * set for Mocha. When this happens, WebDriver may be waiting on a condition to
+ * timeout, but Mocha has errored the test because its own timeout was exceeded.
+ * To ensure that WebDriver timeout conditions are properly reported to the test
+ * runner (Mocha), its timeout values must be set to a value shorter than the
+ * runner's. This is typically done in the setup test, and set to some factor of
+ * the Mocha timeout.
+ *
+ * ### Set WebDriver timeout to 1/4 of Mocha
+ * ```javascript
+ * const mochaTimeout = this.timeouts();
+ * const wdTimeout = mochaTimeout / 4;
+ * DriverManager.registerConfig({
+ *   timeouts: {
+ *     pageLoad: wdTimeout,
+ *     script: wdTimeout,
+ *     implicit: wdTimeout
+ *   }
+ * });
+ * ```
+ *
+ */
+export declare class DriverManager {
+    /**
+     * Optionally set the {@link Builder}
+     * instance used by DriverManager to create WebDriver.
+     * The Builder allows different settings for thigns such as the remote server,
+     * proxies, and other runtime options often needed when running in distributed
+     * environments.
+     * The instance can be preconfigured with capabilities, and any additional
+     * capabilities from [[registerConfig]] will also be applied during the
+     * creation process.  If no Builder is explicitly passed, a default one will
+     * be used.
+     * If setting a custom Builder, this function must be called before the first
+     * test calls [[getDriver]], and must only be called once per test run. If called
+     * multiple times or after [[getDriver]], an error will be thrown.
+     * @param b A builder instance
+     */
+    static setBuilder(b: Builder): void;
+    /**
+     * Register a configuration for WebDriver instances. Configurations consist of
+     * {@link Capabilities} and/or {@link Timeouts}.
+     * This configuration is used by [[getDriver]] to retrieve a configured WebDriver
+     * instance.
+     * @param config The driver configuration
+     * @param name An optional name to assocaite with the config. If no name is given,
+     * the config will be the default. If a name is given, its configuration is merged with the default
+     * with its values taking precedence.
+     *
+     * ### Register a default config
+     * ```javascript
+     * DriverManager.registerConfig(
+     *   {
+     *     capabilities: new Capabilities({
+     *       browserName: "chrome"
+     *     }),
+     *     timeouts: {
+     *       implicit: 5000
+     *     }
+     *   }
+     * );
+     * ```
+     * ### Register a Firefox config. These capabilities override any matching ones set in the default
+     * ```javascript
+     * DriverManager.registerConfig(
+     *   {
+     *     capabilities: new Capabilities({
+     *       browserName: "firefox",
+     *       hideAlerts: true
+     *     })
+     *   },
+     *   "firefox-no-alerts"
+     * );
+     * ```
+     */
+    static registerConfig(config: DriverConfiguration, name?: string): void;
+    /**
+     * Get a {@link WebDriver}
+     * instance for a given configuration. If no configName is given, the returned
+     * driver will use the default configuration.
+     * @see [[registerConfig]]
+     *
+     * ### Get driver with default capabilities
+     * ```javascript
+     * let driver = await DriverManager.getDriver();
+     * ```
+     * ### Configure and get Firefox driver
+     * ```javascript
+     * // mocha-setup.ts
+     * DriverManager.registerConfig(
+     *   {
+     *     browserName: "firefox"
+     *   },
+     *   "firefox-config");
+     * // test.spec.ts
+     * let driver = await DriverManager.getDriver("firefox-config");
+     * ```
+     * @param configName An optional configuration name, registered through
+     * [[registerConfig]], whose set will be applied to the driver instance. If no
+     * name is given, the default configuration with the "chrome" browser
+     * will be used. If the given configName doesn't exist, an error will be thrown.
+     * @return A Promise that resolves to a WebDriver instance, configured with
+     * custom capabilities for the given configName, or the default capabilities
+     * if none is specified.
+     */
+    static getDriver(configName?: string): Promise<WebDriver>;
+    /**
+     * Gets the current driver instance, if one exists, otherwise create and
+     * return the default one. This method is useful for test setups which evaluate
+     * the outcome of the previous test to capture screenshots on failures. After-
+     * scripts call <code>getCurrentDriver</code> to get the instance of the driver
+     * that experienced the test failure, then capture the screenshot from it.
+     */
+    static getCurrentDriver(): Promise<WebDriver>;
+    /**
+     * Release the WebDriver instance from use.  Called when each test is done
+     * with its driver usage, typically, in the <code>after/afterAll</code> function.
+     * If `immediate` is not given, this method will delay a brief time before telling
+     * the driver to quit, allowing subsequent tests to reuse the same instance.
+     * If a call to {@link getDriver} is called before the timeout is reached,
+     * then the release is aborted.
+     * If `immediate` is true, then a Promise<void> will be returned and the driver
+     * told to quit immediately.
+     * @param driver The WebDriver instance
+     * @param immediate Immediately release the driver without delay
+     * @returns Promise<void> A Promise that will resolve when the driver is released if
+     * `immediate` is true, otherwise, void
+     */
+    static releaseDriver(driver: WebDriver, immediate?: boolean): Promise<void>;
+}
+export {};