@genesislcap/foundation-testing 10.3.1 → 11.3.0

package/dist/foundation-testing.api.json

@@ -580,6 +580,158 @@
             "endIndex": 8
           }
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!Equal:type",
+          "docComment": "/**\n * Expects that the type parameter X is equal to Y, returning true or false\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type Equal<X, Y> = "
+            },
+            {
+              "kind": "Content",
+              "text": "(<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/types.ts",
+          "releaseTag": "Public",
+          "name": "Equal",
+          "typeParameters": [
+            {
+              "typeParameterName": "X",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            },
+            {
+              "typeParameterName": "Y",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!Expect:type",
+          "docComment": "/**\n * Expects that the type parameter T resolves to true, or will be a typescript error\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type Expect<T extends "
+            },
+            {
+              "kind": "Content",
+              "text": "true"
+            },
+            {
+              "kind": "Content",
+              "text": "> = "
+            },
+            {
+              "kind": "Content",
+              "text": "T"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/types.ts",
+          "releaseTag": "Public",
+          "name": "Expect",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!FilterConditionally:type",
+          "docComment": "/**\n * Filters out key/value pairs from an object where they value does not match a condition\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type FilterConditionally<Source, Condition> = "
+            },
+            {
+              "kind": "Reference",
+              "text": "Pick",
+              "canonicalReference": "!Pick:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<Source, {\n    [K in keyof Source]: Source[K] extends Condition ? K : never;\n}[keyof Source]>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/harness.ts",
+          "releaseTag": "Public",
+          "name": "FilterConditionally",
+          "typeParameters": [
+            {
+              "typeParameterName": "Source",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            },
+            {
+              "typeParameterName": "Condition",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 3
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/foundation-testing!fixture:function(1)",
@@ -1281,6 +1433,360 @@
             }
           ],
           "extendsTokenRanges": []
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-testing!resetTestHarness:function(1)",
+          "docComment": "/**\n * Resets items tracked during testing such as calls to spied functions. Must be called at the end of every test even if not asserting on the spies.\n *\n * @param wrapper - `WithTestHarness<T>` object to reset\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function resetTestHarness<T>(wrapper: "
+            },
+            {
+              "kind": "Reference",
+              "text": "WithTestHarness",
+              "canonicalReference": "@genesislcap/foundation-testing!WithTestHarness:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T>"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/harness.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 4,
+            "endIndex": 5
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "wrapper",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isOptional": false
+            }
+          ],
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "resetTestHarness"
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!SinonWrapper:type",
+          "docComment": "/**\n * 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\n *\n * @typeParam T - object with keys where values are functions\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type SinonWrapper<T extends "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    [K in keyof T]: (...args: any) => any;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": "> = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    [K in keyof T]: "
+            },
+            {
+              "kind": "Reference",
+              "text": "sinon.SinonSpy",
+              "canonicalReference": "@types/sinon!Sinon.SinonSpy:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "Parameters",
+              "canonicalReference": "!Parameters:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T[K]>, "
+            },
+            {
+              "kind": "Reference",
+              "text": "ReturnType",
+              "canonicalReference": "!ReturnType:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T[K]>>;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/harness.ts",
+          "releaseTag": "Public",
+          "name": "SinonWrapper",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 10
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!SpiedFunctions:type",
+          "docComment": "/**\n * Filters out all key/value pairs which are not functions, and omits the constructor\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type SpiedFunctions<T> = "
+            },
+            {
+              "kind": "Reference",
+              "text": "Omit",
+              "canonicalReference": "!Omit:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "FilterConditionally",
+              "canonicalReference": "@genesislcap/foundation-testing!FilterConditionally:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T, (...args: any[]) => any>, 'constructor'>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/harness.ts",
+          "releaseTag": "Public",
+          "name": "SpiedFunctions",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!SuiteCallback:type",
+          "docComment": "/**\n * Defines the Generic type for a test Suite `T` the callback function required to assert on type `T`.\n *\n * @typeParam T - the top level class we are testing\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type SuiteCallback<T> = "
+            },
+            {
+              "kind": "Reference",
+              "text": "uvu.Callback",
+              "canonicalReference": "uvu!uvu.Callback:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "ComponentContext",
+              "canonicalReference": "@genesislcap/foundation-testing!ComponentContext:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<T>>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/suite/suite.ts",
+          "releaseTag": "Public",
+          "name": "SuiteCallback",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-testing!testSpy:function(1)",
+          "docComment": "/**\n * 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.\n *\n * @remarks\n *\n * Access the test functionality using the type with {@link WithTestHarness}\n *\n * Reset after each test with {@link resetTestHarness}\n *\n * @example\n *\n * // Testing the first function call async (\\{ element \\}) =\\> \\{\n *\n * assert.ok( element.layout.addItemFromChild.calledWith(\\{ type: 'component', componentType: 'test', title: `Item test`, reorderEnabled: true, isClosable: false, size: undefined, \\}) );\n *\n * // Reset the tester at the end of every test even if you don't assert on any of it! resetTestHarness(element.layout); \\}\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function testSpy(constructor: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Function",
+              "canonicalReference": "!Function:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/harness.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "constructor",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "testSpy"
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-testing!WithTestHarness:type",
+          "docComment": "/**\n * 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\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type WithTestHarness<T extends "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    [k in keyof T]: any;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": "> = "
+            },
+            {
+              "kind": "Content",
+              "text": "T & "
+            },
+            {
+              "kind": "Reference",
+              "text": "SinonWrapper",
+              "canonicalReference": "@genesislcap/foundation-testing!SinonWrapper:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "SpiedFunctions",
+              "canonicalReference": "@genesislcap/foundation-testing!SpiedFunctions:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T>>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/utils/harness.ts",
+          "releaseTag": "Public",
+          "name": "WithTestHarness",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 8
+          }
         }
       ]
     }

package/dist/foundation-testing.d.ts

@@ -9,6 +9,7 @@ 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 as suite_2 } from 'uvu';
 import { test as test_2 } from 'uvu';
 import { uvu } from 'uvu';
@@ -135,6 +136,26 @@ export declare function createLogicSuite<TContext = LogicContext>(title: string,
  */
 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
@@ -246,10 +267,89 @@ export declare interface LogicContext {
 
 export { Registration }
 
+/**
+ * Resets items tracked during testing such as calls to spied functions.
+ * 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;
+
+/**
+ * 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_2 as 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_2 as 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/docs/api/foundation-testing.equal.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [Equal](./foundation-testing.equal.md)
+
+## Equal type
+
+Expects that the type parameter X is equal to Y, returning true or false
+
+**Signature:**
+
+```typescript
+export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+```

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

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [Expect](./foundation-testing.expect.md)
+
+## Expect type
+
+Expects that the type parameter T resolves to true, or will be a typescript error
+
+**Signature:**
+
+```typescript
+export type Expect<T extends true> = T;
+```

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

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [FilterConditionally](./foundation-testing.filterconditionally.md)
+
+## FilterConditionally type
+
+Filters out key/value pairs from an object where they value does not match a condition
+
+**Signature:**
+
+```typescript
+export type FilterConditionally<Source, Condition> = Pick<Source, {
+    [K in keyof Source]: Source[K] extends Condition ? K : never;
+}[keyof Source]>;
+```