@genesislcap/foundation-testing 14.30.3 → 14.31.0

package/dist/foundation-testing.d.ts

@@ -1,384 +0,0 @@
-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 { 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>;
-
-/**
- * @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;
-
-/**
- * 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_2.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;
-
-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

@@ -1,11 +0,0 @@
-// 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.4"
-    }
-  ]
-}