@oracle/oraclejet-webdriver 18.1.5 → 19.0.0

package/src/elements/oj-tab-bar/OjTabBarBase.ts

@@ -173,11 +173,31 @@ export interface Translations {
    * @deprecated Since 18.0.0. The Redwood design system does not allow this to be customized.
    */
   accessibleReorderTouchInstructionText: string;
+  /**
+   * Provides properties to customize the default context menu item's aria-label
+   * @deprecated Since 19.0.0. The Redwood design system does not allow this to be customized.
+   */
+  labelActions: string;
+  /**
+   * The context menu description text used for aria describedby by tabbar.
+   * @deprecated Since 19.0.0. The Redwood design system does not allow this to be customized.
+   */
+  labelContextMenu: string;
   /**
    * Provides properties to customize the context menu cut label.
    * @deprecated Since 18.0.0. The Redwood design system does not allow this to be customized.
    */
   labelCut: string;
+  /**
+   * The context menu move left label.
+   * @deprecated Since 19.0.0. The Redwood design system does not allow this to be customized.
+   */
+  labelMoveLeft: string;
+  /**
+   * The context menu move right label.
+   * @deprecated Since 19.0.0. The Redwood design system does not allow this to be customized.
+   */
+  labelMoveRight: string;
   /**
    * Provides properties to customize the context menu paste after label.
    * @deprecated Since 18.0.0. The Redwood design system does not allow this to be customized.

package/src/elements/oj-table/OjTableBase.ts

@@ -581,6 +581,10 @@ export interface DndDropRows {
    * A data type or an array of data types this element can accept.
    */
   dataTypes: string | Array<string>;
+  /**
+   * The drop positions this Table supports. Default is ['before'].
+   */
+  positions: Array<unknown | unknown>;
 }
 export interface DndReorder {
   /**
@@ -866,4 +870,8 @@ export interface Translations {
    * Used for the default required icon tooltip.
    */
   tooltipRequired: string;
+  /**
+   * Used for the separators in the default header tooltip.
+   */
+  tooltipSeparator: string;
 }

package/src/elements/oj-thematic-map/OjThematicMapBase.ts

@@ -386,10 +386,12 @@ export interface Areas {
   shortDesc: string | null;
   /**
    * The CSS style class defining the style of the area.
+   * @deprecated Since 19.0.0. The svgClassName property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgClassName: string;
   /**
    * The CSS style object defining the style of the area. Only SVG CSS style properties are supported.
+   * @deprecated Since 19.0.0. The svgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgStyle: object;
 }
@@ -424,10 +426,12 @@ export interface Links {
   startLocation: LinksStartLocation;
   /**
    * The CSS style class defining the style of the link.
+   * @deprecated Since 19.0.0. The svgClassName property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgClassName: string;
   /**
    * The CSS style object defining the style of the link. Only SVG CSS style properties are supported.
+   * @deprecated Since 19.0.0. The svgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgStyle: object;
   /**
@@ -445,11 +449,11 @@ export interface LinksEndLocation {
    */
   location: string;
   /**
-   * The x coordinate which can represent latitude of the end point.
+   * The x coordinate which can represent longitude of the end point.
    */
   x: number;
   /**
-   * The y coordinate which can represent longitude of the end point.
+   * The y coordinate which can represent latitude of the end point.
    */
   y: number;
 }
@@ -463,11 +467,11 @@ export interface LinksStartLocation {
    */
   location: string;
   /**
-   * The x coordinate which can represent latitude of the start point.
+   * The x coordinate which can represent longitude of the start point.
    */
   x: number;
   /**
-   * The y coordinate which can represent longitude of the start point.
+   * The y coordinate which can represent latitude of the start point.
    */
   y: number;
 }
@@ -578,10 +582,12 @@ export interface Markers {
   sourceSelected: string;
   /**
    * The CSS style class defining the style of the marker.
+   * @deprecated Since 19.0.0. The svgClassName property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgClassName: string;
   /**
    * The CSS style object defining the style of the marker. Only SVG CSS style properties are supported.
+   * @deprecated Since 19.0.0. The svgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgStyle: object;
   /**
@@ -604,6 +610,7 @@ export interface Markers {
 export interface StyleDefaults {
   /**
    * The CSS style object defining the style of the area layer areas.
+   * @deprecated Since 19.0.0. The areaSvgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   areaSvgStyle: object;
   /**

package/src/elements/oj-timeline/OjTimelineBase.ts

@@ -270,6 +270,7 @@ export interface MajorAxis {
   scale: string;
   /**
    * The CSS style object defining any additional styling of the major axis.
+   * @deprecated Since 19.0.0. The svgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgStyle: object;
 }
@@ -322,6 +323,7 @@ export interface MinorAxis {
   scale: string;
   /**
    * The CSS style object defining any additional styling of the minor axis.
+   * @deprecated Since 19.0.0. The svgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgStyle: object;
   /**
@@ -374,6 +376,7 @@ export interface Overview {
   rendered: string;
   /**
    * The CSS style object defining any additional styling of the overview.
+   * @deprecated Since 19.0.0. The svgStyle property is deprecated. This API is not recommended in Redwood theme. Use other customization APIs where appropriate.
    */
   svgStyle: object;
 }

package/src/elements/oj-waterfall-layout/OjWaterfallLayoutBase.ts

@@ -7,6 +7,16 @@ import { OjWebElement } from '../';
  * Put overrides into the WebElements's subclass, OjWaterfallLayout.ts.
  */
 export class OjWaterfallLayoutBase extends OjWebElement {
+  /**
+   * Gets the value of <code>cardSizing</code> property.
+   * Specifies whether the card size stays the same or can change dynamically during runtime. See the Help documentation for more information.
+   * @return The value of <code>cardSizing</code> property.
+   *
+   */
+  public getCardSizing(): Promise<string> {
+    return this.getProperty<string>('cardSizing');
+  }
+
   /**
    * Gets the value of <code>scrollPolicy</code> property.
    * Specifies how data are fetched as user scrolls towards the bottom of the grid.
@@ -69,7 +79,7 @@ export interface ScrollPosition {
   /**
    * The key of the item. If DataProvider is used for data and the key does not exist in the DataProvider or if the item has not been fetched yet, then the value is ignored.
    */
-  key: any;
+  key: string | number;
   /**
    * The vertical offset in pixels relative to the item identified by key.
    */

package/src/index.ts

@@ -19,22 +19,16 @@ import {
   OjFetch
 } from './lib/OjFetch';
 
-import { checkVersions } from './lib/version-check';
-import { Expectation } from './lib/Expectation';
-import * as sm from './lib/ScreenshotManager';
 import { getBusyStates, pageReady } from './lib/busy-context-utils';
 import { assertViewModelValue } from './lib/viewmodel-utils';
 import { isNoRequireJet, setNoRequireJet } from './lib/no-require-jet';
 
-// Export register function before importing elements so that they can
-// call it to register themselves
 export { fetchKeyByFilter } from './lib/dataprovider-utils';
-export { DriverManager } from './lib/driver-manager';
+export { DriverManager, type DriverConfiguration } from './lib/driver-manager';
 export { register } from './lib/driver-override';
-export type { SlotProxy } from './lib/slot-proxy';
-export { slotProxy } from './lib/slot-proxy';
-export { sm as ScreenshotManager };
-export { Expectation };
+export { type SlotProxy, slotProxy } from './lib/slot-proxy';
+export * as ScreenshotManager from './lib/ScreenshotManager';
+export { Expectation } from './lib/Expectation';
 
 /**
  * This interface describes the functions that are needed from the driver object
@@ -97,11 +91,10 @@ const ojwd = {
     const timeouts = await driver.manage().getTimeouts();
     try {
       await driver.wait(pageReady(), timeouts.pageLoad);
-      await checkVersions(driver);
     } catch (ex) {
       if (ex instanceof error.TimeoutError || ex instanceof error.ScriptTimeoutError) {
         const openStates = await getBusyStates(driver);
-        ex.message += ` - open busy states: ${openStates}`;
+        ex.message += `\nBusy states: ${openStates}`;
       }
       throw ex;
     }

package/src/lib/busy-context-utils.ts

@@ -1,5 +1,9 @@
 import { Condition, WebDriver, error } from 'selenium-webdriver';
 import { executeWithModules, TEST_OBJ_NAME } from './oj-module-proxy';
+// the relative path to package.json is correct when run from dist/ folder
+const wdPkg = require('../package.json');
+
+type VersionDef = { version: string; revision: string };
 
 /**
  * Get open busy state descriptions from the page context
@@ -11,7 +15,10 @@ export const getBusyStates = async (driver: WebDriver): Promise<string> => {
   const hasProxy = await driver.executeScript<boolean>(`return '${TEST_OBJ_NAME}' in window`);
   if (hasProxy) {
     return executeWithModules<string>(driver, ['BusyContext'], [], (BusyContext) =>
-      BusyContext.getBusyStates().map((state: { description: string }) => state.description)
+      BusyContext.getBusyStates().map(
+        (state: { description: string; stack: string }) =>
+          `${state.description}${state.stack ? '\n' + state.stack : ''}`
+      )
     ).catch((ex) => ex.message);
   }
   return '';
@@ -21,18 +28,42 @@ export const getBusyStates = async (driver: WebDriver): Promise<string> => {
  * Returns a Promise that is resolved when the application's busy
  * state reports ready or the page is not a JET page (RequireJS
  * or ojs/ojcontext module not available).
+ * This method also checks that the JET UI version matches oraclejet-webdriver
  * @private
  * @param driver WebDriver instance
  * @return A Promise which is resolved to true when the
  * page's busy state is ready or to false when it is not a JET page.
  */
 export const whenBusyContextReady = async (driver: WebDriver): Promise<boolean> => {
-  return executeWithModules<boolean>(driver, ['BusyContext'], [], (BusyContext) =>
-    BusyContext.whenReady()
+  return executeWithModules<boolean>(
+    driver,
+    ['BusyContext', 'Core'],
+    [{ version: wdPkg.version, revision: wdPkg.config.revision }],
+    (BusyContext, Core, { version, revision }: VersionDef) => {
+      // inline the version-check to avoid additional timing changes with making another
+      // remote script call
+      if (
+        // Check if not local build (running from JET repo)
+        !revision.match(/^#@@oj\.revision@@#$|^local:/) &&
+        // or version mismatch
+        (version !== Core.version || revision !== Core.revision)
+      ) {
+        throw Error(
+          `version mismatch: oraclejet ${JSON.stringify({
+            version: Core.version,
+            revision: Core.revision
+          })}, oraclejet-webdriver ${JSON.stringify({ version, revision })}`
+        );
+      }
+
+      return BusyContext.whenReady();
+    }
   ).catch(async (ex) => {
     if (ex instanceof error.TimeoutError || ex instanceof error.ScriptTimeoutError) {
       const openStates = await getBusyStates(driver);
       throw Error(`BusyContext.whenReady() timed out: ${ex.message}\nBusy states: ${openStates}`);
+    } else if (ex.message?.indexOf('version mismatch:') > -1) {
+      throw ex;
     } else {
       // unexpected error which is just reported as a warning below
       return false;

package/src/lib/driver-manager.ts

@@ -1,350 +1,9 @@
-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;
-}
-interface CapabilitiesConfiguration {
-  /**
-   * The WebDriver Capabilties for the configuration
-   */
-  capabilities?: Capabilities | Map<string, any> | {};
-  /**
-   * The WebDriver timeout values for the configuration
-   */
-  timeouts?: Timeouts;
-}
-
-/**
- * @private
- */
-const defaultConfigName = '';
-/**
- * @private
- */
-const defaultCapabilities = new Capabilities({
-  autoWebview: true,
-  browserName: 'chrome'
-});
-/**
- * @private
- */
-const defaultTimeouts: Timeouts = {
-  implicit: 0,
-  pageLoad: 30000,
-  script: 30000
-};
-/**
- * @private
- */
-const configs: { [key: string]: CapabilitiesConfiguration } = {};
-/**
- * @private
- */
-let currentInstance: { configName: string | undefined; driver: WebDriver | undefined } = {
-  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: 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);
-/**
- * @private
- */
-let quitPromise = Promise.resolve();
-
-/**
- * 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-webdriver";
- *
- * 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-webdriver";
- *
- * 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 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
-   */
-  public static setBuilder(b: Builder) {
-    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.
-   *
-   * ### Register a default config
-   * ```javascript
-   * DriverManager.registerConfig(
-   *   {
-   *     capabilities: new Capabilities({
-   *       browserName: "chrome"
-   *     }),
-   *     timeouts: {
-   *       implicit: 5000
-   *     }
-   *   }
-   * );
-   * ```
-   * ### Register a Firefox config
-   * ```javascript
-   * DriverManager.registerConfig(
-   *   {
-   *     capabilities: new Capabilities({
-   *       browserName: "firefox",
-   *       hideAlerts: true
-   *     })
-   *   },
-   *   "firefox-no-alerts"
-   * );
-   * ```
-   */
-  public static registerConfig(config: CapabilitiesConfiguration, name?: string): void {
-    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.
-   */
-  public static async getDriver(configName?: string): Promise<WebDriver> {
-    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 (ex) {}
-    }
-
-    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.
-   */
-  public static async getCurrentDriver(): Promise<WebDriver> {
-    return DriverManager.getDriver(currentInstance.configName);
-  }
-
-  /**
-   * Release the WebDriver instance from use.  Called when each test is done
-   * with its driver usage, typicall, in the Mocha <code>after</code> function.
-   * @param driver The WebDriver instance
-   */
-  public static releaseDriver(driver: WebDriver): void {
-    clearTimeout(releaseTimer);
-    // Wait for the delay to quit the driver. If [getDriver] was called before
-    // the timeout expired, then it will have cleared the timeout so that the
-    // instance isn't closed.
-    releaseTimer = setTimeout(() => quitDriver(driver), quitDelay);
-  }
-}
-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
- */
-function createDriver(configName: string) {
-  const config = configs[configName];
-  if (!config) {
-    throw Error(`No driver configuration exists for "${configName}"`);
-  }
-  // Merge default capabilities with custom ones
-  const caps = new 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 Builder();
-  }
-
-  return quitPromise.then(async () => {
-    const driver = builder.withCapabilities(caps).build();
-    currentInstance = { configName, driver };
-    await driver.manage().setTimeouts(timeouts);
-    return driver;
-  });
-}
-
-/**
- * @private
- */
-function quitCurrentDriver() {
-  quitDriver(currentInstance.driver);
-}
-
-/**
- * @private
- */
-function quitDriver(driver?: WebDriver) {
-  if (driver) {
-    currentInstance = {
-      configName: undefined,
-      driver: undefined
-    };
-    quitPromise = driver.quit().catch((ex) => console.warn(ex));
-  }
-}
+/*
+ * Although DriverManager has moved to oraclejet-selenium-driver package, re-export
+ * from its original location in case other projects are importing it directly from
+ * this folder.
+ */
+export {
+  DriverManager,
+  type DriverConfiguration
+} from '@oracle/oraclejet-selenium-driver/DriverManager';

package/src/lib/driver-override.ts

@@ -86,10 +86,13 @@ WebDriver.prototype.executeAsyncScript = wrapExecuteScript(WebDriver.prototype.e
 function getWebDriverErrors() {
   return Object.keys(WebDriverErrors)
     .filter((c) => c.match(/^[A-Z].+Error$/))
-    .reduce((accum, className) => {
-      accum[className] = new WebDriverErrors[className]();
-      return accum;
-    }, {});
+    .reduce(
+      (accum, className) => ({
+        ...accum,
+        [className]: new WebDriverErrors[className]()
+      }),
+      {}
+    );
 }
 
 /**

package/tsconfig.json

@@ -12,11 +12,11 @@
     "noPropertyAccessFromIndexSignature": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
-    "module": "commonjs",
+    "module": "Node16",
+    "moduleResolution": "node16",
     "target": "ES2021",
     "sourceMap": true,
     "skipLibCheck": true,
-    "moduleResolution": "node",
     "types": ["node", "selenium-webdriver"],
     "paths": {
       "@oracle/oraclejet/*": ["./node_modules/@oracle/oraclejet/dist/types/*"]