@interactors/core 0.3.0

package/src/index.ts

@@ -0,0 +1,20 @@
+export { Interactor, InteractorConstructor, InteractorSpecification } from './specification';
+export { Interaction, ReadonlyInteraction, isInteraction } from './interaction';
+export { createInteractor } from './create-interactor';
+export { createInspector } from './inspector'
+export { perform } from './perform';
+export { focused, focus, blur } from './focused';
+export { isVisible } from 'element-is-visible';
+export { Matcher } from './matcher';
+export * from './dispatch';
+
+export { including } from './matchers/including';
+export { matching } from './matchers/matching';
+export { and } from './matchers/and';
+export { or } from './matchers/or';
+export { not } from './matchers/not';
+export { some } from './matchers/some';
+export { every } from './matchers/every';
+
+export { fillIn } from './element/fill-in';
+export { click } from './element/click';

package/src/inspector.ts

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { instantiateBaseInteractor, findElements, unsafeSyncResolveParent } from "./constructor";
+import { BaseInteractor, Filters, InteractorConstructor, FilterParams } from "./specification";
+
+type GetElement<I extends InteractorConstructor<any, any, any, any>> = I extends InteractorConstructor<infer E, any, any, any> ? E : never
+type GetFilters<I extends InteractorConstructor<any, any, any, any>> = I extends InteractorConstructor<any, infer F, any, any> ? F : never
+type GetActions<I extends InteractorConstructor<any, any, any, any>> = I extends InteractorConstructor<any, any, any, infer A> ? A : never
+
+export interface InteractorInspector<E extends Element, FP extends FilterParams<any, any>> extends BaseInteractor<E, FP> {
+  element: E,
+  find<T extends InteractorConstructor<any, any, any, any>>(interactor: T): Inspector<T>
+}
+
+export interface Inspector<C extends InteractorConstructor<any, any, any, any>> {
+  /**
+   * Finds all matched by selector elements and wraps each of them to intreactor
+   */
+   all(): (InteractorInspector<GetElement<C>, GetFilters<C>> & GetActions<C>)[]
+}
+
+export function createInspector<IC extends InteractorConstructor<any, any, any, any>>(
+  constructor: IC,
+  parentElement?: Element
+): Inspector<IC> {
+  // NOTE: Wait for https://github.com/thefrontside/bigtest/pull/895 to use specification instead
+  let options = constructor().options as ReturnType<IC>['options']
+  return {
+    all() {
+      let elements = findElements<GetElement<IC>>(parentElement ?? unsafeSyncResolveParent(options), options);
+      return elements.map(
+        element => (Object.assign(
+          instantiateBaseInteractor(options, () => element) as (BaseInteractor<GetElement<IC>, Filters<GetFilters<IC>>> & GetActions<IC>), {
+          element,
+          find<T extends InteractorConstructor<any, any, any, any>>(constructor: T): Inspector<T> {
+            return createInspector(constructor, element)
+          }
+        }))
+      );
+    }
+  };
+}

package/src/interaction.ts

@@ -0,0 +1,82 @@
+import { globals } from '@interactors/globals';
+import type { FilterObject } from './specification';
+
+const interactionSymbol = Symbol.for('interaction');
+
+export function isInteraction(x: unknown): x is Interaction<unknown> {
+  return typeof x === 'object' && x != null && interactionSymbol in x
+}
+
+/**
+ * An interaction represents some type of action or assertion that can be
+ * taken on an {@link Interactor}.
+ *
+ * The interaction can function as a lazy promise. That means that calling
+ * `then` on the interaction or awaiting it using `await`, will run the
+ * interaction and the promise will resolve once the action is complete.
+ * However, an interaction which is not awaited will not run by itself.
+ *
+ * @typeParam T the return value of the promise that this interaction evaluates to.
+ */
+export interface Interaction<T> extends Promise<T> {
+  /**
+   * Return a description of the interaction
+   */
+  description: string;
+  /**
+   * Perform the interaction
+   */
+  action: () => Promise<T>;
+
+  [interactionSymbol]: true
+}
+
+/**
+ * Like {@link Interaction}, except that it is used for assertions only.
+ *
+ * @typeParam T the return value of the promise that this interaction evaluates to.
+ */
+export interface ReadonlyInteraction<T> extends Interaction<T> {
+  /**
+   * Perform the check
+   */
+  check: () => Promise<T>;
+}
+
+function createInteraction<T>(description: string, action: () => Promise<T>): Interaction<T> {
+  let promise: Promise<T>;
+  return {
+    description,
+    action,
+    [interactionSymbol]: true,
+    [Symbol.toStringTag]: `[interaction ${description}]`,
+    then(onFulfill, onReject) {
+      if(!promise) { promise = this.action(); }
+      return promise.then(onFulfill, onReject);
+    },
+    catch(onReject) {
+      if(!promise) { promise = this.action(); }
+      return promise.catch(onReject);
+    },
+    finally(handler) {
+      if(!promise) { promise = this.action(); }
+      return promise.finally(handler);
+    }
+  }
+}
+
+export function interaction<T>(description: string, action: () => Promise<T>): Interaction<T> {
+  return createInteraction(description, globals.wrapAction(description, action, 'interaction'))
+}
+
+export function check<T>(description: string, check: () => Promise<T>): ReadonlyInteraction<T> {
+  return { check() { return this.action() }, ...createInteraction(description, globals.wrapAction(description, check, 'check')) };
+}
+
+export function interactionFilter<T, Q>(description: string, action: () => Promise<T>, filter: (element: Element) => Q): Interaction<T> & FilterObject<Q, Element> {
+  return { apply: filter, ...interaction(description, action) };
+}
+
+export function checkFilter<T, Q>(description: string, action: () => Promise<T>, filter: (element: Element) => Q): ReadonlyInteraction<T> & FilterObject<Q, Element> {
+  return { apply: filter , ...check(description, action) };
+}

package/src/locator.ts

@@ -0,0 +1,15 @@
+import { FilterDefinition } from './specification';
+import { matcherDescription, MaybeMatcher } from './matcher';
+import { applyFilter } from './match';
+
+export class Locator<E extends Element> {
+  constructor(private definition: FilterDefinition<string, E>, public value: MaybeMatcher<string>) {}
+
+  get description(): string {
+    return matcherDescription(this.value);
+  }
+
+  apply(element: E): string {
+    return applyFilter(this.definition, element);
+  }
+}

package/src/match.ts

@@ -0,0 +1,162 @@
+import { Locator } from './locator';
+import { FilterSet } from './filter-set';
+import { Filters, FilterDefinition } from './specification';
+import { escapeHtml } from './escape-html';
+import { MaybeMatcher, applyMatcher, matcherDescription } from './matcher';
+
+const check = (value: unknown): string => value ? "✓" : "⨯";
+
+export class Match<E extends Element, F extends Filters<E>> {
+  public matchLocator?: MatchLocator<E>;
+  public matchFilter: MatchFilter<E, F>;
+  public matches: boolean;
+
+  constructor(
+    public element: E,
+    public filterSet: FilterSet<E, F>,
+    public locator?: Locator<E>,
+  ) {
+    this.matchLocator = locator && new MatchLocator(element, locator);
+    this.matchFilter = new MatchFilter(element, filterSet);
+    this.matches = (this.matchLocator ? this.matchLocator.matches : true) && this.matchFilter.matches;
+  }
+
+  asTableHeader(name: string): string[] {
+    if(this.matchLocator) {
+      return [name, ...this.filterSet.asTableHeader()];
+    } else {
+      return this.filterSet.asTableHeader();
+    }
+  }
+
+  asTableRow(): string[] {
+    if(this.matchLocator) {
+      return [this.matchLocator.description(), ...this.matchFilter.asTableRow()]
+    } else {
+      return this.matchFilter.asTableRow();
+    }
+  }
+
+  get sortWeight(): number {
+    return (this.matchLocator?.sortWeight || 0) + this.matchFilter.sortWeight;
+  }
+
+  elementDescription(): string {
+    let tag = this.element.tagName.toLowerCase();
+    let attrs = Array.from(this.element.attributes).map((attr) => {
+      return `${attr.name}="${escapeHtml(attr.value)}"`
+    });
+    return `<${[tag, ...attrs].join(' ')}>`;
+  }
+}
+
+export class MatchLocator<E extends Element> {
+  public matches: boolean;
+  public expected: MaybeMatcher<string> | null;
+  public actual: string | null;
+
+  constructor(
+    public element: E,
+    public locator: Locator<E>,
+  ) {
+    this.expected = locator.value;
+    this.actual = locator.apply(element);
+    this.matches = applyMatcher(this.expected, this.actual);
+  }
+
+  formatActual(): string {
+    return JSON.stringify(this.actual);
+  }
+
+  description(): string {
+    return `${check(this.matches)} ${this.formatActual()}`;
+  }
+
+  get sortWeight(): number {
+    return this.matches ? 10 : 0;
+  }
+}
+
+export class MatchFilter<E extends Element, F extends Filters<E>> {
+  public matches: boolean;
+  public items: MatchFilterItem<unknown, E, F>[];
+
+  constructor(
+    public element: E,
+    public filter: FilterSet<E, F>,
+  ) {
+    this.items = Object.entries(filter.all).map(([key, expected]) => {
+      return new MatchFilterItem(element, filter, key, expected)
+    });
+    this.matches = this.items.every((match) => match.matches)
+  }
+
+  asTableRow(): string[] {
+    return this.items.map((f) => f.description());
+  }
+
+  get sortWeight(): number {
+    return this.items.reduce((agg, i) => agg + i.sortWeight, 0);
+  }
+
+  formatAsExpectations(): string {
+    return this.items.filter((i) => !i.matches).map((i) => i.formatAsExpectation()).join('\n\n');
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyFilter<T>(definition: FilterDefinition<T, any>, element: Element): T {
+  if(typeof(definition) === 'function') {
+    return definition(element) as T;
+  } else {
+    return definition.apply(element) as T;
+  }
+}
+
+export class MatchFilterItem<T, E extends Element, F extends Filters<E>> {
+  public actual: T;
+  public matches: boolean;
+
+  constructor(
+    public element: E,
+    public filter: FilterSet<E, F>,
+    public key: string,
+    public expected: MaybeMatcher<T>,
+  ) {
+    if(this.filter.specification.filters && this.filter.specification.filters[this.key]) {
+      let definition = this.filter.specification.filters[this.key];
+      if(typeof(definition) === 'function') {
+        this.actual = definition(this.element) as T;
+      } else {
+        this.actual = definition.apply(this.element) as T;
+      }
+      this.matches = applyMatcher(this.expected, this.actual);
+    } else {
+      throw new Error(`interactor does not define a filter named ${JSON.stringify(this.key)}`);
+    }
+  }
+
+  formatActual(): string {
+    return JSON.stringify(this.actual);
+  }
+
+  formatExpected(): string {
+    return matcherDescription(this.expected);
+  }
+
+  description(): string {
+    return `${check(this.matches)} ${this.formatActual()}`;
+  }
+
+  formatAsExpectation(): string {
+    return [
+      `╒═ Filter:   ${this.key}`,
+      `├─ Expected: ${this.formatExpected()}`,
+      `└─ Received: ${this.formatActual()}`,
+    ].join('\n')
+  }
+
+  get sortWeight(): number {
+    return this.matches ? 1 : 0;
+  }
+}

package/src/matcher.ts

@@ -0,0 +1,28 @@
+import isEqual from 'lodash.isequal';
+
+export interface Matcher<T> {
+  match(actual: T): boolean;
+  description(): string;
+}
+
+export type MaybeMatcher<T> = Matcher<T> | T;
+
+export function isMatcher<T>(value: MaybeMatcher<T>): value is Matcher<T> {
+  return value && typeof (value as Matcher<T>).match === 'function' && typeof (value as Matcher<T>).description === 'function';
+}
+
+export function matcherDescription<T>(value: MaybeMatcher<T>): string {
+  if(isMatcher(value)) {
+    return value.description();
+  } else {
+    return JSON.stringify(value);
+  }
+}
+
+export function applyMatcher<T>(value: MaybeMatcher<T>, actual: T): boolean {
+  if(isMatcher(value)) {
+    return value.match(actual);
+  } else {
+    return isEqual(value, actual);
+  }
+}

package/src/matchers/and.ts

@@ -0,0 +1,12 @@
+import { Matcher, MaybeMatcher, matcherDescription, applyMatcher } from '../matcher';
+
+export function and<T>(...args: MaybeMatcher<T>[]): Matcher<T> {
+  return {
+    match(actual: T): boolean {
+      return args.every((matcher) => applyMatcher(matcher, actual));
+    },
+    description(): string {
+      return args.map(matcherDescription).join(' and ');
+    },
+  }
+}

package/src/matchers/every.ts

@@ -0,0 +1,12 @@
+import { Matcher, MaybeMatcher, applyMatcher, matcherDescription } from '../matcher';
+
+export function every<T>(expected: MaybeMatcher<T>): Matcher<Iterable<T>> {
+  return {
+    match(actual: Iterable<T>): boolean {
+      return Array.from(actual).every((value) => applyMatcher(expected, value));
+    },
+    description(): string {
+      return `every item ${matcherDescription(expected)}`;
+    },
+  }
+}

package/src/matchers/including.ts

@@ -0,0 +1,12 @@
+import { Matcher } from '../matcher';
+
+export function including(subString: string): Matcher<string> {
+  return {
+    match(actual: string): boolean {
+      return actual.includes(subString);
+    },
+    description(): string {
+      return `including ${JSON.stringify(subString)}`;
+    },
+  }
+}

package/src/matchers/matching.ts

@@ -0,0 +1,12 @@
+import { Matcher } from '../matcher';
+
+export function matching(regexp: RegExp): Matcher<string> {
+  return {
+    match(actual: string): boolean {
+      return actual.match(regexp) != null;
+    },
+    description(): string {
+      return `matching ${regexp}`;
+    },
+  }
+}

package/src/matchers/not.ts

@@ -0,0 +1,12 @@
+import { Matcher, MaybeMatcher, matcherDescription, applyMatcher } from '../matcher';
+
+export function not<T>(matcher: MaybeMatcher<T>): Matcher<T> {
+  return {
+    match(actual: T): boolean {
+      return !applyMatcher(matcher, actual);
+    },
+    description(): string {
+      return `not ${matcherDescription(matcher)}`;
+    },
+  }
+}

package/src/matchers/or.ts

@@ -0,0 +1,12 @@
+import { Matcher, MaybeMatcher, matcherDescription, applyMatcher } from '../matcher';
+
+export function or<T>(...args: MaybeMatcher<T>[]): Matcher<T> {
+  return {
+    match(actual: T): boolean {
+      return args.some((matcher) => applyMatcher(matcher, actual));
+    },
+    description(): string {
+      return args.map(matcherDescription).join(' or ');
+    },
+  }
+}

package/src/matchers/some.ts

@@ -0,0 +1,12 @@
+import { Matcher, MaybeMatcher, applyMatcher, matcherDescription } from '../matcher';
+
+export function some<T>(expected: MaybeMatcher<T>): Matcher<Iterable<T>> {
+  return {
+    match(actual: Iterable<T>): boolean {
+      return Array.from(actual).some((value) => applyMatcher(expected, value));
+    },
+    description(): string {
+      return `some item ${matcherDescription(expected)}`;
+    },
+  }
+}

package/src/merge-objects.ts

@@ -0,0 +1,2 @@
+// A utility type for merging two object types
+export type MergeObjects<A, B> = B & Omit<A, keyof B>;

package/src/perform.ts

@@ -0,0 +1,11 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Interactor, FilterParams } from './specification';
+
+export function perform<E extends Element, F extends FilterParams<any, any>, T extends unknown[]>(fn: (element: E, ...args: T) => void): (interactor: Interactor<E, F>, ...args: T) => Promise<void> {
+  console.warn('`perform` is deprecated, please use `({ perform }) => perform(...)` instead!');
+  return async (interactor: Interactor<E, F>, ...args: T) => {
+    return await interactor.perform(element => {
+      fn(element, ...args);
+    });
+  };
+}