# Class DriverManager

Manage instances of WebDriver 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:

    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 `mocha-setup.ts` file which configures DriverManager

    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.

    $ 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 `getDriver()`

    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 `--timeout=nnn` 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

    const mochaTimeout = this.timeouts();
    const wdTimeout = mochaTimeout / 4;
    DriverManager.registerConfig({
      timeouts: {
        pageLoad: wdTimeout,
        script: wdTimeout,
        implicit: wdTimeout
      }
    });

#### Hierarchy

- DriverManager

#####
Index

### Constructors

constructor

### Methods

getCurrentDriver
getDriver
registerConfig
releaseDriver
setBuilder

## Constructors

### constructor

- new DriverManager(): DriverManager

- #### Returns DriverManager

## Methods

### `Static` getCurrentDriver

- getCurrentDriver(): 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 `getCurrentDriver` to get the instance of the driver that experienced the test failure, then capture the screenshot from it.

  #### Returns Promise<WebDriver>

### `Static` getDriver

- getDriver(configName?): Promise<WebDriver>

- Get a WebDriver instance for a given configuration. If no configName is given, the returned driver will use the default configuration.

  #### Parameters

  - ##### `Optional` configName: string

    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.

  #### Returns Promise<WebDriver>

  A Promise that resolves to a WebDriver instance, configured with custom capabilities for the given configName, or the default capabilities if none is specified.

  #### See

  [[registerConfig]]

  ### Get driver with default capabilities

      let driver = await DriverManager.getDriver();

  ### Configure and get Firefox driver

      // mocha-setup.ts
      DriverManager.registerConfig(
        {
          browserName: "firefox"
        },
        "firefox-config");
      // test.spec.ts
      let driver = await DriverManager.getDriver("firefox-config");

### `Static` registerConfig

- registerConfig(config, name?): void

- Register a configuration for WebDriver instances. Configurations consist of Capabilities and/or Timeouts. This configuration is used by [[getDriver]] to retrieve a configured WebDriver instance.

  #### Parameters

  - ##### config: DriverConfiguration

    The driver configuration

  - ##### `Optional` name: string

    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

        DriverManager.registerConfig(
          {
            capabilities: new Capabilities({
              browserName: "chrome"
            }),
            timeouts: {
              implicit: 5000
            }
          }
        );

    ### Register a Firefox config. These capabilities override any matching ones set in the default

        DriverManager.registerConfig(
          {
            capabilities: new Capabilities({
              browserName: "firefox",
              hideAlerts: true
            })
          },
          "firefox-no-alerts"
        );

  #### Returns void

### `Static` releaseDriver

- releaseDriver(driver, immediate?): Promise<void>

- Release the WebDriver instance from use. Called when each test is done with its driver usage, typically, in the `after/afterAll` 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 getDriver is called before the timeout is reached, then the release is aborted. If `immediate` is true, then a Promise will be returned and the driver told to quit immediately.

  #### Parameters

  - ##### driver: WebDriver

    The WebDriver instance

  - ##### `Optional` immediate: boolean

    Immediately release the driver without delay

  #### Returns Promise<void>

  Promise A Promise that will resolve when the driver is released if `immediate` is true, otherwise, void

### `Static` setBuilder

- setBuilder(b): void

- Optionally set the 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.

  #### Parameters

  - ##### b: Builder

    A builder instance

  #### Returns void

Generated using TypeDoc