@augment-vir/test 30.0.0 → 30.0.1

package/README.md

@@ -0,0 +1,10 @@
+# @augment-vir/test
+
+A universal testing suite that works with Mocha style test runners _and_ Node.js's built-in test runner with the following main exports:
+
+-   [`describe`](https://electrovir.github.io/augment-vir/functions/describe.html): the normal describe test suite function, automatically imported based on the current environment.
+-   [`it`](https://electrovir.github.io/augment-vir/functions/it.html): the normal it test function, automatically imported based on the current environment.
+-   [`itCases`](https://electrovir.github.io/augment-vir/functions/itCases.html): a succinct way to test lots of inputs and outputs to a single function.
+-   [`testWeb`](https://electrovir.github.io/augment-vir/variables/testWeb.html): a API of web-testing utilities, only available in browser environments.
+
+See the docs under `Test`, or `Package: @augment-vir/test` here: https://electrovir.github.io/augment-vir

package/dist/augments/test-web.d.ts

@@ -1,13 +1,52 @@
 import { RuntimeEnvError } from '@augment-vir/core';
 declare function importWebTestApi(): Promise<RuntimeEnvError | {
-    cleanupRender: typeof import("@open-wc/testing-helpers/types/src/fixtureWrapper").fixtureCleanup;
+    /**
+     * Cleans up all rendered test HTML by removing the actual wrapper nodes. Common use case is
+     * at the end of each test.
+     */
+    cleanupRender: typeof import("@open-wc/testing-helpers").fixtureCleanup;
+    /** Clicks the center of the given element. */
     click: typeof import("../test-web/click-element").clickElement;
+    /** Deletes all text that has been typed into the given `<input>` element. */
     deleteInputText: typeof import("../test-web/type-into-element").deleteAllTextInInput;
+    /** Repeatedly tries to focus the given element until it is focused. */
     ensureFocus: typeof import("../test-web/element-test-focus").focusElement;
+    /** Moves the mouse to the center of the given element. */
     moveMouseTo: typeof import("../test-web/click-element").moveToElement;
-    render: typeof import("@open-wc/testing-helpers/types/src/fixture-no-side-effect").fixture;
-    type: typeof import("../test-web/type-into-element").typeString;
+    /**
+     * Renders a string or TemplateResult and puts it in the DOM via a fixtureWrapper.
+     *
+     * Uses `fixture` from `@open-wc/testing-helpers`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {testWeb} from '@augment-vir/test';
+     * import {html} from 'element-vir';
+     *
+     * const rendered = await testWeb.render(html`
+     *     <${MyElement}><span></span></${MyElement}>
+     * `);
+     * ```
+     *
+     * @returns A Promise that will resolve to the first child of the rendered HTML.
+     */
+    render: typeof import("@open-wc/testing-helpers").fixture;
+    /** Focus the given element and then type the given string. */
     typeIntoInput: typeof import("../test-web/type-into-element").typeStringIntoElement;
+    /**
+     * Types the given string as if it were input by a keyboard. This doesn't try to type into
+     * any element in particular, it'll go wherever the current focus is, if any.
+     */
+    typeText: typeof import("../test-web/type-into-element").typeString;
 }>;
+/**
+ * A suite of web test helpers. This is only accessible within a browser runtime. If accessed
+ * outside of a browser runtime, it'll be an Error instead of a collection of test helpers.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export declare const testWeb: Exclude<Awaited<ReturnType<typeof importWebTestApi>>, Error>;
 export {};

package/dist/augments/test-web.js

@@ -1,21 +1,60 @@
 import { isRuntimeEnv, RuntimeEnv, RuntimeEnvError } from '@augment-vir/core';
 async function importWebTestApi() {
     if (!isRuntimeEnv(RuntimeEnv.Web)) {
-        return new RuntimeEnvError('The testWeb api cannot be used outside of a browser context.');
+        return new RuntimeEnvError("The 'testWeb' api cannot be used outside of a browser context.");
     }
     const { clickElement, moveToElement } = await import('../test-web/click-element');
     const { focusElement } = await import('../test-web/element-test-focus');
-    const { cleanupFixture, renderFixture } = await import('../test-web/open-wc-exports');
     const { deleteAllTextInInput, typeString, typeStringIntoElement } = await import('../test-web/type-into-element');
+    const { fixtureCleanup, fixture } = await import('@open-wc/testing-helpers');
     return {
-        cleanupRender: cleanupFixture,
+        /**
+         * Cleans up all rendered test HTML by removing the actual wrapper nodes. Common use case is
+         * at the end of each test.
+         */
+        cleanupRender: fixtureCleanup,
+        /** Clicks the center of the given element. */
         click: clickElement,
+        /** Deletes all text that has been typed into the given `<input>` element. */
         deleteInputText: deleteAllTextInInput,
+        /** Repeatedly tries to focus the given element until it is focused. */
         ensureFocus: focusElement,
+        /** Moves the mouse to the center of the given element. */
         moveMouseTo: moveToElement,
-        render: renderFixture,
-        type: typeString,
+        /**
+         * Renders a string or TemplateResult and puts it in the DOM via a fixtureWrapper.
+         *
+         * Uses `fixture` from `@open-wc/testing-helpers`.
+         *
+         * @example
+         *
+         * ```ts
+         * import {testWeb} from '@augment-vir/test';
+         * import {html} from 'element-vir';
+         *
+         * const rendered = await testWeb.render(html`
+         *     <${MyElement}><span></span></${MyElement}>
+         * `);
+         * ```
+         *
+         * @returns A Promise that will resolve to the first child of the rendered HTML.
+         */
+        render: fixture,
+        /** Focus the given element and then type the given string. */
         typeIntoInput: typeStringIntoElement,
+        /**
+         * Types the given string as if it were input by a keyboard. This doesn't try to type into
+         * any element in particular, it'll go wherever the current focus is, if any.
+         */
+        typeText: typeString,
     };
 }
+/**
+ * A suite of web test helpers. This is only accessible within a browser runtime. If accessed
+ * outside of a browser runtime, it'll be an Error instead of a collection of test helpers.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export const testWeb = (await importWebTestApi());

package/dist/augments/universal-testing-suite/it-cases.d.ts

@@ -1,5 +1,12 @@
 import { ErrorMatchOptions, type CustomOutputAsserter } from '@augment-vir/assert';
 import { type AnyFunction, type TypedFunction } from '@augment-vir/core';
+/**
+ * Base test case for {@link itCases}.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export type BaseTestCase<OutputGeneric> = {
     it: string;
     only?: boolean | undefined;
@@ -9,13 +16,33 @@ export type BaseTestCase<OutputGeneric> = {
 } | {
     throws: ErrorMatchOptions | undefined;
 });
-export type OutputTestCaseSingleInput<FunctionToTest extends AnyFunction> = {
+/**
+ * Input for a function test that only has a single input.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export type FunctionTestCaseSingleInput<FunctionToTest extends AnyFunction> = {
     input: Parameters<FunctionToTest>[0];
 } & BaseTestCase<Awaited<ReturnType<FunctionToTest>>>;
-export type OutputTestCaseMultipleInputs<FunctionToTest extends AnyFunction> = {
+/**
+ * Input for a function test that has multiple inputs.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export type FunctionTestCaseMultipleInputs<FunctionToTest extends AnyFunction> = {
     inputs: Parameters<FunctionToTest>['length'] extends never ? FunctionToTest extends TypedFunction<[infer ArgumentsType], any> ? ArgumentsType[] : never : Parameters<FunctionToTest>;
 } & BaseTestCase<Awaited<ReturnType<FunctionToTest>>>;
-export type FunctionTestCase<FunctionToTest extends AnyFunction> = 1 extends Parameters<FunctionToTest>['length'] ? Parameters<FunctionToTest>['length'] extends 0 | 1 ? OutputTestCaseSingleInput<FunctionToTest> : OutputTestCaseMultipleInputs<FunctionToTest> : 0 extends Parameters<FunctionToTest>['length'] ? BaseTestCase<Awaited<ReturnType<FunctionToTest>>> : OutputTestCaseMultipleInputs<FunctionToTest>;
-export declare function itCases<FunctionToTest extends AnyFunction>(functionToTest: FunctionToTest, testCases: ReadonlyArray<FunctionTestCase<typeof functionToTest>>): unknown[];
-export declare function itCases<FunctionToTest extends AnyFunction>(functionToTest: FunctionToTest, customAsserter: CustomOutputAsserter<typeof functionToTest>, testCases: ReadonlyArray<FunctionTestCase<typeof functionToTest>>): unknown[];
-export declare function itCases<FunctionToTest extends AnyFunction>(functionToTest: FunctionToTest, testCasesOrCustomAsserter: CustomOutputAsserter<typeof functionToTest> | ReadonlyArray<FunctionTestCase<typeof functionToTest>>, maybeTestCases?: ReadonlyArray<FunctionTestCase<typeof functionToTest>> | undefined): unknown[];
+/**
+ * A function test case used for {@link itCases}.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export type FunctionTestCase<FunctionToTest extends AnyFunction> = 1 extends Parameters<FunctionToTest>['length'] ? Parameters<FunctionToTest>['length'] extends 0 | 1 ? FunctionTestCaseSingleInput<FunctionToTest> : FunctionTestCaseMultipleInputs<FunctionToTest> : 0 extends Parameters<FunctionToTest>['length'] ? BaseTestCase<Awaited<ReturnType<FunctionToTest>>> : FunctionTestCaseMultipleInputs<FunctionToTest>;
+export declare function itCases<const FunctionToTest extends AnyFunction>(functionToTest: FunctionToTest, customAsserter: CustomOutputAsserter<NoInfer<FunctionToTest>>, testCases: ReadonlyArray<FunctionTestCase<NoInfer<FunctionToTest>>>): unknown[];
+export declare function itCases<const FunctionToTest extends AnyFunction>(functionToTest: FunctionToTest, testCases: ReadonlyArray<FunctionTestCase<NoInfer<FunctionToTest>>>): unknown[];

package/dist/augments/universal-testing-suite/it-cases.js

@@ -2,6 +2,16 @@ import { assert, check } from '@augment-vir/assert';
 import { ensureErrorAndPrependMessage, } from '@augment-vir/core';
 import { it } from './universal-it.js';
 const unsetError = Symbol('unset-error');
+/**
+ * Succinctly run many input / output tests for a pure function without repeating `it` boilerplate.
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export function itCases(functionToTest, testCasesOrCustomAsserter, maybeTestCases) {
     const testCases = (maybeTestCases ||
         testCasesOrCustomAsserter);

package/dist/augments/universal-testing-suite/universal-describe.d.ts

@@ -1,20 +1,55 @@
 /**
- * A minimal interface for `describe` that is compatible with both Mocha ({@link mochaDescribe}) and
- * Node.js's built-in test runner ({@link nodeDescribe}). This is used for {@link describe}.
+ * A minimal interface for {@link describe}. This is used in {@link UniversalDescribe}.
  *
- * @category Testing:Common
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export type UniversalBareDescribe = (this: void, describeThis: string, callback: (this: void) => void) => void;
+/**
+ * The type for {@link describe}.
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export type UniversalDescribe = UniversalBareDescribe & {
     only: UniversalBareDescribe;
     skip: UniversalBareDescribe;
 };
 /**
- * An interface for the `describe` test function that is compatible with both Mocha
- * ({@link mochaDescribe}) and Node.js's built-in test runner ({@link nodeDescribe}). This is used in
- * {@link UniversalDescribe}. The only difference is that this type does not include `only` and
- * `skip`.
+ * A test suite declaration. This can be used in both web tests _and_ node tests, so you only have
+ * import from a single place and learn a single interface.
  *
- * @category Testing:Common
+ * This should be passed a _noun_ (preferably a single word, when possible) of what is going to be
+ * tested inside the test suite. Its callback should call `it` from this same package.
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @example
+ *
+ * ```ts
+ * import {describe, it} from '@augment-vir/test';
+ *
+ * describe(myFunction.name, () => {
+ *     it('does a thing', () => {
+ *         myFunction();
+ *     });
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export type UniversalBareDescribe = (this: void, describeThis: string, callback: (this: void) => void) => void;
 export declare const describe: UniversalDescribe;

package/dist/augments/universal-testing-suite/universal-describe.js

@@ -6,4 +6,31 @@ const describes = isRuntimeEnv(RuntimeEnv.Node)
     : {
         mocha: globalThis.describe,
     };
-export const describe = (describes.mocha || describes.node);
+/**
+ * A test suite declaration. This can be used in both web tests _and_ node tests, so you only have
+ * import from a single place and learn a single interface.
+ *
+ * This should be passed a _noun_ (preferably a single word, when possible) of what is going to be
+ * tested inside the test suite. Its callback should call `it` from this same package.
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @example
+ *
+ * ```ts
+ * import {describe, it} from '@augment-vir/test';
+ *
+ * describe(myFunction.name, () => {
+ *     it('does a thing', () => {
+ *         myFunction();
+ *     });
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export const describe = describes.mocha || describes.node;

package/dist/augments/universal-testing-suite/universal-it.d.ts

@@ -1,27 +1,69 @@
 import { UniversalContext } from './universal-test-context.js';
 /**
- * An interface for an `it` callback that is compatible with both Mocha ({@link mochaIt}) and
- * Node.js's built-in test runner ({@link nodeIt}) and used in {@link UniversalIt}.
+ * An interface for an {@link it} callback. Used in {@link UniversalBareIt}.
  *
- * @category Testing:Common
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export type UniversalItCallback = (this: void, context: UniversalContext) => Promise<void> | void;
 /**
- * An interface for the `it` test function that is compatible with both Mocha ({@link mochaIt}) and
- * Node.js's built-in test runner ({@link nodeIt}). This is used in {@link UniversalIt}. The only
- * difference is that this type does not include `only` and `skip`.
+ * A minimal interface for {@link it}. This is used in {@link UniversalIt}.
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
  *
- * @category Testing:Common
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export type UniversalBareIt = (this: void, doesThis: string, callback: UniversalItCallback) => void;
 /**
- * A minimal interface for `it` that is compatible with both Mocha ({@link mochaIt}) and Node.js's
- * built-in test runner ({@link nodeIt}). This is used for {@link it}.
+ * The type for {@link it}.
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
  *
- * @category Testing:Common
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export type UniversalIt = UniversalBareIt & {
     only: UniversalBareIt;
     skip: UniversalBareIt;
 };
+/**
+ * A single test declaration. This can be used in both web tests _and_ node tests, so you only have
+ * import from a single place and learn a single interface.
+ *
+ * This should be nested within a `describe` call. The `it` name should form a sentence fragment
+ * that is attached to the parent `describe`'s input. The sentence should ultimately read like this:
+ * "myFunction, it does a thing" (as shown in the example below).
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @example
+ *
+ * ```ts
+ * import {describe, it} from '@augment-vir/test';
+ *
+ * describe(myFunction.name, () => {
+ *     it('does a thing', () => {
+ *         myFunction();
+ *     });
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export declare const it: UniversalIt;

package/dist/augments/universal-testing-suite/universal-it.js

@@ -6,4 +6,32 @@ const its = isRuntimeEnv(RuntimeEnv.Node)
     : {
         mocha: globalThis.it,
     };
-export const it = (its.mocha || its.node);
+/**
+ * A single test declaration. This can be used in both web tests _and_ node tests, so you only have
+ * import from a single place and learn a single interface.
+ *
+ * This should be nested within a `describe` call. The `it` name should form a sentence fragment
+ * that is attached to the parent `describe`'s input. The sentence should ultimately read like this:
+ * "myFunction, it does a thing" (as shown in the example below).
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @example
+ *
+ * ```ts
+ * import {describe, it} from '@augment-vir/test';
+ *
+ * describe(myFunction.name, () => {
+ *     it('does a thing', () => {
+ *         myFunction();
+ *     });
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export const it = its.mocha || its.node;

package/dist/augments/universal-testing-suite/universal-test-context.d.ts

@@ -1,14 +1,77 @@
 import { RuntimeEnv } from '@augment-vir/core';
 import { TestContext as NodeTestContextImport } from 'node:test';
-import type { Mocha } from '../../mocha.js';
-export type MochaTestContext = Mocha.Context;
+import type { MochaContext } from '../../mocha-types.js';
+/**
+ * The test context for [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or
+ * other Mocha-style test runners.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export type MochaTestContext = MochaContext;
+/**
+ * The test context for [Node.js's test runner](https://nodejs.org/api/test.html).
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export type NodeTestContext = NodeTestContextImport;
+/**
+ * Test context provided by `it`'s callback.
+ *
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
+ * runners.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export type UniversalContext = NodeTestContext | MochaTestContext;
+/**
+ * Test context by runtime env when [Node.js's test runner](https://nodejs.org/api/test.html) is
+ * used for Node tests and [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) is
+ * used for web tests.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export type ContextByEnv = {
     [RuntimeEnv.Node]: NodeTestContext;
-    [RuntimeEnv.Web]: Mocha.Context;
+    [RuntimeEnv.Web]: MochaContext;
 };
+/**
+ * Ensures that the given context is for the given env, otherwise throws an Error.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export declare function ensureTestContext<const SpecificEnv extends RuntimeEnv>(context: UniversalContext, env: RuntimeEnv): ContextByEnv[SpecificEnv];
+/**
+ * Asserts that the given context is for the given env, otherwise throws an Error.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export declare function assertTestContext<const SpecificEnv extends RuntimeEnv>(context: UniversalContext, env: RuntimeEnv): asserts context is ContextByEnv[SpecificEnv];
+/**
+ * Checks that the given context is for the given env.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export declare function isTestContext<const SpecificEnv extends RuntimeEnv>(context: UniversalContext, env: RuntimeEnv): context is ContextByEnv[SpecificEnv];
+/**
+ * Determine the env for the given test context.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export declare function determineTestContextEnv(context: UniversalContext): RuntimeEnv;

package/dist/augments/universal-testing-suite/universal-test-context.js

@@ -1,14 +1,35 @@
 import { RuntimeEnv } from '@augment-vir/core';
+/**
+ * Ensures that the given context is for the given env, otherwise throws an Error.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export function ensureTestContext(context, env) {
     assertTestContext(context, env);
     return context;
 }
+/**
+ * Asserts that the given context is for the given env, otherwise throws an Error.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export function assertTestContext(context, env) {
     const actualEnv = determineTestContextEnv(context);
     if (actualEnv !== env) {
-        throw new TypeError();
+        throw new TypeError(`Provided test context is not for the expected env '${env}'.`);
     }
 }
+/**
+ * Checks that the given context is for the given env.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export function isTestContext(context, env) {
     try {
         assertTestContext(context, env);
@@ -19,6 +40,13 @@ export function isTestContext(context, env) {
     }
 }
 const nodeOnlyCheckKey = 'diagnostic';
+/**
+ * Determine the env for the given test context.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
 export function determineTestContextEnv(context) {
     return context[nodeOnlyCheckKey] ? RuntimeEnv.Node : RuntimeEnv.Web;
 }

package/dist/mocha-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Extracted from https://www.npmjs.com/package/@types/mocha/v/10.0.7 with modifications to prevent
+ * leakage of global types.
+ *
+ * The original code has the following license:
+ *
+ * MIT License
+ *
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+ * associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute,
+ * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+ * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
+ */
+interface Runnable extends NodeJS.EventEmitter {
+    on(event: 'error', listener: (error: any) => void): this;
+    once(event: 'error', listener: (error: any) => void): this;
+    addListener(event: 'error', listener: (error: any) => void): this;
+    removeListener(event: 'error', listener: (error: any) => void): this;
+    prependListener(event: 'error', listener: (error: any) => void): this;
+    prependOnceListener(event: 'error', listener: (error: any) => void): this;
+    emit(name: 'error', error: any): boolean;
+}
+interface Runnable extends NodeJS.EventEmitter {
+    on(event: string, listener: (...args: any[]) => void): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    addListener(event: string, listener: (...args: any[]) => void): this;
+    removeListener(event: string, listener: (...args: any[]) => void): this;
+    prependListener(event: string, listener: (...args: any[]) => void): this;
+    prependOnceListener(event: string, listener: (...args: any[]) => void): this;
+    emit(name: string, ...args: any[]): boolean;
+}
+interface Test extends Runnable {
+    type: 'test';
+    speed?: 'slow' | 'medium' | 'fast' | undefined;
+    err?: Error | undefined;
+    clone(): Test;
+}
+export interface MochaContext {
+    test?: Runnable | undefined;
+    currentTest?: Test | undefined;
+    /** Get the context `Runnable`. */
+    runnable(): Runnable;
+    /** Set the context `Runnable`. */
+    runnable(runnable: Runnable): MochaContext;
+    /** Get test timeout. */
+    timeout(): number;
+    /** Set test timeout. */
+    timeout(ms: string | number): MochaContext;
+    /** Get test slowness threshold. */
+    slow(): number;
+    /** Set test slowness threshold. */
+    slow(ms: string | number): MochaContext;
+    /** Mark a test as skipped. */
+    skip(): never;
+    /** Get the number of allowed retries on failed tests. */
+    retries(): number;
+    /** Set the number of allowed retries on failed tests. */
+    retries(n: number): MochaContext;
+    [key: string]: any;
+}
+export {};

package/dist/mocha-types.js

@@ -0,0 +1,26 @@
+/**
+ * Extracted from https://www.npmjs.com/package/@types/mocha/v/10.0.7 with modifications to prevent
+ * leakage of global types.
+ *
+ * The original code has the following license:
+ *
+ * MIT License
+ *
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+ * associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute,
+ * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+ * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
+ */
+export {};

package/dist/test-web/symlinked/animation-frame.d.ts

@@ -1 +1,9 @@
+/**
+ * Wait for an animation frame's duration. Optionally, wait for multiple frames by providing a
+ * `frameCount` input.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function waitForAnimationFrame(frameCount?: number): Promise<void>;

package/dist/test-web/symlinked/animation-frame.js

@@ -1,4 +1,12 @@
 import { DeferredPromise } from '@augment-vir/common';
+/**
+ * Wait for an animation frame's duration. Optionally, wait for multiple frames by providing a
+ * `frameCount` input.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function waitForAnimationFrame(frameCount = 1) {
     const deferredPromise = new DeferredPromise();
     function requestNextFrame() {

package/dist/test-web/symlinked/element-focus.d.ts

@@ -1 +1,8 @@
+/**
+ * Detects whether the given element is currently focused.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function isElementFocused(element: Element): boolean;

package/dist/test-web/symlinked/element-focus.js

@@ -1,3 +1,10 @@
+/**
+ * Detects whether the given element is currently focused.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function isElementFocused(element) {
     return element.matches(':focus');
 }

package/dist/test-web/symlinked/element-position.d.ts

@@ -1,5 +1,38 @@
 import type { Coords } from '@augment-vir/common';
+/**
+ * Checks if the current element is completely visible in its scroll view.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function checkIfEntirelyInScrollView(element: Element): Promise<unknown>;
-export declare function checkIfInScrollView(element: Element, ratio: number): Promise<unknown>;
+/**
+ * Check if the given element is visible in its scroll container to the degree of the given ratio.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export declare function checkIfInScrollView(element: Element, 
+/** A number from 0-1, representing 0% to 100%. */
+ratio: number): Promise<unknown>;
+/**
+ * Get the center of the current element. This is a relatively expensive operation as it uses
+ * [`.getBoundingClientRect()`](https://developer.mozilla.org/docs/Web/API/Element/getBoundingClientRect)
+ * so this should not be called excessively.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function getCenterOfElement(element: Element): Coords;
+/**
+ * Useful for debugging purposes, this sticks an absolutely positioned and brightly colored div at
+ * the given position.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function appendPositionDebugDiv(position: Coords): HTMLDivElement;

package/dist/test-web/symlinked/element-position.js

@@ -1,8 +1,24 @@
 import { assert } from '@augment-vir/assert';
+/**
+ * Checks if the current element is completely visible in its scroll view.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function checkIfEntirelyInScrollView(element) {
     return checkIfInScrollView(element, 1);
 }
-export async function checkIfInScrollView(element, ratio) {
+/**
+ * Check if the given element is visible in its scroll container to the degree of the given ratio.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export async function checkIfInScrollView(element, 
+/** A number from 0-1, representing 0% to 100%. */
+ratio) {
     return new Promise((resolve) => {
         const observer = new IntersectionObserver((entries, observerItself) => {
             assert.isLengthAtLeast(entries, 1);
@@ -12,6 +28,15 @@ export async function checkIfInScrollView(element, ratio) {
         observer.observe(element);
     });
 }
+/**
+ * Get the center of the current element. This is a relatively expensive operation as it uses
+ * [`.getBoundingClientRect()`](https://developer.mozilla.org/docs/Web/API/Element/getBoundingClientRect)
+ * so this should not be called excessively.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function getCenterOfElement(element) {
     const rect = element.getBoundingClientRect();
     return {
@@ -19,6 +44,14 @@ export function getCenterOfElement(element) {
         y: Math.floor((rect.bottom + rect.top) / 2),
     };
 }
+/**
+ * Useful for debugging purposes, this sticks an absolutely positioned and brightly colored div at
+ * the given position.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function appendPositionDebugDiv(position) {
     const div = document.createElement('div');
     div.classList.add('debug');

package/dist/test-web/type-into-element.d.ts

@@ -1,3 +1,3 @@
-export declare function typeString(input: string): Promise<void>;
-export declare function typeStringIntoElement(input: string, inputElement: Readonly<HTMLInputElement>): Promise<void>;
+export declare function typeString(text: string): Promise<void>;
+export declare function typeStringIntoElement(text: string, inputElement: Readonly<HTMLInputElement>): Promise<void>;
 export declare function deleteAllTextInInput(inputElement: Readonly<HTMLInputElement>): Promise<void>;

package/dist/test-web/type-into-element.js

@@ -1,13 +1,13 @@
 import { sendKeys } from '@web/test-runner-commands';
 import { focusElement } from './element-test-focus.js';
-export async function typeString(input) {
+export async function typeString(text) {
     return await sendKeys({
-        type: input,
+        type: text,
     });
 }
-export async function typeStringIntoElement(input, inputElement) {
+export async function typeStringIntoElement(text, inputElement) {
     await focusElement(inputElement);
-    await typeString(input);
+    await typeString(text);
 }
 export async function deleteAllTextInInput(inputElement) {
     const lastValue = inputElement.value;

package/package.json

@@ -1,6 +1,20 @@
 {
     "name": "@augment-vir/test",
-    "version": "30.0.0",
+    "version": "30.0.1",
+    "description": "A universal testing suite that works with Mocha style test runners _and_ Node.js's built-in test runner.",
+    "keywords": [
+        "test",
+        "suite",
+        "augment",
+        "helper",
+        "util",
+        "node",
+        "browser",
+        "backend",
+        "frontend",
+        "vir",
+        "augment-vir"
+    ],
     "homepage": "https://github.com/electrovir/augment-vir",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -20,18 +34,16 @@
     "types": "dist/index.d.ts",
     "scripts": {
         "compile": "virmator compile",
-        "docs": "virmator docs",
         "start": "tsx src/index.ts",
         "test": "concurrently --colors --kill-others-on-fail -c green,blue --names node,web \"npm run test:node\" \"npm run test:web\"",
         "test:coverage": "npm run test",
-        "test:docs": "virmator docs check",
         "test:node": "virmator test --no-deps node 'src/augments/universal-testing-suite/**/*.test.ts'",
         "test:update": "npm test",
         "test:web": "virmator test --no-deps web 'src/test-web/**/*.test.ts'"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.0.0",
-        "@augment-vir/common": "^30.0.0",
+        "@augment-vir/assert": "^30.0.1",
+        "@augment-vir/common": "^30.0.1",
         "@open-wc/testing-helpers": "^3.0.1",
         "type-fest": "^4.25.0"
     },

package/dist/test-web/open-wc-exports.d.ts

@@ -1 +0,0 @@
-export { fixtureCleanup as cleanupFixture, fixture as renderFixture } from '@open-wc/testing-helpers';

package/dist/test-web/open-wc-exports.js

@@ -1 +0,0 @@
-export { fixtureCleanup as cleanupFixture, fixture as renderFixture } from '@open-wc/testing-helpers';