@genesislcap/foundation-testing 14.68.2 → 14.68.3-alpha-43b6152.0

package/dist/foundation-testing.d.ts

@@ -0,0 +1,435 @@
+import * as assert from 'uvu/assert';
+import { Constructable } from '@microsoft/fast-element';
+import { Container } from '@microsoft/fast-foundation';
+import { DesignSystem } from '@microsoft/fast-foundation';
+import { ExecutionContext } from '@microsoft/fast-element';
+import type { FoundationElement } from '@microsoft/fast-foundation';
+import { FoundationElementDefinition } from '@microsoft/fast-foundation';
+import { FoundationElementRegistry } from '@microsoft/fast-foundation';
+import { HTMLView } from '@microsoft/fast-element';
+import { Logger } from '@genesislcap/foundation-utils';
+import { Registration } from '@microsoft/fast-foundation';
+import { default as sinon_2 } from 'sinon';
+import { default as sinon_3 } from 'sinon';
+import { suite } from 'uvu';
+import { test } from 'uvu';
+import { uvu } from 'uvu';
+import { ViewTemplate } from '@microsoft/fast-element';
+
+export { assert }
+
+/**
+ * Component suite context interface
+ * @public
+ */
+export declare interface ComponentContext<TElement = HTMLElement> extends Pick<Fixture<TElement>, 'element' | 'disconnect'> {
+    designSystem: DesignSystem;
+    container: Container;
+    runCases: RunCases;
+}
+
+/**
+ * Create component test suite.
+ *
+ * @example
+ * Simple suite using the tag name of the component.
+ * ```ts
+ * import { createComponentSuite } from '@genesislcap/foundation-testing';
+ * import { Component } from './component';
+ * Component; // < As we're using tag name in the Suite, we hold a reference to avoid tree shaking.
+ * const Suite = createComponentSuite<Component>('Component', 'my-component');
+ * // test cases...
+ * Suite.run();
+ * ```
+ *
+ * @example
+ * Mocking a DI dependency for a composable component.
+ * ```ts
+ * const connectMock = new ConnectMock();
+ * const mocks = [Registration.instance(Connect, connectMock)];
+ * const Suite = createComponentSuite<ConnectionIndicator>('ConnectionIndicator Component', () => connectionIndicator(), null, mocks);
+ * // test cases...
+ * Suite.run();
+ * ```
+ *
+ * @example
+ * An element will be required to test anything that directly or in-directly makes use of the DI container, for example,
+ * a service that can be injected into components, or has its own injected dependencies.
+ * ```ts
+ * import { Service } from './service';
+ * @customElement({
+ *   name: 'test-element',
+ *   template: html`<slot></slot>`,
+ * })
+ * class TestElement extends FASTElement {}
+ * const mocks = [...];
+ * const Suite = createComponentSuite<TestElement>('Service', 'test-element', null, mocks);
+ * // test cases...
+ * Suite.run();
+ * ```
+ *
+ * Importing the service should invoke the Service's DI registration, so in your test cases you can simply query the
+ * container to get a reference to your service.
+ * ```ts
+ * Suite('Service.x does something expected', async ({ container }) => {
+ *   const myService = container.get(Service);
+ *   // assert
+ * });
+ * ```
+ *
+ * You can optionally add the service to the test element for lookup convenience, but this is not required.
+ * ```ts
+ * class TestElement extends FASTElement {
+ *   @Service service: Service;
+ * }
+ * Suite('Element has service injected', async ({ element }) => {
+ *   assert.ok(element.service);
+ * });
+ * ```
+ *
+ * @typeParam TElement - The element interface.
+ * @param title - Title of the test suite
+ * @param elementNameOrGetter - Element tag name or getter which is used to create the element within the fixture
+ * @param context - Optional component context {@link ComponentContext}
+ * @param registrations - Optional array of DI container registrations
+ * @returns The test suite
+ * @public
+ * @remarks
+ * Used to test function output given certain input arguments.
+ */
+export declare function createComponentSuite<TElement = HTMLElement>(title: string, elementNameOrGetter: string | ElementGetter, context?: ComponentContext<TElement>, registrations?: Registration<any>[]): uvu.Test<ComponentContext<TElement>>;
+
+/**
+ * Create logic test suite.
+ *
+ * @example
+ * ```ts
+ * import { createLogicSuite } from '@genesislcap/foundation-testing';
+ * import { myFunction } from './logic';
+ * const Suite = createLogicSuite('myFunction');
+ * Suite('myFunction should provide expected results', ({ runCases }) => {
+ *   runCases(myFunction, [
+ *     [['1'], true],
+ *     [[123], true],
+ *     [['60%'], true],
+ *     [['$60'], false],
+ *     [['1.1'], false],
+ *     [[''], false],
+ *     [[true], false],
+ *     [[null], false],
+ *     [[undefined], false],
+ *   ]);
+ * });
+ * Suite.run();
+ * ```
+ *
+ * @typeParam TContext - The context interface.
+ * @param title - Title of the test suite
+ * @param context - Optional context which extends {@link LogicContext}
+ * @returns The test suite
+ * @public
+ * @remarks
+ * Used to test function output given certain input arguments.
+ */
+export declare function createLogicSuite<TContext = LogicContext>(title: string, context?: TContext): uvu.Test<TContext>;
+
+/**
+ * Delayed resolve utility.
+ *
+ * @example
+ * ```ts
+ * test('delayed resolve', async () => {
+ *   const mockAPI = delayedResolve({ foo: 'bar' }, 2_000);
+ *   const result = await mockAPI();
+ * });
+ * ```
+ * @param result - The result of the promise.
+ * @param duration - An optional duration in milliseconds. Defaults to 500.
+ * @public
+ */
+export declare const delayedResolve: (result: unknown, duration?: number) => () => Promise<unknown>;
+
+/**
+ * @public
+ */
+export declare type ElementGetter = () => FoundationElementRegistry<FoundationElementDefinition, FoundationElement>;
+
+/**
+ * Expects that the type parameter X is equal to Y, returning true or false
+ * @public
+ */
+export declare type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+/**
+ * Expects that the type parameter T resolves to true, or will be a typescript error
+ * @public
+ */
+export declare type Expect<T extends true> = T;
+
+/**
+ * Filters out key/value pairs from an object where they value does not match a condition
+ * @public
+ */
+export declare type FilterConditionally<Source, Condition> = Pick<Source, {
+    [K in keyof Source]: Source[K] extends Condition ? K : never;
+}[keyof Source]>;
+
+/**
+ * Unit test fixture.
+ * @public
+ */
+export declare interface Fixture<TElement = HTMLElement> {
+    /**
+     * The document the fixture is running in.
+     */
+    document: Document;
+    /**
+     * The template the fixture was created from.
+     */
+    template: ViewTemplate;
+    /**
+     * The view that was created from the fixture's template.
+     */
+    view: HTMLView;
+    /**
+     * The parent element that the view was appended to.
+     * @remarks
+     * This element will be appended to the DOM only
+     * after {@link Fixture.connect} has been called.
+     */
+    parent: HTMLElement;
+    /**
+     * The first element in the {@link Fixture.view}.
+     */
+    element: TElement;
+    /**
+     * Adds the {@link Fixture.parent} to the DOM, causing the
+     * connect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    connect(): Promise<void>;
+    /**
+     * Removes the {@link Fixture.parent} from the DOM, causing the
+     * disconnect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Creates a test fixture suitable for testing custom elements, templates, and bindings.
+ * @param templateNameOrRegistry - An HTML template or single element name to create the fixture for.
+ * @param options - Enables customizing fixture creation behavior.
+ * @returns A promise of the test fixture {@link Fixture}.
+ *
+ * @public
+ * @remarks
+ * Yields control to the caller one Microtask later, in order to
+ * ensure that the DOM has settled. This has changed in the latest version of FAST!
+ */
+export declare function fixture<TElement = HTMLElement>(templateNameOrRegistry: ViewTemplate | string | FoundationElementRegistry<FoundationElementDefinition, Constructable<TElement>> | [
+FoundationElementRegistry<FoundationElementDefinition, Constructable<TElement>>,
+...FoundationElementRegistry<FoundationElementDefinition, Constructable>[]
+], options?: FixtureOptions): Promise<Fixture<TElement>>;
+
+/**
+ * Options used to customize the creation of the unit test fixture.
+ * @public
+ */
+export declare interface FixtureOptions {
+    /**
+     * The document to run the fixture in.
+     * @defaultValue `globalThis.document`
+     */
+    document?: Document;
+    /**
+     * The parent element to append the fixture to.
+     * @defaultValue An instance of `HTMLDivElement`.
+     */
+    parent?: HTMLElement;
+    /**
+     * The data source to bind the HTML to.
+     * @defaultValue An empty object.
+     */
+    source?: any;
+    /**
+     * The execution context to use during binding.
+     * @defaultValue {@link @microsoft/fast-element#defaultExecutionContext}
+     */
+    context?: ExecutionContext;
+    /**
+     * A pre-configured design system instance used in setting up the fixture.
+     */
+    designSystem?: DesignSystem;
+}
+
+/**
+ * Test logger
+ * @public
+ * @remarks
+ * Exported so you can set log levels differently across packages when needed.
+ */
+export declare const logger: Logger;
+
+/**
+ * Logic suite context interface
+ * @public
+ */
+export declare interface LogicContext {
+    /**
+     * @privateRemarks
+     * Not hardening the typing on this to RunCases until get a feel for usages.
+     */
+    runCases?(fn: (value: any) => any, cases: [any, any, assert.Message?][]): void;
+}
+
+export { Registration }
+
+/**
+ * Resets the history of the spied functions on the objects so previous running tests
+ * don't affect the current test.
+ * Must be called at the end of every test even if not asserting on the spies.
+ * @param wrapper - `WithTestHarness<T>` object to reset
+ * @public
+ */
+export declare function resetTestHarness<T>(wrapper: WithTestHarness<T>): void;
+
+/**
+ * Restores the spied functions back to the original functions without the spies.
+ * @param wrapper - `WithTestHarness<T>` object to restore
+ * @public
+ */
+export declare function restoreTestHarness<T>(wrapper: WithTestHarness<T>): void;
+
+/**
+ * @public
+ */
+export declare type RunCases = (fn: (...args: unknown[]) => unknown, cases: [unknown[], unknown, string?][], assertion?: (...args: unknown[]) => void) => void;
+
+/**
+ * Assert a set of test cases.
+ * @param fn - The function to test.
+ * @param cases - An array of test cases to run against the function.
+ * @param assertion - Optional uvu assertion method, defaults to assert.equal.
+ * @public
+ * @remarks
+ * This is available as part of the suite context, but can also be run standalone.
+ */
+export declare function runCases(fn: (...args: unknown[]) => unknown, cases: [unknown[], unknown, string?][], assertion?: (...args: unknown[]) => void): void;
+
+export { sinon_2 as sinon }
+
+/**
+ * Crates an object with a key value pair for each spied function
+ * where the key is the function name and the value is the sinon wrapped
+ * spy function
+ * @public
+ * @typeParam T - object with keys where values are functions
+ */
+export declare type SinonWrapper<T extends {
+    [K in keyof T]: (...args: any) => any;
+}> = {
+    [K in keyof T]: sinon_3.SinonSpy<Parameters<T[K]>, ReturnType<T[K]>>;
+};
+
+/**
+ * Filters out all key/value pairs which are not functions, and omits the constructor
+ * @public
+ */
+export declare type SpiedFunctions<T> = Omit<FilterConditionally<T, (...args: any[]) => any>, 'constructor'>;
+
+export { suite }
+
+/**
+ * Defines the Generic type for a test Suite `T` the callback function
+ * required to assert on type `T`.
+ * @typeParam T - the top level class we are testing
+ * @public
+ */
+export declare type SuiteCallback<T> = uvu.Callback<ComponentContext<T>>;
+
+export { test }
+
+/**
+ * Decorator: Used on a test harness class based on a `FoundationElement` to give it extra functionality
+ * which can be used during testing. *Important* this is to be used on a parent element compared to
+ * the element under test.
+ *
+ *
+ * @remarks
+ * Access the test functionality using the type with {@link WithTestHarness}
+ *
+ * Reset after each test with {@link resetTestHarness}
+ *
+ * @example
+ *
+ * // Testing the first function call
+ * async (\{ element \}) =\> \{
+ *
+ assert.ok(
+ element.layout.addItemFromChild.calledWith(\{
+ type: 'component',
+ componentType: 'test',
+ title: `Item test`,
+ reorderEnabled: true,
+ isClosable: false,
+ size: undefined,
+ \})
+ );
+ *
+ *   // Reset the tester at the end of every test even if you don't assert on any of it!
+ *   resetTestHarness(element.layout);
+ * \}
+ *
+ * @public
+ */
+export declare function testSpy(constructor: Function): void;
+
+/**
+ * Timeout utility.
+ *
+ * @example A promise that never ends.
+ * ```ts
+ * test(
+ *   'should fail',
+ *   timeout(async () => {
+ *     await new Promise(() => {});
+ *     assert.ok(true);
+ *   }, 5_000),
+ * );
+ * ```
+ *
+ * @example A slow API.
+ * ```ts
+ * test(
+ *   'should fail',
+ *   timeout(async () => {
+ *     const slowMockAPI = delayedResolve({ foo: 'bar' }, 4_000);
+ *     await slowMockAPI();
+ *     assert.unreachable('should have timed out');
+ *   }, 2_000),
+ * );
+ * ```
+ *
+ * @param callback - The async test function.
+ * @param duration - An optional duration in milliseconds. Defaults to 5_000.
+ * @public
+ */
+export declare const timeout: (callback: (context: any) => Promise<any>, duration?: number) => (context: any) => Promise<any>;
+
+export { uvu }
+
+/**
+ * Type can be used  to inform Typescript the object decorated with {@link testSpy} has function
+ * spies which can be interacted upon their normal function reference
+ * @public
+ */
+export declare type WithTestHarness<T extends {
+    [k in keyof T]: any;
+}> = T & SinonWrapper<SpiedFunctions<T>>;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.34.9"
+    }
+  ]
+}

package/docs/api/foundation-testing.delayedresolve.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [delayedResolve](./foundation-testing.delayedresolve.md)
+
+## delayedResolve variable
+
+Delayed resolve utility.
+
+**Signature:**
+
+```typescript
+delayedResolve: (result: unknown, duration?: number) => () => Promise<unknown>
+```
+
+## Example
+
+
+```ts
+test('delayed resolve', async () => {
+  const mockAPI = delayedResolve({ foo: 'bar' }, 2_000);
+  const result = await mockAPI();
+});
+```
+

package/docs/api/foundation-testing.md

@@ -29,7 +29,9 @@
 
 |  Variable | Description |
 |  --- | --- |
+|  [delayedResolve](./foundation-testing.delayedresolve.md) | Delayed resolve utility. |
 |  [logger](./foundation-testing.logger.md) | Test logger |
+|  [timeout](./foundation-testing.timeout.md) | Timeout utility. |
 
 ## Type Aliases
 

package/docs/api/foundation-testing.timeout.md

@@ -0,0 +1,43 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [timeout](./foundation-testing.timeout.md)
+
+## timeout variable
+
+Timeout utility.
+
+**Signature:**
+
+```typescript
+timeout: (callback: (context: any) => Promise<any>, duration?: number) => (context: any) => Promise<any>
+```
+
+## Example 1
+
+A promise that never ends.
+
+```ts
+test(
+  'should fail',
+  timeout(async () => {
+    await new Promise(() => {});
+    assert.ok(true);
+  }, 5_000),
+);
+```
+
+## Example 2
+
+A slow API.
+
+```ts
+test(
+  'should fail',
+  timeout(async () => {
+    const slowMockAPI = delayedResolve({ foo: 'bar' }, 4_000);
+    await slowMockAPI();
+    assert.unreachable('should have timed out');
+  }, 2_000),
+);
+```
+

package/docs/api-report.md

@@ -16,6 +16,7 @@ import { HTMLView } from '@microsoft/fast-element';
 import { Logger } from '@genesislcap/foundation-utils';
 import { Registration } from '@microsoft/fast-foundation';
 import { default as sinon_2 } from 'sinon';
+import { default as sinon_3 } from 'sinon';
 import { suite } from 'uvu';
 import { test } from 'uvu';
 import { uvu } from 'uvu';
@@ -39,6 +40,9 @@ export function createComponentSuite<TElement = HTMLElement>(title: string, elem
 // @public
 export function createLogicSuite<TContext = LogicContext>(title: string, context?: TContext): uvu.Test<TContext>;
 
+// @public
+export const delayedResolve: (result: unknown, duration?: number) => () => Promise<unknown>;
+
 // @public (undocumented)
 export type ElementGetter = () => FoundationElementRegistry<FoundationElementDefinition, FoundationElement>;
 
@@ -102,11 +106,13 @@ export type RunCases = (fn: (...args: unknown[]) => unknown, cases: [unknown[],
 // @public
 export function runCases(fn: (...args: unknown[]) => unknown, cases: [unknown[], unknown, string?][], assertion?: (...args: unknown[]) => void): void;
 
+export { sinon_2 as sinon }
+
 // @public
 export type SinonWrapper<T extends {
     [K in keyof T]: (...args: any) => any;
 }> = {
-    [K in keyof T]: sinon_2.SinonSpy<Parameters<T[K]>, ReturnType<T[K]>>;
+    [K in keyof T]: sinon_3.SinonSpy<Parameters<T[K]>, ReturnType<T[K]>>;
 };
 
 // @public
@@ -122,6 +128,9 @@ export { test }
 // @public
 export function testSpy(constructor: Function): void;
 
+// @public
+export const timeout: (callback: (context: any) => Promise<any>, duration?: number) => (context: any) => Promise<any>;
+
 export { uvu }
 
 // @public

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-testing",
   "description": "Genesis Foundation Testing",
-  "version": "14.68.2",
+  "version": "14.68.3-alpha-43b6152.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -33,18 +33,23 @@
     "PORT": 3050
   },
   "scripts": {
-    "build": "npm run clean && tsc -b ./tsconfig.json",
+    "api:extract": "api-extractor run",
+    "api:document": "api-documenter markdown -i dist -o docs/api",
+    "build": "npm run clean && tsc -b ./tsconfig.json && npm run api:extract && npm run api:document",
     "clean": "rimraf dist tsconfig.tsbuildinfo",
-    "dev": "tsc -b ./tsconfig.json -w"
+    "dev": "tsc -b ./tsconfig.json -w",
+    "test": "uvu -r tsm --tsmconfig ./src/tsm/tsm.ts -r @esbuild-kit/cjs-loader -r ./src/jsdom/setup.ts . test.ts"
   },
   "devDependencies": {
+    "@microsoft/api-documenter": "^7.19.13",
+    "@microsoft/api-extractor": "7.34.9",
     "@types/node": "^20.3.1",
     "@types/sinon": "^10.0.13",
     "rimraf": "^3.0.2",
     "typescript": "^4.5.5"
   },
   "dependencies": {
-    "@genesislcap/foundation-utils": "14.68.2",
+    "@genesislcap/foundation-utils": "14.68.3-alpha-43b6152.0",
     "@microsoft/fast-element": "^1.7.0",
     "@microsoft/fast-foundation": "^2.33.2",
     "@playwright/test": "^1.18.1",
@@ -65,5 +70,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5366046018e36151b75f74ec6a088aed80b12686"
+  "gitHead": "86cd12b91d5e5abfc932bb89286f0ff71b85d72f"
 }