1 files changed, 310 insertions, 0 deletions
diff --git a/packages/web-util/src/tests/hook.ts b/packages/web-util/src/tests/hook.ts
new file mode 100644
index 000000000..f5bebbd6d
--- /dev/null
+++ b/packages/web-util/src/tests/hook.ts
@@ -0,0 +1,310 @@
+/*
+ This file is part of GNU Taler
+ (C) 2022 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+ */
+
+import {
+  ComponentChildren,
+  Fragment,
+  FunctionalComponent,
+  h as create,
+  options,
+  render as renderIntoDom,
+  VNode
+} from "preact";
+
+// This library is expected to be included in testing environment only
+// When doing tests we want the requestAnimationFrame to be as fast as possible.
+// without this option the RAF will timeout after 100ms making the tests slower
+options.requestAnimationFrame = (fn: () => void) => {
+  return fn();
+};
+
+export function createExample<Props>(
+  Component: FunctionalComponent<Props>,
+  props: Partial<Props> | (() => Partial<Props>),
+): ComponentChildren {
+  const evaluatedProps = typeof props === "function" ? props() : props;
+  const Render = (args: any): VNode => create(Component, args);
+
+  return {
+    component: Render,
+    props: evaluatedProps,
+  };
+}
+
+// export function createExampleWithCustomContext<Props, ContextProps>(
+//   Component: FunctionalComponent<Props>,
+//   props: Partial<Props> | (() => Partial<Props>),
+//   ContextProvider: FunctionalComponent<ContextProps>,
+//   contextProps: Partial<ContextProps>,
+// ): ComponentChildren {
+//   /**
+//    * FIXME:
+//    * This may not be useful since the example can be created with context
+//    * already
+//    */
+//   const evaluatedProps = typeof props === "function" ? props() : props;
+//   const Render = (args: any): VNode => create(Component, args);
+//   const WithContext = (args: any): VNode =>
+//     create(ContextProvider, {
+//       ...contextProps,
+//       children: [Render(args)],
+//     } as any);
+
+//   return {
+//     component: WithContext,
+//     props: evaluatedProps,
+//   };
+// }
+
+const isNode = typeof window === "undefined";
+
+/**
+ * To be used on automated unit test.
+ * So test will run under node or browser
+ * @param Component
+ * @param args
+ */
+export function renderNodeOrBrowser(
+  Component: any,
+  args: any,
+  Context: any,
+): void {
+  const vdom = !Context
+    ? create(Component, args)
+    : create(Context, { children: [create(Component, args)] });
+
+  const customElement = {} as Element;
+  const parentElement = isNode ? customElement : document.createElement("div");
+  if (!isNode) {
+    document.body.appendChild(parentElement);
+  }
+
+  // renderIntoDom works also in nodejs
+  // if the VirtualDOM is composed only by functional components
+  // then no called is going to be made to the DOM api.
+  // vdom should not have any 'div' or other html component
+  renderIntoDom(vdom, parentElement);
+
+  if (!isNode) {
+    document.body.removeChild(parentElement);
+  }
+}
+type RecursiveState<S> = S | (() => RecursiveState<S>);
+
+interface Mounted<T> {
+  // unmount: () => void;
+  pullLastResultOrThrow: () => Exclude<T, VoidFunction>;
+  assertNoPendingUpdate: () => Promise<boolean>;
+  // waitNextUpdate: (s?: string) => Promise<void>;
+  waitForStateUpdate: () => Promise<boolean>;
+}
+
+/**
+ * Manual API mount the hook and return testing API
+ * Consider using hookBehaveLikeThis() function
+ * 
+ * @param hookToBeTested
+ * @param Context
+ * 
+ * @returns testing API
+ */
+export function mountHook<T extends object>(
+  hookToBeTested: () => RecursiveState<T>,
+  Context?: ({ children }: { children: any }) => VNode | null,
+): Mounted<T> {
+  let lastResult: Exclude<T, VoidFunction> | Error | null = null;
+
+  const listener: Array<() => void> = [];
+
+  // component that's going to hold the hook
+  function Component(): VNode {
+    try {
+      let componentOrResult = hookToBeTested();
+      while (typeof componentOrResult === "function") {
+        componentOrResult = componentOrResult();
+      }
+      //typecheck fails here
+      const l: Exclude<T, () => void> = componentOrResult as any;
+      lastResult = l;
+    } catch (e) {
+      if (e instanceof Error) {
+        lastResult = e;
+      } else {
+        lastResult = new Error(`mounting the hook throw an exception: ${e}`);
+      }
+    }
+
+    // notify to everyone waiting for an update and clean the queue
+    listener.splice(0, listener.length).forEach((cb) => cb());
+    return create(Fragment, {});
+  }
+
+  renderNodeOrBrowser(Component, {}, Context);
+
+  function pullLastResult(): Exclude<T | Error | null, VoidFunction> {
+    const copy: Exclude<T | Error | null, VoidFunction> = lastResult;
+    lastResult = null;
+    return copy;
+  }
+
+  function pullLastResultOrThrow(): Exclude<T, VoidFunction> {
+    const r = pullLastResult();
+    if (r instanceof Error) throw r;
+    //sanity check
+    if (!r) throw Error("there was no last result");
+    return r;
+  }
+
+  async function assertNoPendingUpdate(): Promise<boolean> {
+    await new Promise((res, rej) => {
+      const tid = setTimeout(() => {
+        res(true);
+      }, 10);
+
+      listener.push(() => {
+        clearTimeout(tid);
+        res(false);
+        //   Error(`Expecting no pending result but the hook got updated.
+        //  If the update was not intended you need to check the hook dependencies
+        //  (or dependencies of the internal state) but otherwise make
+        //  sure to consume the result before ending the test.`),
+        // );
+      });
+    });
+
+    const r = pullLastResult();
+    if (r) {
+      return Promise.resolve(false);
+    }
+    return Promise.resolve(true);
+    // throw Error(`There are still pending results.
+    //  This may happen because the hook did a new update but the test didn't consume the result using pullLastResult`);
+  }
+  async function waitForStateUpdate(): Promise<boolean> {
+    return await new Promise((res, rej) => {
+      const tid = setTimeout(() => {
+        res(false);
+      }, 10);
+
+      listener.push(() => {
+        clearTimeout(tid);
+        res(true);
+      });
+    });
+  }
+
+  return {
+    // unmount,
+    pullLastResultOrThrow,
+    waitForStateUpdate,
+    assertNoPendingUpdate,
+  };
+}
+
+export const nullFunction = (): void => {
+  null;
+};
+export const nullAsyncFunction = (): Promise<void> => {
+  return Promise.resolve();
+};
+
+type HookTestResult = HookTestResultOk | HookTestResultError;
+
+interface HookTestResultOk {
+  result: "ok";
+}
+interface HookTestResultError {
+  result: "fail";
+  error: string;
+  index: number;
+}
+
+/**
+ * Main testing driver.
+ * It will assert that there are no more and no less hook updates than expected. 
+ * 
+ * @param hookFunction hook function to be tested
+ * @param props initial props for the hook
+ * @param checks step by step state validation
+ * @param Context additional testing context for overrides
+ * 
+ * @returns testing result, should also be checked to be "ok"
+ */
+export async function hookBehaveLikeThis<T extends object, PropsType>(
+  hookFunction: (p: PropsType) => RecursiveState<T>,
+  props: PropsType,
+  checks: Array<(state: T) => void>,
+  Context?: ({ children }: { children: any }) => VNode | null,
+): Promise<HookTestResult> {
+  const { pullLastResultOrThrow, waitForStateUpdate, assertNoPendingUpdate } =
+    mountHook<T>(() => hookFunction(props), Context);
+
+  const [firstCheck, ...resultOfTheChecks] = checks;
+  {
+    const state = pullLastResultOrThrow();
+    const checkError = firstCheck(state);
+    if (checkError !== undefined) {
+      return {
+        result: "fail",
+        index: 0,
+        error: `Check return not undefined error: ${checkError}`,
+      };
+    }
+  }
+
+  let index = 1;
+  for (const check of resultOfTheChecks) {
+    const hasNext = await waitForStateUpdate();
+    if (!hasNext) {
+      return {
+        result: "fail",
+        error: "Component didn't update and the test expected one more state",
+        index,
+      };
+    }
+    const state = pullLastResultOrThrow();
+    const checkError = check(state);
+    if (checkError !== undefined) {
+      return {
+        result: "fail",
+        index,
+        error: `Check return not undefined error: ${checkError}`,
+      };
+    }
+    index++;
+  }
+
+  const hasNext = await waitForStateUpdate();
+  if (hasNext) {
+    return {
+      result: "fail",
+      index,
+      error: "Component updated and test didn't expect more states",
+    };
+  }
+  const noMoreUpdates = await assertNoPendingUpdate();
+  if (noMoreUpdates === false) {
+    return {
+      result: "fail",
+      index,
+      error: "Component was updated but the test does not cover the update",
+    };
+  }
+
+  return {
+    result: "ok",
+  };
+}