@vonage/vivid-test-utils 5.2.0

package/README.md

@@ -0,0 +1,102 @@
+# Vivid Test Utils
+
+A library to make it easier to interact with Vivid components in tests, that works with any frontend library and common testing frameworks.
+
+## Motivation
+
+Since Vivid is a Web Components library, writing tests can be more challenging. Depending on the testing framework used and how tests are set up, there can be various pitfalls and issues that slow down test development.
+
+The library provides a unified way to select components, perform actions on them, and assert their state, that can be trusted to work.
+
+Since the version of test utils are kept in sync with the Vivid version, these operations will also continue to work in the future, even when things change underneath.
+
+## Testing Frameworks
+
+The library supports the following testing frameworks:
+
+- Playwright
+- Cypress
+- DOM: Can be used with a simulated DOM like JSDOM, e.g. in combination with Vue Test Utils or React Testing Library
+
+The usage across all testing frameworks is the same. The only difference is in initialization and whether certain operations are asynchronous or not.
+
+## Usage
+
+### Installation
+
+The library is provided as the `@vonage/vivid-test-utils` package. The version number is kept in sync with the Vivid library itself that it supports.
+
+### Initialization
+
+#### Playwright
+
+```js
+import { vividPlaywright } from '@vonage/vivid-test-utils/playwright';
+
+// Create the vvd object using the Playwright page object and Playwright's expect function:
+const vvd = vividPlaywright(page, expect);
+```
+
+#### Cypress
+
+```js
+import { vividCypress } from '@vonage/vivid-test-utils/cypress';
+
+// Create the vvd object using the cy object:
+const vvd = vividCypress(cy);
+```
+
+#### DOM with Vue Test Utils
+
+If you run your tests in a simulated DOM environment, it may not provide all features needed by Vivid.
+
+The library comes with a polyfill for JSDOM that fills these gaps. You can load it as follows, e.g. in a global test setup file:
+
+```js
+import '@vonage/vivid-test-utils/jsdom-polyfill';
+```
+
+```js
+import { vividDOM } from '@vonage/vivid-test-utils/dom';
+
+const wrapper = mount(Component, { attachTo: document.body });
+// Create the vvd object using a Jest/Vitest or other Jasmine-style expect function and a root DOM node:
+const vvd = vividDOM(expect, document.body);
+```
+
+### Selecting Components
+
+```js
+// Select with a component specific selector:
+vvd.textField.byLabel('Email');
+// Or by test ID, which will work for all components:
+vvd.textField.byTestId('#email');
+```
+
+### Performing Actions
+
+```js
+// After selecting a component, you can perform component specific actions:
+vvd.textField.byLabel('Email').fill('user@example.com');
+```
+
+When using Playwright or DOM, actions will need to be awaited.
+
+### Asserting Component State
+
+```js
+// Use vvd.expect to make component specific assertions:
+vvd.expect(vvd.textField.byLabel('Email')).toHaveValue('user@example.com');
+// You can also assert the value of a specific prop:
+vvd.expect(vvd.textField.byLabel('Email')).toHaveProp('appearance', 'ghost');
+```
+
+When using Playwright, expectations will need to be awaited.
+
+### Selecting Multiple Components
+
+```js
+// The all selector returns a collection of components:
+vvd.textField.all().nth(0).fill('user@example.com');
+vvd.expect(vvd.textField.all()).toHaveCount(2);
+```

package/dist/actions.d.ts

@@ -0,0 +1,31 @@
+import type { DriverT } from './drivers/driver';
+import { BaseWrapper } from './base';
+import { type AccordionItemWrapper, type ButtonWrapper, type ComboboxWrapper, type DatePickerWrapper, type DateRangePickerWrapper, type DateTimePickerWrapper, type NavDisclosureWrapper, type PaginationWrapper, TagWrapper, type TimePickerWrapper } from './components.generated';
+export declare function click<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function fill<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator'], text: string): D['actionReturn'];
+export declare function comboboxFill<D extends DriverT>(this: ComboboxWrapper<D>, text: string): D['actionReturn'];
+export declare function clear<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function comboboxClear<D extends DriverT>(this: ComboboxWrapper<D>): D['actionReturn'];
+export declare function check<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function uncheck<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function focus<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function blur<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function hover<D extends DriverT>(this: BaseWrapper<D>, locator: () => D['locator']): D['actionReturn'];
+export declare function selectOptionByValue<D extends DriverT>(this: BaseWrapper<D>, value: string): D['actionReturn'];
+export declare function selectOptionByText<D extends DriverT>(this: BaseWrapper<D>, text: string): D['actionReturn'];
+export declare function clickButton<D extends DriverT>(this: BaseWrapper<D>, locator: () => ButtonWrapper<D>): D['actionReturn'];
+export declare function selectDate<D extends DriverT>(this: DatePickerWrapper<D>, date: string): D['actionReturn'];
+interface PickerWrapper<D extends DriverT> extends BaseWrapper<D> {
+    pickerButton(): ButtonWrapper<D>;
+    clearButton(): ButtonWrapper<D>;
+}
+export declare function clearPicker<D extends DriverT>(this: PickerWrapper<D>): D['actionReturn'];
+export declare function selectTime<D extends DriverT>(this: TimePickerWrapper<D>, time: string): D['actionReturn'];
+export declare function selectDateRange<D extends DriverT>(this: DateRangePickerWrapper<D>, range: [string, string]): D['actionReturn'];
+export declare function selectDateTime<D extends DriverT>(this: DateTimePickerWrapper<D>, dateTime: string): D['actionReturn'];
+export declare function slideTo<D extends DriverT>(this: BaseWrapper<D>, track: () => D['locator'], thumb: () => D['locator'], value: number): D['actionReturn'];
+export declare function clickPaginationPage<D extends DriverT>(this: PaginationWrapper<D>, pageIndex: number): D['actionReturn'];
+export declare function toggleAccordionItem<D extends DriverT>(this: AccordionItemWrapper<D>, expand: boolean): D['actionReturn'];
+export declare function toggleNavDisclosure<D extends DriverT>(this: NavDisclosureWrapper<D>, expand: boolean): D['actionReturn'];
+export declare function toggleTag<D extends DriverT>(this: TagWrapper<D>, select: boolean): D['actionReturn'];
+export {};

package/dist/base.d.ts

@@ -0,0 +1,38 @@
+import type { Driver, DriverT } from './drivers/driver';
+export type Context<D extends DriverT> = {
+    rootLocator: D['rootLocator'];
+    driver: Driver<D>;
+};
+export type ComponentInfo = {
+    name: string;
+};
+export declare abstract class BaseWrapper<D extends DriverT, E extends HTMLElement = HTMLElement> {
+    protected readonly ctx: Context<D>;
+    protected readonly locator: D['locator'];
+    constructor(ctx: Context<D>, locator: D['locator']);
+    abstract componentInfo: ComponentInfo;
+    unwrap(): D["locator"];
+    protected assert<A = unknown, Q = unknown>(message: string, query: (el: E, arg: A) => Q, expectedValue: Q, arg?: A): D["expectReturn"];
+}
+export declare abstract class BaseComponent<D extends DriverT, W extends BaseWrapper<D>> {
+    protected readonly ctx: Context<D>;
+    constructor(ctx: Context<D>);
+    abstract componentInfo: ComponentInfo;
+    abstract wrap(locator: D['locator']): W;
+    all: any;
+}
+export type ComponentCollectionLocator<D extends DriverT, W extends BaseWrapper<D>> = ComponentCollection<D, W>;
+export declare class ComponentCollection<D extends DriverT, W extends BaseWrapper<D>> {
+    private ctx;
+    private readonly component;
+    private readonly locator;
+    constructor(ctx: Context<D>, component: BaseComponent<D, W>, locator: D['locatorMultiple']);
+    type: "collection";
+    nth: (n: number) => W;
+}
+export declare class ComponentCollectionExpectations<D extends DriverT> {
+    private readonly ctx;
+    private readonly locator;
+    constructor(ctx: Context<D>, locator: ComponentCollectionLocator<D, any>);
+    toHaveCount: (n: number) => D["expectReturn"];
+}