@govela/testing 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abullo
+
+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.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @govela/testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Test helpers for Vela components, for Vitest with happy-dom or jsdom.
+The components are compiled by `@govela/unplugin`, as in the
+application.
+
+```sh
+npm i -D @govela/testing @govela/unplugin vitest happy-dom
+```
+
+```js
+// vite.config.js
+import vela from '@govela/unplugin/vite';
+
+export default { plugins: [vela()], test: { environment: 'happy-dom' } };
+```
+
+```js
+import { afterEach, expect, test } from 'vitest';
+import { cleanup, fireEvent, render } from '@govela/testing';
+import Counter from './Counter.vela';
+
+afterEach(cleanup);
+
+test('counts', async () => {
+  const { container } = render(Counter, { props: { step: 2 } });
+  await fireEvent.click(container.querySelector('button'));
+  expect(container.textContent).toContain('2');
+});
+```
+
+- `render(Component, { props, slots, events, target })` mounts the
+  component into a new `<div>` of `document.body` and returns
+  `{ container, component, rerender(props), unmount() }`. A slot is an
+  HTML string, a node or a function returning one; `events` listens to
+  the component's `$$dispatch` events.
+- `fireEvent(element, event)`, `fireEvent.click(element)`,
+  `fireEvent.input(element, value)` and the others dispatch the event
+  and wait until the component has updated.
+- `cleanup()` unmounts every rendered component; `tick()` waits for
+  pending updates.
+- In TypeScript, `render` checks the props (and requires the required
+  ones), the `detail` of each listener and the slot names against the
+  component's type.
+
+License: MIT.

package/index.d.ts

@@ -0,0 +1,72 @@
+// Types of @govela/testing. render() checks the props, events and slots of
+// a test against the component's types (Component<P, E, S, B>).
+import type { Component, ComponentInstance, Props } from '@govela/runtime';
+
+export { tick } from '@govela/runtime';
+
+/** Content of a slot: an HTML string, a node, or a function returning one. */
+export type SlotContent = string | Node | (() => string | Node);
+
+/** Listeners of a component's events, by name, with their `detail` types. */
+export type EventListeners<E extends Record<string, any>> = {
+  [K in keyof E & string]?: (event: CustomEvent<E[K]>) => void;
+};
+
+/** The slots of a component by name; `default` is the default slot. */
+export type SlotContents<S extends Record<string, any>> = string extends keyof S
+  ? Record<string, SlotContent>
+  : { [K in keyof S]?: SlotContent };
+
+/** The options of render(): props are required when the component has required props. */
+export type RenderOptions<
+  P extends Props = Props,
+  E extends Record<string, any> = Record<string, any>,
+  S extends Record<string, any> = Record<string, any>,
+> = {
+  /** Slot contents by name. */
+  slots?: SlotContents<S>;
+  /** Listeners of the component's events (`$$dispatch`), by name. */
+  events?: EventListeners<E>;
+  /** The element to mount into; by default a new div in document.body. */
+  target?: Element;
+} & ({} extends P ? { props?: P } : { props: P });
+
+export interface RenderResult<P extends Props = Props> {
+  /** The element the component is mounted into. */
+  readonly container: Element;
+  /** The mounted component. */
+  readonly component: ComponentInstance<P>;
+  /** Sets props and waits for the update. */
+  rerender(props: Partial<P>): Promise<void>;
+  /** Destroys the component and removes the container render() created. */
+  unmount(): void;
+}
+
+/** Mounts a component for a test. */
+export function render<P extends Props, E extends Record<string, any>, S extends Record<string, any>>(
+  component: Component<P, E, S, any>,
+  ...options: {} extends P ? [options?: RenderOptions<NoInfer<P>, NoInfer<E>, NoInfer<S>>] : [options: RenderOptions<NoInfer<P>, NoInfer<E>, NoInfer<S>>]
+): RenderResult<P>;
+
+/** Unmounts every component render() mounted; call it after each test. */
+export function cleanup(): void;
+
+export interface FireEvent {
+  /** Dispatches event on element and waits for the component to update. */
+  (element: Element | null, event: Event): Promise<boolean>;
+  click(element: Element | null, init?: MouseEventInit): Promise<boolean>;
+  dblClick(element: Element | null, init?: MouseEventInit): Promise<boolean>;
+  mouseDown(element: Element | null, init?: MouseEventInit): Promise<boolean>;
+  mouseUp(element: Element | null, init?: MouseEventInit): Promise<boolean>;
+  keyDown(element: Element | null, init?: KeyboardEventInit): Promise<boolean>;
+  keyUp(element: Element | null, init?: KeyboardEventInit): Promise<boolean>;
+  focus(element: Element | null, init?: FocusEventInit): Promise<boolean>;
+  blur(element: Element | null, init?: FocusEventInit): Promise<boolean>;
+  /** Sets the value of an input, select or textarea and dispatches input. */
+  input(element: Element | null, value?: string, init?: EventInit): Promise<boolean>;
+  /** Sets the value (or checked, for a boolean) and dispatches change. */
+  change(element: Element | null, value?: string | boolean, init?: EventInit): Promise<boolean>;
+  submit(element: Element | null, init?: EventInit): Promise<boolean>;
+}
+
+export const fireEvent: FireEvent;

package/index.js

@@ -0,0 +1,117 @@
+// @govela/testing: render Vela components in a test DOM (Vitest with
+// happy-dom or jsdom) and act on them (task 066, docs/GUIDE.md "Testing").
+// Compile the components with @govela/unplugin, as in the application.
+import { mount, tick } from '@govela/runtime';
+
+export { tick };
+
+const rendered = new Set();
+
+// A slot passed to render(): an HTML string, a node, or a function returning
+// either. A slot of the runtime is a function returning a DocumentFragment
+// with the content; reopened, it returns the same nodes.
+function slotOf(content) {
+  let nodes = null;
+  return () => {
+    if (!nodes) {
+      const value = typeof content === 'function' ? content() : content;
+      const template = document.createElement('template');
+      if (typeof value === 'string') template.innerHTML = value;
+      else if (value != null) template.content.append(value);
+      nodes = [...template.content.childNodes];
+    }
+    const fragment = document.createDocumentFragment();
+    fragment.append(...nodes);
+    return fragment;
+  };
+}
+
+/**
+ * Mounts a component into a new container appended to document.body (or
+ * into options.target) and returns the container and the instance.
+ */
+export function render(Component, options = {}) {
+  const { props = {}, slots = {}, events = {}, target } = options;
+  const container = target ?? document.body.appendChild(document.createElement('div'));
+  const runtimeSlots = {};
+  for (const [name, content] of Object.entries(slots)) runtimeSlots[name] = slotOf(content);
+  // Component events are CustomEvents that bubble from the component's DOM.
+  const listeners = [];
+  for (const [name, handler] of Object.entries(events)) {
+    container.addEventListener(name, handler);
+    listeners.push([name, handler]);
+  }
+  const component = mount(Component, { target: container, props, slots: runtimeSlots });
+  let mounted = true;
+  const result = {
+    container,
+    component,
+    /** Sets props and waits for the update. */
+    async rerender(next) {
+      if (!component.set) throw new Error('[Vela] rerender(): the component has no props');
+      component.set(next);
+      await settle();
+    },
+    /** Destroys the component and removes the container it created. */
+    unmount() {
+      if (!mounted) return;
+      mounted = false;
+      rendered.delete(result);
+      component.destroy();
+      for (const [name, handler] of listeners) container.removeEventListener(name, handler);
+      if (!target) container.remove();
+    },
+  };
+  rendered.add(result);
+  return result;
+}
+
+/** Unmounts every component render() mounted; call it after each test. */
+export function cleanup() {
+  for (const result of [...rendered]) result.unmount();
+}
+
+// settle waits until the updates scheduled by an event or a state change
+// are applied: the runtime flushes them in microtasks.
+async function settle() {
+  await tick();
+  await tick();
+}
+
+/**
+ * Dispatches event on element and waits for the component to update.
+ * fireEvent.click(button), fireEvent.input(input, 'text') and the other
+ * helpers create the event.
+ */
+export async function fireEvent(element, event) {
+  if (!element) throw new Error('[Vela] fireEvent(): no element');
+  const result = element.dispatchEvent(event);
+  await settle();
+  return result;
+}
+
+const view = () => document.defaultView ?? globalThis;
+const mouse = (type) => (element, init = {}) => fireEvent(element, new (view().MouseEvent)(type, { bubbles: true, cancelable: true, ...init }));
+const keyboard = (type) => (element, init = {}) => fireEvent(element, new (view().KeyboardEvent)(type, { bubbles: true, cancelable: true, ...init }));
+const focus = (type, bubbles) => (element, init = {}) => fireEvent(element, new (view().FocusEvent)(type, { bubbles, ...init }));
+
+fireEvent.click = mouse('click');
+fireEvent.dblClick = mouse('dblclick');
+fireEvent.mouseDown = mouse('mousedown');
+fireEvent.mouseUp = mouse('mouseup');
+fireEvent.keyDown = keyboard('keydown');
+fireEvent.keyUp = keyboard('keyup');
+fireEvent.focus = focus('focus', false);
+fireEvent.blur = focus('blur', false);
+/** Sets the value of an input, select or textarea and dispatches input. */
+fireEvent.input = (element, value, init = {}) => {
+  if (value !== undefined) element.value = value;
+  return fireEvent(element, new (view().Event)('input', { bubbles: true, ...init }));
+};
+/** Sets the value (or checked, for a boolean) and dispatches change. */
+fireEvent.change = (element, value, init = {}) => {
+  if (typeof value === 'boolean') element.checked = value;
+  else if (value !== undefined) element.value = value;
+  return fireEvent(element, new (view().Event)('change', { bubbles: true, ...init }));
+};
+fireEvent.submit = (element, init = {}) => fireEvent(element, new (view().Event)('submit', { bubbles: true, cancelable: true, ...init }));

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@govela/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Test helpers for Vela components: render, fireEvent, cleanup, tick. Manifest generated by the compiler repository; do not edit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elauven/vela.git",
+    "directory": "packages/testing"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@govela/runtime": "0.7.0"
+  }
+}