@interactors/core 1.0.0-rc1.2 → 1.0.0-rc1.3

package/src/resolvers.ts

@@ -0,0 +1,100 @@
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { globals } from '@interactors/globals';
+import { Match } from './match';
+import { NoSuchElementError, NotAbsentError, AmbiguousElementError } from './errors';
+import { formatDescription, formatMatchesTable } from './format';
+import { InteractorOptions } from './specification';
+
+const defaultSelector = 'div';
+
+export function findElements<E extends Element>(parentElement: Element, interactor: InteractorOptions<any, any, any>): E[] {
+  if (!interactor.name) {
+    throw new Error('One of your interactors was created without a name. Please provide a label for your interactor:\n\tHTML.extend(\'my interactor\') || createInteractor(\'my interactor\')');
+  }
+  if (typeof interactor.specification.selector === 'function') {
+    return interactor.specification.selector(parentElement);
+  } else if (interactor.specification.selector === ':root') {
+    // this is a bit of a hack, because otherwise there isn't a good way of selecting the root element
+    return [parentElement.ownerDocument.querySelector(':root') as E];
+  } else {
+    return Array.from(parentElement.querySelectorAll(interactor.specification.selector || defaultSelector));
+  }
+}
+
+function findMatches(parentElement: Element, interactor: InteractorOptions<any, any, any>): Match<Element, any>[] {
+  return findElements(parentElement, interactor).map((e) => new Match(e, interactor.filter, interactor.locator));
+}
+
+function throwNoSuchElementError(matches: Match<Element, any>[], interactor: InteractorOptions<any, any, any>): never {
+  if (matches.length === 0) {
+    throw new NoSuchElementError(`did not find ${formatDescription(interactor)}`);
+  } else {
+    throw new NoSuchElementError(`did not find ${formatDescription(interactor)}, did you mean one of:\n\n${formatMatchesTable(interactor, matches)}`);
+  }
+}
+
+function findFirstMatch(parentElement: Element, interactor: InteractorOptions<any, any, any>): Match<Element, any> {
+  let matches: Match<Element, any>[] = []
+  for (let element of findElements(parentElement, interactor)) {
+    let match = new Match(element, interactor.filter, interactor.locator)
+    matches.push(match)
+    if (match.matches) {
+      return match
+    }
+  }
+  throwNoSuchElementError(matches, interactor);
+}
+
+export function hasMatchMatching(parentElement: Element, interactor: InteractorOptions<any, any, any>): boolean {
+  return findElements(parentElement, interactor).some(element => new Match(element, interactor.filter, interactor.locator).matches);
+}
+
+function findMatchesNonEmpty(parentElement: Element, interactor: InteractorOptions<any, any, any>): Match<Element, any>[] {
+  let matches = findMatches(parentElement, interactor);
+  let matching = matches.filter((m) => m.matches);
+  if (matching.length > 0) {
+    return matching;
+  }
+  throwNoSuchElementError(matches, interactor);
+}
+
+// Given a parent element, and an interactor, find exactly one matching element
+// and return it. If no elements match, raise an error. If more than one
+// element matches, raise an error.
+export function resolveUnique(parentElement: Element, interactor: InteractorOptions<any, any, any>): Element {
+  let matching = findMatchesNonEmpty(parentElement, interactor);
+
+  if (matching.length === 1) {
+    return matching[0].element;
+  } else {
+    let alternatives = matching.map((m) => '- ' + m.elementDescription());
+    throw new AmbiguousElementError(`${formatDescription(interactor)} matches multiple elements:\n\n${alternatives.join('\n')}`);
+  }
+}
+
+// Given a parent element, and an interactor, find the first matching element and
+// return it. If no elements match, raise an error.
+export function resolveFirst(parentElement: Element, interactor: InteractorOptions<any, any, any>): Element {
+  return findFirstMatch(parentElement, interactor).element
+}
+
+// Given a parent element, and an interactor, check if there are any matching
+// elements, and throw an error if there are. Otherwise return undefined.
+export function resolveEmpty(parentElement: Element, interactor: InteractorOptions<any, any, any>): void {
+  let matching = findMatches(parentElement, interactor).filter((m) => m.matches)
+
+  if (matching.length !== 0) {
+    let alternatives = matching.map((m) => '- ' + m.elementDescription());
+    throw new NotAbsentError(`${formatDescription(interactor)} exists but should not:\n\n${alternatives.join('\n')}`);
+  }
+}
+
+export function unsafeSyncResolveParent(options: InteractorOptions<any, any, any>): Element {
+  return options.ancestors.reduce(resolveUnique, globals.document.documentElement);
+}
+
+export function unsafeSyncResolveUnique<E extends Element>(options: InteractorOptions<E, any, any>): E {
+  return resolveUnique(unsafeSyncResolveParent(options), options) as E;
+}

package/src/serialize.ts

@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { InteractionOptions as SerializedInteractionOptions, InteractionType } from "@interactors/globals";
+import { pascalCase } from "change-case";
+import { InteractionOptions } from "./interaction";
+import { matcherCode } from "./matcher";
+import { InteractorOptions } from "./specification";
+
+export function serializeInteractorOptions(options: InteractorOptions<any, any, any>): {
+  interactor: string;
+  filter: { [name: string]: unknown };
+  locator: string;
+  code: () => string;
+} {
+  let locator = matcherCode(options.locator?.value);
+  return {
+    interactor: options.name,
+    filter: options.filter.all,
+    locator,
+    code() {
+      let interactorName = pascalCase(options.name);
+      let filters = Object.entries(options.filter.all).map(([name, filter]) => `"${name}": ${matcherCode(filter)}`);
+      return `${interactorName}(${[locator, filters.length && `{ ${filters.join(", ")} }`]
+        .filter(Boolean)
+        .join(", ")})`;
+    },
+  };
+}
+
+export function serializeInteractionOptions<E extends Element, T>(
+  type: InteractionType,
+  { name, interactor: { options }, args, filters }: InteractionOptions<E, T>
+): SerializedInteractionOptions {
+  let interactor = serializeInteractorOptions(options);
+  let ancestors = options.ancestors.map((ancestor) => serializeInteractorOptions(ancestor));
+  return {
+    ...interactor,
+    ancestors,
+    name,
+    type,
+    args,
+    code() {
+      let serializedArgs = "";
+      if (filters) {
+        let serializedFilters = Object.entries(filters).map(([name, filter]) => `"${name}": ${matcherCode(filter)}`);
+        serializedArgs = `{ ${serializedFilters.join(", ")} }`;
+      } else if (args) {
+        serializedArgs = args.map((arg) => JSON.stringify(arg)).join(", ");
+      }
+      return `${[...ancestors, interactor]
+        .map(({ code }, index) => (index == 0 ? code() : `${code()})`))
+        .join(".find(")}.${name}(${serializedArgs})`;
+    },
+  };
+}

package/src/specification.ts

@@ -1,8 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+import { Operation } from '@effection/core';
 import { FilterSet } from './filter-set';
 import { Locator } from './locator';
-import { Interaction, ReadonlyInteraction } from './interaction';
+import { ActionInteraction, AssertionInteraction } from './interaction';
 import { MergeObjects } from './merge-objects';
 import { MaybeMatcher } from './matcher';
 
@@ -38,7 +39,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
    * await Link('Next').perform((e) => e.click());
    * ```
    */
-  perform(fn: (element: E) => void): Interaction<void>;
+  perform(fn: (element: E) => void): ActionInteraction<E, void>;
 
   /**
    * Perform a one-off assertion on the given interactor. Takes a function which
@@ -54,7 +55,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
    * await Link('Next').assert((e) => assert(e.tagName === 'A'));
    * ```
    */
-  assert(fn: (element: E) => void): ReadonlyInteraction<void>;
+  assert(fn: (element: E) => void): AssertionInteraction<E, void>;
 
   /**
    * An assertion which checks that an element matching the interactor exists.
@@ -66,7 +67,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
    * await Link('Next').exists();
    * ```
    */
-  exists(): ReadonlyInteraction<void> & FilterObject<boolean, Element>;
+  exists(): AssertionInteraction<E, void> & FilterObject<boolean, Element>;
 
   /**
    * An assertion which checks that an element matching the interactor does not
@@ -78,7 +79,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
    * await Link('Next').absent();
    * ```
    */
-  absent(): ReadonlyInteraction<void> & FilterObject<boolean, Element>;
+  absent(): AssertionInteraction<E, void> & FilterObject<boolean, Element>;
 
   /**
    * Checks that there is one element matching the interactor, and that this
@@ -91,7 +92,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
    * await Link('Home').has({ href: '/' })
    * ```
    */
-  has(filters: F): ReadonlyInteraction<void>;
+  has(filters: F): AssertionInteraction<E, void>;
 
   /**
    * Identical to {@link has}, but reads better with some filters.
@@ -102,7 +103,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
    * await CheckBox('Accept conditions').is({ checked: true })
    * ```
    */
-  is(filters: F): ReadonlyInteraction<void>;
+  is(filters: F): AssertionInteraction<E, void>;
 
   /**
    * Returns a copy of the given interactor which is scoped to this interactor.
@@ -128,7 +129,7 @@ export interface Interactor<E extends Element, F extends FilterParams<any, any>>
   apply: FilterFn<string, Element>;
 }
 
-export type ActionFn<E extends Element, I extends Interactor<E, any>> = (interactor: I, ...args: any[]) => Promise<unknown>;
+export type ActionFn<E extends Element, I extends Interactor<E, any>> = (interactor: I, ...args: any[]) => Operation<unknown>;
 
 export type FilterFn<T, E extends Element> = (element: E) => T;
 
@@ -162,15 +163,15 @@ export type InteractorSpecification<E extends Element, F extends Filters<E>, A e
 }
 
 export type ActionMethods<E extends Element, A extends Actions<E, I>, I extends Interactor<E, any>> = {
-  [P in keyof A]: A[P] extends ((interactor: I, ...args: infer TArgs) => Promise<infer TReturn>)
-    ? ((...args: TArgs) => Interaction<TReturn>)
+  [P in keyof A]: A[P] extends ((interactor: I, ...args: infer TArgs) => Operation<infer TReturn>)
+    ? ((...args: TArgs) => ActionInteraction<E, TReturn>)
     : never;
 }
 
 export type FilterMethods<E extends Element, F extends Filters<E>> = {
   [P in keyof F]:
-    F[P] extends FilterFn<infer TReturn, any> ? (() => Interaction<TReturn> & FilterObject<TReturn, Element>) :
-    F[P] extends FilterObject<infer TReturn, any> ? (() => Interaction<TReturn> & FilterObject<TReturn, Element>) :
+    F[P] extends FilterFn<infer TReturn, any> ? (() => AssertionInteraction<E, TReturn> & FilterObject<TReturn, Element>) :
+    F[P] extends FilterObject<infer TReturn, any> ? (() => AssertionInteraction<E, TReturn> & FilterObject<TReturn, Element>) :
     never;
 }
 
@@ -198,6 +199,7 @@ export type FilterParams<E extends Element, F extends Filters<E>> = keyof F exte
  * @typeParam A the actions of this interactor, this is usually inferred from the specification
  */
 export interface InteractorConstructor<E extends Element, FP extends FilterParams<any, any>, FM extends FilterMethods<any, any>, AM extends ActionMethods<any, any, any>> {
+  interactorName: string;
   selector(value: string | SelectorFn<E>): InteractorConstructor<E, FP, FM, AM>;
   locator(value: FilterDefinition<string, E>): InteractorConstructor<E, FP, FM, AM>;
   filters<FR extends Filters<E>>(filters: FR): InteractorConstructor<E, MergeObjects<FP, FilterParams<E, FR>>, MergeObjects<FM, FilterMethods<E, FR>>, AM>;
@@ -225,6 +227,7 @@ export interface InteractorConstructor<E extends Element, FP extends FilterParam
    *
    * ``` typescript
    * Link('Home');
+   * Link(/^home/i);
    * ```
    *
    * Or with a locator and options:
@@ -236,7 +239,7 @@ export interface InteractorConstructor<E extends Element, FP extends FilterParam
    * @param value The locator value, which should match the value of applying the locator function defined in the {@link InteractorSpecification} to the element.
    * @param filters An object describing a set of filters to apply, which should match the value of applying the filters defined in the {@link InteractorSpecification} to the element.
    */
-  (value: MaybeMatcher<string>, filters?: FP): Interactor<E, FP> & FM & AM;
+  (value: MaybeMatcher<string> | RegExp, filters?: FP): Interactor<E, FP> & FM & AM;
 }
 
 export type InteractorOptions<E extends Element, F extends Filters<E>, A extends Actions<E, Interactor<E, EmptyObject>>> = {

package/dist/cjs/format-table.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatTable = void 0;
-const MAX_COLUMN_WIDTH = 40;
-function formatValue(value, width) {
-    if (value.length > width) {
-        return value.slice(0, width - 1) + '…';
-    }
-    else {
-        return value.padEnd(width);
-    }
-}
-function formatTable(options) {
-    let columnWidths = options.headers.map((h, index) => {
-        return Math.min(MAX_COLUMN_WIDTH, Math.max(h.length, ...options.rows.map((r) => r[index].length)));
-    });
-    let formatRow = (cells) => {
-        return '┃ ' + cells.map((c, index) => formatValue(c, columnWidths[index])).join(' ┃ ') + ' ┃';
-    };
-    let spacerRow = () => {
-        return '┣━' + columnWidths.map((w) => "━".repeat(w)).join('━╋━') + '━┫';
-    };
-    return [
-        formatRow(options.headers),
-        spacerRow(),
-        ...options.rows.map((row) => formatRow(row))
-    ].join('\n');
-}
-exports.formatTable = formatTable;
-//# sourceMappingURL=format-table.js.map

package/dist/cjs/format-table.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"format-table.js","sourceRoot":"","sources":["../../src/format-table.ts"],"names":[],"mappings":";;;AAKA,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAE3B,SAAS,WAAW,CAAC,KAAa,EAAE,KAAa;IAC/C,IAAG,KAAK,CAAC,MAAM,GAAG,KAAK,EAAE;QACvB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;KACxC;SAAM;QACL,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;KAC5B;AACH,CAAC;AAED,SAAgB,WAAW,CAAC,OAAqB;IAC/C,IAAI,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QAClD,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACrG,CAAC,CAAC,CAAC;IAEH,IAAI,SAAS,GAAG,CAAC,KAAe,EAAE,EAAE;QAClC,OAAO,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAChG,CAAC,CAAA;IAED,IAAI,SAAS,GAAG,GAAG,EAAE;QACnB,OAAO,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAC1E,CAAC,CAAA;IAED,OAAO;QACL,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1B,SAAS,EAAE;QACX,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;KAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAlBD,kCAkBC"}

package/dist/esm/format-table.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"format-table.js","sourceRoot":"","sources":["../../src/format-table.ts"],"names":[],"mappings":"AAKA,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAE3B,SAAS,WAAW,CAAC,KAAa,EAAE,KAAa;IAC/C,IAAG,KAAK,CAAC,MAAM,GAAG,KAAK,EAAE;QACvB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;KACxC;SAAM;QACL,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;KAC5B;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,IAAI,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QAClD,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACrG,CAAC,CAAC,CAAC;IAEH,IAAI,SAAS,GAAG,CAAC,KAAe,EAAE,EAAE;QAClC,OAAO,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAChG,CAAC,CAAA;IAED,IAAI,SAAS,GAAG,GAAG,EAAE;QACnB,OAAO,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAC1E,CAAC,CAAA;IAED,OAAO;QACL,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1B,SAAS,EAAE;QACX,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;KAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/format-table.d.ts

@@ -1,6 +0,0 @@
-export interface TableOptions {
-    headers: string[];
-    rows: string[][];
-}
-export declare function formatTable(options: TableOptions): string;
-//# sourceMappingURL=format-table.d.ts.map

package/dist/format-table.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"format-table.d.ts","sourceRoot":"","sources":["../src/format-table.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;CAClB;AAYD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAkBzD"}

package/src/format-table.ts

@@ -1,34 +0,0 @@
-export interface TableOptions {
-  headers: string[];
-  rows: string[][];
-}
-
-const MAX_COLUMN_WIDTH = 40
-
-function formatValue(value: string, width: number) {
-  if(value.length > width) {
-    return value.slice(0, width - 1) + '…';
-  } else {
-    return value.padEnd(width);
-  }
-}
-
-export function formatTable(options: TableOptions): string {
-  let columnWidths = options.headers.map((h, index) => {
-    return Math.min(MAX_COLUMN_WIDTH, Math.max(h.length, ...options.rows.map((r) => r[index].length)));
-  });
-
-  let formatRow = (cells: string[]) => {
-    return '┃ ' + cells.map((c, index) => formatValue(c, columnWidths[index])).join(' ┃ ') + ' ┃';
-  }
-
-  let spacerRow = () => {
-    return '┣━' + columnWidths.map((w) => "━".repeat(w)).join('━╋━') + '━┫';
-  }
-
-  return [
-    formatRow(options.headers),
-    spacerRow(),
-    ...options.rows.map((row) => formatRow(row))
-  ].join('\n');
-}