feat(cdk-experimental/testing): Bring in component harness

Co-Authored-By: Yi Qi <[email protected]>
Co-Authored-By: Rado Kirov <[email protected]>
Co-Authored-By: Thomas Shafer <[email protected]>
Co-Authored-By: Caitlin Mott <[email protected]>
Co-Authored-By: Craig Nishina <[email protected]>

Author: 6 people

src/cdk-experimental/testing/component-harness.ts

@@ -0,0 +1,213 @@
+/**
+ * Test Element interface
+ * This is a wrapper of native element
+ */
+export interface TestElement {
+  blur(): Promise<void>;
+  clear(): Promise<void>;
+  click(): Promise<void>;
+  focus(): Promise<void>;
+  getCssValue(property: string): Promise<string>;
+  hover(): Promise<void>;
+  sendKeys(keys: string): Promise<void>;
+  text(): Promise<string>;
+  getAttribute(name: string): Promise<string|null>;
+}
+
+/**
+ * Extra searching options used by searching functions
+ *
+ * @param allowNull Optional, whether the found element can be null. If
+ * allowNull is set, the searching function will always try to fetch the element
+ * at once. When the element cannot be found, the searching function should
+ * return null if allowNull is set to true, throw an error if allowNull is set
+ * to false. If allowNull is not set, the framework will choose the behaviors
+ * that make more sense for each test type (e.g. for unit test, the framework
+ * will make sure the element is not null; otherwise throw an error); however,
+ * the internal behavior is not guaranteed and user should not rely on it. Note
+ * that in most cases, you don't need to care about whether an element is
+ * present when loading the element and don't need to set this parameter unless
+ * you do want to check whether the element is present when calling the
+ * searching function. e.g. you want to make sure some element is not there when
+ * loading the element in order to check whether a "ngif" works well.
+ *
+ * @param global Optional. If global is set to true, the selector will match any
+ *     element on the page and is not limited to the root of the harness. If
+ * global is unset or set to false, the selector will only find elements under
+ * the current root.
+ */
+export interface Options {
+  allowNull?: boolean;
+  global?: boolean;
+}
+
+/**
+ * Type narrowing of Options to allow the overloads of ComponentHarness.find to
+ * return null only if allowNull is set to true.
+ */
+interface OptionsWithAllowNullSet extends Options {
+  allowNull: true;
+}
+
+/**
+ * Locator interface
+ */
+export interface Locator {
+  /**
+   * Get the host element of locator.
+   */
+  host(): TestElement;
+
+  /**
+   * Search the first matched test element.
+   * @param css Selector of the test elements.
+   * @param options Optional, extra searching options
+   */
+  find(css: string, options?: Options): Promise<TestElement|null>;
+
+  /**
+   * Search all matched test elements under current root by css selector.
+   * @param css Selector of the test elements.
+   */
+  findAll(css: string): Promise<TestElement[]>;
+
+  /**
+   * Load the first matched Component Harness.
+   * @param componentHarness Type of user customized harness.
+   * @param root Css root selector of the new component harness.
+   * @param options Optional, extra searching options
+   */
+  load<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>, root: string,
+    options?: Options): Promise<T|null>;
+
+  /**
+   * Load all Component Harnesses under current root.
+   * @param componentHarness Type of user customized harness.
+   * @param root Css root selector of the new component harnesses.
+   */
+  loadAll<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>, root: string): Promise<T[]>;
+}
+
+/**
+ * Base Component Harness
+ * This base component harness provides the basic ability to locate element and
+ * sub-component harness. It should be inherited when defining user's own
+ * harness.
+ */
+export class ComponentHarness {
+  constructor(private readonly locator: Locator) {}
+
+  /**
+   * Get the host element of component harness.
+   */
+  host(): TestElement {
+    return this.locator.host();
+  }
+
+  /**
+   * Generate a function to find the first matched test element by css
+   * selector.
+   * @param css Css selector of the test element.
+   */
+  protected find(css: string): () => Promise<TestElement>;
+
+  /**
+   * Generate a function to find the first matched test element by css
+   * selector.
+   * @param css Css selector of the test element.
+   * @param options Extra searching options
+   */
+  protected find(css: string, options: OptionsWithAllowNullSet):
+    () => Promise<TestElement|null>;
+
+  /**
+   * Generate a function to find the first matched test element by css
+   * selector.
+   * @param css Css selector of the test element.
+   * @param options Extra searching options
+   */
+  protected find(css: string, options: Options): () => Promise<TestElement>;
+
+  /**
+   * Generate a function to find the first matched Component Harness.
+   * @param componentHarness Type of user customized harness.
+   * @param root Css root selector of the new component harness.
+   */
+  protected find<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>,
+    root: string): () => Promise<T>;
+
+  /**
+   * Generate a function to find the first matched Component Harness.
+   * @param componentHarness Type of user customized harness.
+   * @param root Css root selector of the new component harness.
+   * @param options Extra searching options
+   */
+  protected find<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>, root: string,
+    options: OptionsWithAllowNullSet): () => Promise<T|null>;
+
+  /**
+   * Generate a function to find the first matched Component Harness.
+   * @param componentHarness Type of user customized harness.
+   * @param root Css root selector of the new component harness.
+   * @param options Extra searching options
+   */
+  protected find<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>, root: string,
+    options: Options): () => Promise<T>;
+
+  protected find<T extends ComponentHarness>(
+    cssOrComponentHarness: string|ComponentHarnessType<T>,
+    cssOrOptions?: string|Options,
+    options?: Options): () => Promise<TestElement|T|null> {
+    if (typeof cssOrComponentHarness === 'string') {
+      const css = cssOrComponentHarness;
+      const options = cssOrOptions as Options;
+      return () => this.locator.find(css, options);
+    } else {
+      const componentHarness = cssOrComponentHarness;
+      const css = cssOrOptions as string;
+      return () => this.locator.load(componentHarness, css, options);
+    }
+  }
+
+  /**
+   * Generate a function to find all matched test elements by css selector.
+   * @param css Css root selector of elements. It will locate
+   * elements under the current root.
+   */
+  protected findAll(css: string): () => Promise<TestElement[]>;
+
+  /**
+   * Generate a function to find all Component Harnesses under current
+   * component harness.
+   * @param componentHarness Type of user customized harness.
+   * @param root Css root selector of the new component harnesses. It will
+   * locate harnesses under the current root.
+   */
+  protected findAll<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>,
+    root: string): () => Promise<T[]>;
+
+  protected findAll<T extends ComponentHarness>(
+    cssOrComponentHarness: string|ComponentHarnessType<T>,
+    root?: string): () => Promise<TestElement[]|T[]> {
+    if (typeof cssOrComponentHarness === 'string') {
+      const css = cssOrComponentHarness;
+      return () => this.locator.findAll(css);
+    } else {
+      const componentHarness = cssOrComponentHarness;
+      return () => this.locator.loadAll(componentHarness, root as string);
+    }
+  }
+}
+
+/**
+ * Type of ComponentHarness.
+ */
+export interface ComponentHarnessType<T extends ComponentHarness> {
+  new(locator: Locator): T;
+}

src/cdk-experimental/testing/protractor.ts

@@ -0,0 +1,182 @@
+import {browser, by, element, ElementFinder} from 'protractor';
+import {promise as wdpromise} from 'selenium-webdriver';
+
+import {ComponentHarness, ComponentHarnessType, Locator, Options, TestElement} from './component-harness';
+
+/**
+ * Component harness factory for protractor.
+ * The function will not try to fetch the host element of harness at once, which
+ * is for performance purpose; however, this is the most common way to load
+ * protractor harness. If you do care whether the host element is present when
+ * loading harness, using the load function that accepts extra searching
+ * options.
+ * @param componentHarness: Type of user defined harness.
+ * @param rootSelector: Optional. Css selector to specify the root of component.
+ * Set to 'body' by default
+ */
+export async function load<T extends ComponentHarness>(
+  componentHarness: ComponentHarnessType<T>,
+  rootSelector: string): Promise<T>;
+
+/**
+ * Component harness factory for protractor.
+ * @param componentHarness: Type of user defined harness.
+ * @param rootSelector: Optional. Css selector to specify the root of component.
+ * Set to 'body' by default.
+ * @param options Optional. Extra searching options
+ */
+export async function load<T extends ComponentHarness>(
+  componentHarness: ComponentHarnessType<T>, rootSelector?: string,
+  options?: Options): Promise<T|null>;
+
+export async function load<T extends ComponentHarness>(
+  componentHarness: ComponentHarnessType<T>, rootSelector = 'body',
+  options?: Options): Promise<T|null> {
+  const root = await getElement(rootSelector, undefined, options);
+  if (root === null) {
+    return null;
+  }
+  const locator = new ProtractorLocator(root);
+  return new componentHarness(locator);
+}
+
+/**
+ * Gets the corresponding ElementFinder for the root of a TestElement.
+ */
+export function getElementFinder(testElement: TestElement): ElementFinder {
+  if (testElement instanceof ProtractorElement) {
+    return testElement.element;
+  }
+
+  throw new Error('Invalid element provided');
+}
+
+class ProtractorLocator implements Locator {
+  private root: ProtractorElement;
+  constructor(private rootFinder: ElementFinder) {
+    this.root = new ProtractorElement(this.rootFinder);
+  }
+
+  host(): TestElement {
+    return this.root;
+  }
+
+  async find(css: string, options?: Options): Promise<TestElement|null> {
+    const finder = await getElement(css, this.rootFinder, options);
+    if (finder === null) return null;
+    return new ProtractorElement(finder);
+  }
+
+  async findAll(css: string): Promise<TestElement[]> {
+    const elementFinders = this.rootFinder.all(by.css(css));
+    const res: TestElement[] = [];
+    await elementFinders.each(el => {
+      if (el) {
+        res.push(new ProtractorElement(el));
+      }
+    });
+    return res;
+  }
+
+  async load<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>, css: string,
+    options?: Options): Promise<T|null> {
+    const root = await getElement(css, this.rootFinder, options);
+    if (root === null) return null;
+    const locator = new ProtractorLocator(root);
+    return new componentHarness(locator);
+  }
+
+  async loadAll<T extends ComponentHarness>(
+    componentHarness: ComponentHarnessType<T>,
+    rootSelector: string,
+  ): Promise<T[]> {
+    const roots = this.rootFinder.all(by.css(rootSelector));
+    const res: T[] = [];
+    await roots.each(el => {
+      if (el) {
+        const locator = new ProtractorLocator(el);
+        res.push(new componentHarness(locator));
+      }
+    });
+    return res;
+  }
+}
+
+class ProtractorElement implements TestElement {
+  constructor(readonly element: ElementFinder) {}
+
+  blur(): Promise<void> {
+    return toPromise<void>(this.element['blur']());
+  }
+
+  clear(): Promise<void> {
+    return toPromise<void>(this.element.clear());
+  }
+
+  click(): Promise<void> {
+    return toPromise<void>(this.element.click());
+  }
+
+  focus(): Promise<void> {
+    return toPromise<void>(this.element['focus']());
+  }
+
+  getCssValue(property: string): Promise<string> {
+    return toPromise<string>(this.element.getCssValue(property));
+  }
+
+  async hover(): Promise<void> {
+    return toPromise<void>(browser.actions()
+      .mouseMove(await this.element.getWebElement())
+      .perform());
+  }
+
+  sendKeys(keys: string): Promise<void> {
+    return toPromise<void>(this.element.sendKeys(keys));
+  }
+
+  text(): Promise<string> {
+    return toPromise(this.element.getText());
+  }
+
+  getAttribute(name: string): Promise<string|null> {
+    return toPromise(this.element.getAttribute(name));
+  }
+}
+
+function toPromise<T>(p: wdpromise.Promise<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    p.then(resolve, reject);
+  });
+}
+
+/**
+ * Get an element finder based on the css selector and root element.
+ * Note that it will check whether the element is present only when
+ * Options.allowNull is set. This is for performance purpose.
+ * @param css the css selector
+ * @param root Optional Search element under the root element. If not set,
+ * search element globally. If options.global is set, root is ignored.
+ * @param options Optional, extra searching options
+ */
+async function getElement(css: string, root?: ElementFinder, options?: Options):
+  Promise<ElementFinder|null> {
+  const useGlobalRoot = options && !!options.global;
+  const elem = root === undefined || useGlobalRoot ? element(by.css(css)) :
+    root.element(by.css(css));
+  const allowNull = options !== undefined && options.allowNull !== undefined ?
+    options.allowNull :
+    undefined;
+  if (allowNull !== undefined) {
+    // Only check isPresent when allowNull is set
+    if (!(await elem.isPresent())) {
+      if (allowNull) {
+        return null;
+      }
+      throw new Error('Cannot find element based on the css selector: ' + css);
+    }
+    return elem;
+  }
+  return elem;
+}