@augment-vir/test 31.53.0 → 31.54.1

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

@@ -1,6 +1,6 @@
 import { RuntimeEnvError } from '@augment-vir/core';
 export { type MenuOptionOptions } from '../test-playwright/get-option.js';
-export { playwrightTeatNameUrlParam, type NavOptions } from '../test-playwright/nav.js';
+export { type NavOptions } from '../test-playwright/nav.js';
 export { type LocatorScreenshotOptions, type SaveScreenshotOptions, type TakeScreenshotOptions, } from '../test-playwright/screenshot.js';
 declare function importPlaywrightTestApi(this: void): Promise<RuntimeEnvError | {
     navigation: {

package/dist/augments/test-playwright.js

@@ -1,5 +1,4 @@
 import { isInsidePlaywrightTest, RuntimeEnvError } from '@augment-vir/core';
-export { playwrightTeatNameUrlParam } from '../test-playwright/nav.js';
 async function importPlaywrightTestApi() {
     if (!isInsidePlaywrightTest()) {
         return new RuntimeEnvError("The 'testPlaywright' api cannot be used outside of a Playwright test context.");

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

@@ -1,4 +1,5 @@
 import { RuntimeEnvError } from '@augment-vir/core';
+import { elementCases } from '../test-web/element-cases.js';
 declare function importWebTestApi(this: void): Promise<RuntimeEnvError | {
     /**
      * Cleans up all rendered test HTML by removing the actual wrapper nodes. Common use case is
@@ -44,6 +45,8 @@ declare function importWebTestApi(this: void): Promise<RuntimeEnvError | {
      * any element in particular, it'll go wherever the current focus is, if any.
      */
     typeText: typeof import("../test-web/type-into-element").typeString;
+    /** Create multiple test cases for element testing. */
+    elementCases: typeof elementCases;
 }>;
 /**
  * A suite of web test helpers. This is only accessible within a browser runtime. If accessed

package/dist/augments/test-web.js

@@ -1,4 +1,5 @@
 import { isRuntimeEnv, RuntimeEnv, RuntimeEnvError } from '@augment-vir/core';
+import { elementCases } from '../test-web/element-cases.js';
 async function importWebTestApi() {
     if (!isRuntimeEnv(RuntimeEnv.Web)) {
         return new RuntimeEnvError("The 'testWeb' api cannot be used outside of a browser context.");
@@ -53,6 +54,8 @@ async function importWebTestApi() {
          * any element in particular, it'll go wherever the current focus is, if any.
          */
         typeText: typeString,
+        /** Create multiple test cases for element testing. */
+        elementCases,
     };
 }
 /**

package/dist/test-web/click-element.js

@@ -1,6 +1,6 @@
-import { sendMouse } from '@web/test-runner-commands';
 import { getCenterOfElement } from './symlinked/element-position.js';
 async function sendMouseToMiddleOfElement(element, operationType) {
+    const { sendMouse } = await import('@web/test-runner-commands');
     const center = getCenterOfElement(element);
     await sendMouse({
         position: [

package/dist/test-web/element-cases.d.ts

@@ -0,0 +1,23 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type DeclarativeElementDefinition, type DefinedTypedEvent, type TypedEvent } from 'element-vir';
+import { type EmptyObject, type IsAny } from 'type-fest';
+import { type UniversalTestContext } from '../augments/universal-testing-suite/universal-test-context.js';
+export type ElementTestCaseExpect = {
+    text: string | string[];
+    events: Map<TypedEvent | DefinedTypedEvent<any, any>, unknown[]>;
+};
+export type ElementTestCase<Definition extends Readonly<DeclarativeElementDefinition>> = {
+    it: string;
+} & (IsAny<Definition> extends true ? {
+    createInputs?: ((testContext: Readonly<UniversalTestContext>) => MaybePromise<any>) | undefined;
+} : Definition['InputsType'] extends EmptyObject ? {
+    createInputs?: never;
+} : {
+    createInputs: (testContext: Readonly<UniversalTestContext>) => MaybePromise<Definition['InputsType']>;
+}) & PartialWithUndefined<{
+    expect: PartialWithUndefined<ElementTestCaseExpect>;
+    act: (instance: Definition['InstanceType']) => MaybePromise<void>;
+    only: boolean;
+    skip: boolean;
+}>;
+export declare function elementCases<const Definition extends Readonly<DeclarativeElementDefinition>>(elementDefinition: Readonly<Definition>, testCases: ReadonlyArray<Readonly<ElementTestCase<Definition>>>): void;

package/dist/test-web/element-cases.js

@@ -0,0 +1,58 @@
+import { assert, waitUntil } from '@augment-vir/assert';
+import { ensureArray } from '@augment-vir/common';
+import { itCasesWithContext, } from '../augments/universal-testing-suite/it-cases-with-context.js';
+import { renderElement } from './render-element.js';
+import { extractElementText } from './symlinked/element-text.js';
+export function elementCases(elementDefinition, testCases) {
+    itCasesWithContext(testRenderElement, () => {
+        /** All assertions are done in the test callback. */
+    }, testCases.map((testCase) => {
+        return {
+            it: testCase.it,
+            inputs: [
+                elementDefinition,
+                testCase,
+            ],
+            throws: undefined,
+        };
+    }));
+}
+async function testRenderElement(testContext, elementDefinition, testCase) {
+    const eventKeys = Array.from(testCase.expect?.events?.keys() || []);
+    const events = new Map(eventKeys.map((key) => {
+        return [
+            key,
+            [],
+        ];
+    }));
+    const inputs = await testCase.createInputs?.(testContext);
+    const instance = await renderElement(elementDefinition, inputs);
+    eventKeys.forEach((eventKey) => {
+        instance.addEventListener(eventKey.type, (event) => {
+            events.get(eventKey)?.push(event.detail);
+        });
+    });
+    await testCase.act?.(instance);
+    await waitUntil.isTrue(() => {
+        const text = extractElementText(instance);
+        if (testCase.expect?.text) {
+            assert.hasValues(text, ensureArray(testCase.expect.text));
+            assert.hasValue(text, testCase.expect.text);
+        }
+        if (testCase.expect?.events) {
+            testCase.expect.events.forEach((expectedEvents, eventKey) => {
+                const actualEvents = events.get(eventKey);
+                assert.isDefined(actualEvents);
+                assert.deepEquals(actualEvents, expectedEvents);
+            });
+        }
+        return true;
+    }, {
+        interval: {
+            milliseconds: 100,
+        },
+        timeout: {
+            minutes: 1,
+        },
+    });
+}

package/dist/test-web/render-element.d.ts

@@ -1,3 +1,3 @@
 import { type DeclarativeElementDefinition } from 'element-vir';
 import { type EmptyObject } from 'type-fest';
-export declare function renderElement<const Definition extends DeclarativeElementDefinition>(elementDefinition: Definition, ...args: Definition['InputsType'] extends EmptyObject ? [] : [Definition['InputsType']]): Promise<Definition["InstanceType"]>;
+export declare function renderElement<const Definition extends Readonly<DeclarativeElementDefinition>>(elementDefinition: Definition, ...args: Definition['InputsType'] extends EmptyObject ? [] : [Definition['InputsType']]): Promise<Definition["InstanceType"]>;

package/dist/test-web/render-element.js

@@ -1,6 +1,6 @@
-import { fixture } from '@open-wc/testing-helpers';
 import { html } from 'element-vir';
 export async function renderElement(elementDefinition, ...args) {
+    const { fixture } = await import('@open-wc/testing-helpers');
     const instance = await fixture(html `
         <${elementDefinition.assign(args[0] || {})}></${elementDefinition}>
     `);

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

@@ -0,0 +1,8 @@
+/**
+ * Extracts the text content of the given element.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export declare function extractElementText(element: Readonly<Element>): string;

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

@@ -0,0 +1,28 @@
+/**
+ * Extracts the text content of the given element.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export function extractElementText(element) {
+    return recursivelyExtractElementText(element).join('\n');
+}
+function recursivelyExtractElementText(node) {
+    if (node.nodeType === Node.TEXT_NODE) {
+        const text = node.textContent?.trim();
+        return text ? [text] : [];
+    }
+    else if (node.nodeType === Node.ELEMENT_NODE) {
+        const element = node;
+        if (element.tagName.toLowerCase() === 'slot') {
+            const slotElement = element;
+            const assignedNodes = slotElement.assignedNodes();
+            return (assignedNodes.length ? assignedNodes : Array.from(element.childNodes)).flatMap((assignedNode) => recursivelyExtractElementText(assignedNode));
+        }
+        else {
+            return Array.from((element.shadowRoot || element).childNodes).flatMap((childNode) => recursivelyExtractElementText(childNode));
+        }
+    }
+    return [];
+}

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/test",
-    "version": "31.53.0",
+    "version": "31.54.1",
     "description": "A universal testing suite that works with Mocha style test runners _and_ Node.js's built-in test runner.",
     "keywords": [
         "test",
@@ -44,8 +44,8 @@
         "test:web": "virmator test --no-deps web 'src/test-web/**/*.test.ts' 'src/augments/universal-testing-suite/**/*.test.ts'"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.53.0",
-        "@augment-vir/common": "^31.53.0",
+        "@augment-vir/assert": "^31.54.1",
+        "@augment-vir/common": "^31.54.1",
         "@open-wc/testing-helpers": "^3.0.1",
         "@virmator/test": "^14.3.0",
         "type-fest": "^5.2.0"