@oracle/oraclejet-webdriver 10.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Oracle Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -0,0 +1,16 @@
+# Oracle JET Component WebElements
+Usage:
+
+```javascript
+import ojwd from '@oracle/oraclejet-webdriver';
+import {ojInputText, ...} from '@oracle/oraclejet-webdriver/elements';
+
+describe('My suite of tests', function() {
+  it('can use Component WebElements', async function() {
+    let input = await ojInputText(driver, By.id('text-input-1'));
+    ...
+  })
+})
+```
+
+See [Testing JET UIs With WebDriver](https://confluence.oraclecorp.com/confluence/display/JET/Testing+JET+UIs+With+WebDriver) for details.

package/bin/generate

@@ -0,0 +1,509 @@
+#!/usr/bin/env node
+
+/**
+ * Generate a component WebElement package from its metadata descriptor
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Map known types to an output type. Used by getSanitizedType() to ensure that
+// component types can be mapped to valid TypeScript types.
+const KNOWN_TYPES = {
+  // Known good types
+  boolean: 'boolean',
+  null: 'null',
+  number: 'number',
+  object: 'object',
+  string: 'string',
+  tuple: 'tuple',
+  undefined: 'undefined',
+  void: 'void',
+  any: 'any',
+  // Known bad types. Convert to valid types
+  function: 'null',
+  promise: 'null',
+  array: 'Array<unknown>'
+};
+// Map of reserved property names. Used to ensure that a superclass's mutator
+// isn't overridden by one generated from properties.
+const RESERVED_PROPS = {
+  metadata: 'metadataProperty',
+  size: 'sizeProperty',
+  text: 'textProperty'
+};
+
+const node = process.argv.shift();
+const cmd = process.argv.shift();
+const mdPath = process.argv.shift();
+let pkgDir = process.argv.shift() || '.';
+
+if (!mdPath) {
+  console.log(
+    '\nUsage: ' + path.basename(cmd) + ' <metadata|-> [<output dir>]'
+  );
+  console.log('\nwhere <metadata> is one of:');
+  console.log('\t- a file path to component metadata (component.json)');
+  console.log('\t- "-" read metadata from stdin');
+  return;
+}
+
+const templateDir = path.dirname(cmd) + path.sep + 'templates';
+
+let className;
+// Main function, executed as async IIFE so that we can await on getMetadata()
+(async function() {
+  const mdContents = await getMetadata(mdPath);
+  const md = JSON.parse(mdContents);
+  const name = md.name;
+  const version = md.version || '0.0.1';
+  className = titleCase(name);
+  const camelName = camelCase(name);
+  const props = md.properties;
+
+  // Package output dir is CCA's name
+  pkgDir += path.sep + name;
+  mkDirParents(pkgDir);
+
+  // Copy package.json files
+  copy(
+    templateDir + path.sep + 'package.json-template',
+    pkgDir + path.sep + 'package.json',
+    {
+      '@NAME@': name,
+      '@CLASSNAME@': className,
+      '@VERSION@': version
+    }
+  );
+  // Copy tsconfig.json
+  copy(
+    templateDir + path.sep + 'tsconfig.json-template',
+    pkgDir + path.sep + 'tsconfig.json'
+  );
+
+  // Create baseclass.ts content
+  let content = [];
+  let types = [];
+  Object.keys(props || {}).forEach(propName => {
+    const properties = props[propName];
+    const typeDef = getTypeDefinition(propName, properties);
+    let type = typeDef.type;
+    const desc = getHTMLEscapedText(properties.description) || '';
+
+    if (type) {
+      // Extended properties for "object" type
+      if (typeDef.typeDecl.length) {
+        types = types.concat(typeDef.typeDecl);
+      }
+      // Writeback propertyes get "changeNNN" function
+      if (properties && properties.writeback && !properties.readOnly) {
+        content = content.concat(indent(getSetterContent(propName, type, desc)));
+      }
+      content = content.concat(indent(getGetterContent(propName, type, desc)));
+    }
+  });
+
+  // If extended properties for "object" type, wrap definitions in namespace
+  if (types.length) {
+    indent(types);
+    types.unshift(`\nnamespace ${className}Base {`);
+    types.push('}');
+  }
+
+  copy(
+    templateDir + path.sep + 'baseclass.ts-template',
+    pkgDir + path.sep + className + 'Base.ts',
+    {
+      '@CLASSNAME@': className,
+      '@CONTENT@': content.join('\n'),
+      '@TYPES@': types.join('\n')
+    }
+  );
+
+  copy(
+    templateDir + path.sep + 'class.ts-template',
+    pkgDir + path.sep + className + '.ts',
+    {
+      '@NAME@': name,
+      '@CLASSNAME@': className,
+      '@CAMELNAME@': camelName
+    }
+  );
+  copy(
+    templateDir + path.sep + 'index.ts-template',
+    pkgDir + path.sep + 'index.ts',
+    {
+      '@NAME@': name,
+      '@CLASSNAME@': className,
+      '@CAMELNAME@': camelName
+    }
+  );
+
+  copy(
+    templateDir + path.sep + 'element-test.spec.ts-template',
+    pkgDir + path.sep + 'element-test.spec.ts',
+    {
+      '@NAME@': name,
+      '@CAMELNAME@': camelName
+    }
+  );
+
+  console.log('Generated WebElement package in ' + pkgDir);
+})();
+
+/**
+ * Get the data type for the given declared type.  This function ensures that
+ * the declared type is legal in TypeScript by checking for known types in JET
+ * components that should be mapped to others.
+ * @param {string} name The property's name
+ * @param {object} props The property's object describing itself
+ * @return {object} An object describing the data type.  Object keys are "type" "typeDecl"
+ * <code>
+ *  {
+ *    "type": string,
+ *    "typeDecl": string[]
+ *  }
+ * </code>
+ */
+function getTypeDefinition(name, props) {
+  const origType = getSanitizedType(props.type);
+  const types = (origType || '').split('|');
+  let decls = [];
+  // Iterate through all types if multiples exist ("string|number|...")
+  types.forEach(function(type, i) {
+    if (type.match(/^object$|Array<object>/i)) {
+      const decl = getObjectType(name, type, props);
+      types[i] = decl.type;
+      decls = decls.concat(decl.typeDecl);
+    }
+  });
+  return {
+    type: types.join('|'),
+    typeDecl: decls
+  };
+}
+
+/**
+ * Get the data type for the given declared type.  This function ensures that
+ * the declared type is legal in TypeScript by checking for known types in JET
+ * components that should be mapped to others.
+ * JET-specific types such as KeySet, DataProvider cannot be converted to TypeScript,
+ * and this function will return 'undefined' or anything it doesn't know about.
+ * @param {string} origType The original delcared data type
+ * @return {string} The data type inferred from the declared type, or undefined
+ * if no known good type exists.
+ */
+function getSanitizedType(origType) {
+  if (!origType) {
+    return origType;
+  }
+  // Check for multiple types "string|number|object ..."
+  if (origType.indexOf('|') > -1) {
+    let parts = [];
+    origType.split('|').forEach(type => {
+      type = getSanitizedType(type);
+      type && parts.push(type);
+    });
+    return parts.join('|');
+  }
+  // Check against KNOWN_TYPES for mapped data type
+  let sanitizedType = KNOWN_TYPES[origType.toLowerCase()];
+  // Parameterized types
+  const typeParams = origType.match(/([a-z\.]+)<(.+?)>/i);
+  if (typeParams) {
+    const generic = typeParams[1];
+    const params = typeParams[2];
+    // Paramterized Object not supported
+    if (generic.match(/^object/i)) {
+      sanitizedType = 'unknown';
+    }
+    else {
+      // Get sanitized type for each param type
+      const paramTypes = [];
+      params.split(',').forEach(p => {
+        const sp = getSanitizedType(p);
+        sp && paramTypes.push(sp);
+      });
+      if (paramTypes.length) {
+        sanitizedType = `${generic}<${paramTypes.join(',')}>`;
+      }
+    }
+  }
+  return sanitizedType;
+}
+
+/**
+ * Given a property whose type is "object" or "Array<object>", get its Type
+ * definition.
+ * @param {string} name The property's name
+ * @param {string} type The property's type
+ * @param {object} props The property descriptor, whose own "properties" object will
+ * be converted to a type declaration
+ * @return {object} An object containing the Type declaration for the properties, i.e.
+ * "type" - a type string
+ * "typeDecl" - array of strings containing any type definitions for the generic
+ * object types
+ */
+function getObjectType(name, type, props) {
+  let buf = [];
+  const typeProps = type.match(/^array</i)
+    ? getProperty('extension.vbdt.itemProperties', props)
+    : props.properties;
+
+  if (typeProps) {
+    const typeInArray = type.match(/^Array/);
+    type = titleCase(name);
+    buf.push('export interface ' + type + ' {');
+    // Add on namespace to type
+    type = `${className}Base.${type}`;
+    if (typeInArray) {
+      type = 'Array<' + type + '>';
+    }
+    let nestedDecl = [];
+    // Iterate through all property types and build their definitions
+    Object.keys(typeProps).forEach(prop => {
+      const desc = getHTMLEscapedText(typeProps[prop].description) || '';
+      let type = getSanitizedType(typeProps[prop].type);
+      // Nested object type
+      if (type && type.match(/object|Array<object>/i)) {
+        const decl = getObjectType(
+          name + titleCase(prop),
+          type,
+          typeProps[prop]
+        );
+        type = decl.type;
+        nestedDecl = nestedDecl.concat(decl.typeDecl);
+      }
+      if (type && type !== 'null') {
+        buf = buf.concat(indent(['/**', ' * ' + desc, ' */']));
+        buf = buf.concat(indent(['"' + prop + '": ' + type + ';']));
+      }
+    });
+    buf.push('}');
+    buf = buf.concat(nestedDecl);
+  }
+  return {
+    type: type,
+    typeDecl: buf
+  };
+}
+
+/**
+ * Convenience function to retrieve a property within an object using dot-notation.
+ * This is espcially useful when a nested property's parents MAY NOT exist, and
+ * we don't want to have to test for every parent level to get to the property.
+ * @param {string} propName The dot-notated property name
+ * @param {object} obj The root object in which to search for the property
+ * @return {any} The property value
+ */
+function getProperty(propName, obj) {
+  if (!obj) {
+    return obj;
+  }
+  if (propName in obj) {
+    return obj[propName];
+  } else if (propName.match(/\./)) {
+    const parts = propName.split('.');
+    const root = parts.shift();
+    return getProperty(parts.join('.'), obj[root]);
+  }
+}
+
+/**
+ * Ensure that the given text is sanitized so that it can be displayed as markup.
+ * @param {string} text The text to be sanitized
+ * @return {string} The HTML-sanitized text
+ */
+function getHTMLEscapedText(text) {
+  text = (text || '').replace(/</g, '&lt;');
+  return text;
+}
+
+/**
+ * Convenience function to create a nested directory and all of its parents, if
+ * necessary. Equivalent to "mkdir -p my/child/dir"
+ * @param {string} dirname The path-separated directory name
+ */
+function mkDirParents(dirname) {
+  // Loop thru dirnames to make parent dirs
+  const parents = [];
+  dirname.split(path.sep).forEach(function(dir) {
+    try {
+      parents.push(dir);
+      fs.mkdirSync(parents.join(path.sep));
+    } catch (e) {}
+  });
+}
+
+/**
+ * Get the accessor function name for the given property
+ * @param {string} prop The property name
+ * @return {string} The property's accessor name
+ */
+function getGetterName(prop) {
+  prop = getAlternativePropName(prop);
+  return 'get' + titleCase(prop);
+}
+/**
+ * Get the mutator functio nname for the given property
+ * @param {string} prop The property name
+ * @return {string} The property's mutator name
+ */
+function getSetterName(prop) {
+  prop = getAlternativePropName(prop);
+  return 'change' + titleCase(prop);
+}
+/**
+ * Get an alternate name for the given property name, if one exists. This function
+ * checks against reserved property names which shouldn't be overridden. If the
+ * given property name is reserved, it will return an alternative name, otherwise,
+ * it will return the same (given) name.
+ * @param {string} prop The property name
+ * @return {string} The alternative property name or the original one, if not
+ * reserved.
+ */
+function getAlternativePropName(prop) {
+  return RESERVED_PROPS[prop] || prop;
+}
+
+/**
+ * Get the contents of the accessor (getter) function for the given property.
+ * @param {string} prop The property name to be set
+ * @param {string} type The property type
+ * @param {string=} desc An optional description of the property
+ * @return {string} The getter function contents
+ */
+function getGetterContent(prop, type, desc) {
+  const func = getGetterName(prop);
+  return [
+    '/**',
+    ' * Gets the value of "' + prop + '" property.',
+    ' * ' + desc,
+    ' * @return The value of "' + prop + '" property.',
+    ' */',
+    'public ' + func + '(): Promise<' + type + '> {',
+    '  return this.getProperty<' + type + '>("' + prop + '");',
+    '}',
+    ''
+  ];
+}
+
+/**
+ * Get the contents of the mutator (setter) function for the given property.
+ * @param {string} prop The property name to be set
+ * @param {string} type The property type
+ * @param {string=} desc An optional description of the property
+ * @return {string} The setter function contents
+ */
+function getSetterContent(prop, type, desc) {
+  const func = getSetterName(prop);
+  return [
+    '/**',
+    ' * Sets the value of "' + prop + '" property.',
+    ' * ' + desc,
+    ' * @param ' + prop + ' The value to set for "' + prop + '"',
+    ' */',
+    'public ' + func + '(' + prop + ': ' + type + '): Promise<void> {',
+    '  return this.setProperty<' + type + '>("' + prop + '", ' + prop + ');',
+    '}',
+    ''
+  ];
+}
+
+/**
+ * Convert 'dashed-name' to 'dashedName'
+ * @param {string} name
+ * @return {string} The camel-cased name
+ */
+function camelCase(name) {
+  return name.replace(/[^a-z0-9](.)/gi, function(v) {
+    return v[1].toUpperCase();
+  });
+}
+
+/**
+ * Convert 'dashed-name' to 'DashedName'
+ * @param {string} name
+ * @return {string} The title-cased name
+ */
+function titleCase(name) {
+  name = camelCase(name);
+  return name.charAt(0).toUpperCase() + name.substring(1);
+}
+
+/**
+ * Indent lines by padding with the given number of spaces. This function modifies
+ * the contents of the original array inline.
+ * @param {string[]} src The original source array of lines to indent
+ * @param {number=} spaces Optional spaces to indent. Defaults to 2
+ * @return {Array<string>} The original src string[]
+ */
+function indent(src, spaces) {
+  if (spaces === undefined) {
+    spaces = 2;
+  }
+  for (let i = 0, len = src.length; i < len; i++) {
+    const line = src[i];
+    if (line) {
+      src[i] = new Array(spaces + 1).join(' ') + line;
+    }
+  }
+  return src;
+}
+
+/**
+ * Copy the contents of the source file to the destination, optionally substituting
+ * key values.  If the destination file exists, its contents won't be overwritten.
+ * @param {string} src The path to the source file
+ * @param {string} dest The path to the destination file
+ * @param {object} filters An object of filters to replace during the copy.  The
+ * object keys are the tokens to be replaced with their values.
+ */
+function copy(src, dest, filters) {
+  let contents = fs.readFileSync(src, 'utf8');
+  Object.keys(filters || {}).forEach(function(key) {
+    // Use function to return 'val' to prevent values containing RegExp
+    // patterns like "$&" from repeating the key
+    function val() { return filters[key]; }
+    while (contents.indexOf(key) > -1) {
+      contents = contents.replace(key, val);
+    }
+  });
+  fs.writeFileSync(dest, contents, { mode: 0o644 });
+}
+
+/**
+ * Get the metadata given the metadata path.  If the path is "-", read from stdin.
+ * @param {string} mdPath The path to the metadata.  Can be a file path or stdin.
+ * @return {string} The metadata JSON contents
+ */
+async function getMetadata(mdPath) {
+  let md;
+  if (mdPath === '-') {
+    md = await readStdin();
+  } else {
+    md = fs.readFileSync(mdPath, 'utf8');
+  }
+  return md;
+}
+
+/**
+ * Fetch the JET metadata object for the given element, whose name is embedded
+ * as the "&element=" parameter in the URL.
+ *
+ * @return Promise<string> A Promise which resolves to the metadata contents string
+ */
+function readStdin() {
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+
+  const md = [];
+  return new Promise(function(resolve, reject) {
+    process.stdin.on('data', chunk => {
+      md.push(chunk);
+    });
+    process.stdin.on('end', () => resolve(md.join('\n')));
+  });
+}

package/bin/generate-jet

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/*
+ * Iterate through JET component metadata files to generate WebElements.  This
+ * script takes either a directory, from which it will scan for all *.json files,
+ * or a single JSON file.
+ * The file(s) are passed to the "generate" utility to create the component
+ * WebElement package.
+ */
+const {spawnSync} = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const node = process.argv.shift();
+const cmd = process.argv.shift();
+let allComps = process.argv.shift();
+const pkgRoot = path.dirname(cmd)+path.sep+'..'
+const generate = [pkgRoot, 'bin', 'generate'].join(path.sep);
+const elements = pkgRoot+path.sep+'elements';
+const output = pkgRoot+path.sep+'generated';
+
+if (!allComps) {
+  console.log('\nUsage: ' +path.basename(cmd)+ ' <JET allComponents.json metadata file>');
+  return;
+}
+
+// Create 'generated' output dir--try/catch in case it already exists
+try {
+  fs.mkdirSync(output);
+} catch (ex) {
+  console.warn(ex.message);
+}
+
+const compUrlsFile = path.dirname(cmd)+path.sep+'templates'+path.sep+'jetcomponents.json';
+const compUrls = JSON.parse(fs.readFileSync(compUrlsFile), 'utf8');
+
+// Generate individual files from allComponents.json so that 'generate' script
+// can read them
+let files = [];
+const comps = JSON.parse(fs.readFileSync(allComps), 'utf8').components;
+Object.keys(comps).forEach((key) => {
+  let file = [output, key + '.json'].join(path.sep);
+  files.push(file);
+  let contents = JSON.stringify(comps[key], null, 2);
+  fs.writeFileSync(file, contents, {mode: 0o644});
+});
+
+files.forEach((absFile) => {
+  if (absFile.match(/\.json$/)) {
+    // Test if element name exists in whitelist
+    let md = JSON.parse(fs.readFileSync(absFile), 'utf8');
+    if (compUrls.indexOf(md.name) > -1) {
+      let out = spawnSync(node, [generate, absFile, output]);
+      const err = out.stderr.toString();
+      if (!err) {
+        postProcess(md.name);
+        console.log(out.output.join(''));
+      }
+      else {
+        throw err;
+      }
+    }
+  }
+});
+
+updateIndex();
+
+/**
+ * Post-process the 'generate' output files. Copies the generated content (from
+ * "generated" dir) to the repo directory, "elements."
+ * @param name The element tag name
+ */
+function postProcess(name) {
+  const className = titleCase(name);
+  const classFile = className+'.ts';
+  const elementDir = getElementDir(name);
+
+  if (!fs.existsSync(elementDir)) {
+    fs.mkdirSync(elementDir);
+  }
+
+  // index.ts - always replace
+  let indexFile = getOutputFile(name, 'index.ts');
+  let indexContent = fs.readFileSync(indexFile).toString();
+  indexContent = indexContent
+    .replace(/@oracle\/oraclejet-webdriver/g, '../../')
+  fs.writeFileSync(indexFile, indexContent);
+  fs.copyFileSync(indexFile, getElementFile(name, 'index.ts'));
+  // <ClassName>.ts - copy only if doesn't already exist
+  let classFilePath = getElementFile(name, classFile);
+  if (!fs.existsSync(classFilePath)) {
+    fs.copyFileSync(getOutputFile(name, classFile), classFilePath);
+  }
+  // <ClassName>Base.ts - always replace
+  const baseName = className+'Base';
+  let baseFile = getOutputFile(name, baseName+'.ts');
+  let baseContent = fs.readFileSync(baseFile).toString();
+  baseContent = baseContent
+    .replace(/@oracle\/oraclejet-webdriver\/elements/g, '../')
+  fs.writeFileSync(baseFile, baseContent);
+  fs.copyFileSync(baseFile, getElementFile(name, baseName+'.ts'));
+  // Remove unneeded files
+  fs.unlinkSync(getOutputFile(name, 'element-test.spec.ts'));
+  fs.unlinkSync(getOutputFile(name, 'package.json'));
+  fs.unlinkSync(getOutputFile(name, 'tsconfig.json'));
+}
+
+/**
+ * Update elements/index.ts to include all of the WebElements and their convenience
+ * functions to be exported.
+ */
+function updateIndex() {
+  const indexFile = `${elements}/index.ts`;
+  const buffer = [`/**
+ * This file aggregates all JET WebElements together into a single module, and
+ * is generated by the build. DO NOT hand-edit this file as its contents will be
+ * overwritten.
+ */
+export { ojWebElement, OjWebElement } from "./OjWebElement";`
+  ];
+  fs.readdirSync(elements).forEach(dir => {
+    // Test if "index.ts" exists under the directory
+    if (fs.existsSync(`${elements}${path.sep}${dir}${path.sep}index.ts`)) {
+      const className = titleCase(dir);
+      const helperName = camelCase(dir);
+      buffer.push(
+        `export { ${helperName}, ${className} } from "./${dir}";`
+      );
+    }
+  });
+  fs.writeFileSync(indexFile, buffer.join('\n'));
+}
+
+function getOutputFile(name, file) {
+  return output + path.sep + name + path.sep + file;
+}
+function getElementDir(name) {
+  return elements + path.sep + name;
+}
+function getElementFile(name, file) {
+  return getElementDir(name) + path.sep + file;
+}
+
+/**
+ * Convert 'dashed-name' to 'dashedName'
+ * @param {string} name
+ */
+function camelCase(name) {
+  return name.replace(/[^a-z0-9](.)/ig, function(v) {
+    return v[1].toUpperCase()
+  });
+}
+
+/**
+ * Convert 'dashed-name' to 'DashedName'
+ * @param {string} name
+ */
+function titleCase(name) {
+  name = camelCase(name);
+  return name.charAt(0).toUpperCase()+name.substring(1);
+}