@vobs/test-utils 0.3.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vobsjs
+Copyright (c) 2026 vobs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,55 @@
+# @vobs/test-utils
+
+In-memory test renderer and assertion helpers for mounting Vobs components without a DOM.
+
+## Install
+
+```bash
+npm install @vobs/test-utils
+```
+
+## Quick start
+
+```ts
+import { expect, it } from 'vitest'
+import { addEventListener, bindText, createElement, createText, insertBefore, state } from '@vobs/vobs'
+import { flushPromises, mount } from '@vobs/test-utils'
+
+it('increments on click', async () => {
+  const view = mount(() => {
+    const count = state(0)
+    const button = createElement('button')
+    const text = createText('')
+    insertBefore(button, text, null)
+    bindText(text, () => `count: ${count.value}`)
+    addEventListener(button, 'click', () => { count.value++ })
+    return button
+  })
+
+  view.fireEvent('click', { target: 'button' })
+  await flushPromises()
+
+  expect(view.queryByText('count: 1')).toBeTruthy()
+  view.destroy()
+})
+```
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `mount(render, options?)` | Mount a render function into an in-memory renderer; returns a `MountedTestApp`. `options.plugins` accepts `VobsPlugin[]`. |
+| `createTestRenderer()` | Standalone `TestRenderer` exposing `container`, `renderer` and query helpers. |
+| `view.queryByText(text)` | Find a text node with exact content. |
+| `view.queryByTag(tag)` | Find the first element with that tag. |
+| `view.queryByAttr(name, value)` | Find the first element with a matching attribute. |
+| `view.fireEvent(event, { target })` | Invoke the handler registered for `event` on the element with that tag. |
+| `view.update()` / `view.destroy()` | Flush an app update / unmount the app. |
+| `act(fn)` | Run updates as one deterministic reactive transaction (`batch`). |
+| `flushEffects()` | Flush queued effects without relying on implementation-specific timers. |
+| `flushPromises()` | Resolve pending promise continuations, then flush reactive effects. |
+| `measure(label, fn)` | Measure synchronous execution; returns `{ label, duration, result }`. |
+
+## Types
+
+TestNode, TestElement, TestText, TestComment, TestRenderer, MountedTestApp, PerformanceMeasurement

package/package.json

@@ -1,46 +1,21 @@
 {
-  "name": "@vobs/test-utils",
-  "version": "0.3.0",
-  "description": "Mount, hydrate and cleanup test harnesses for vobs applications and components.",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "license": "MIT",
-  "author": "vobsjs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vobsjs/vobs.git",
-    "directory": "packages/tools/test-utils"
-  },
-  "bugs": {
-    "url": "https://github.com/vobsjs/vobs/issues"
-  },
-  "homepage": "https://github.com/vobsjs/vobs#readme",
-  "dependencies": {
-    "@vobs/icons": "0.3.0",
-    "@vobs/reactivity": "0.3.0",
-    "@vobs/runtime-core": "0.3.0",
-    "@vobs/runtime-dom": "0.3.0",
-    "@vobs/i18n": "0.3.0",
-    "@vobs/server-renderer": "0.3.0",
-    "@vobs/ui": "0.3.0"
-  },
   "files": [
-    "dist"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "name": "@vobs/test-utils",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+    ".": "./src/index.ts"
   },
-  "types": "./dist/index.d.ts",
-  "module": "./dist/index.js",
-  "main": "./dist/index.js",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22.12.0"
+  "dependencies": {
+    "@vobs/dom": "1.1.0",
+    "@vobs/vobs": "1.1.0",
+    "@vobs/runtime": "1.1.0"
   }
 }

package/src/error-boundary.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { createElement, createText, createVobs, effect, ErrorBoundary, insertErrorBoundary, state } from '@vobs/vobs'
+
+describe('insertErrorBoundary', () => {
+  it('捕获子渲染分支的错误并可重试', () => {
+    const broken = state(true)
+    let retry!: () => void
+    const app = createVobs({
+      render: () => {
+        const root = createElement('div')
+        insertErrorBoundary(root, null, {
+          children: () => {
+            if (broken.value) throw new Error('broken')
+            return createText('ready')
+          },
+          fallback: (error, nextRetry) => {
+            retry = nextRetry
+            return createText(`error: ${error.message}`)
+          }
+        })
+        return root
+      }
+    })
+    const container = document.createElement('div')
+    app.mount(container)
+    app.update()
+    expect(container.textContent).toBe('error: broken')
+
+    broken.value = false
+    retry()
+    app.update()
+    expect(container.textContent).toBe('ready')
+    app.destroy()
+  })
+
+  it('捕获子分支中创建的 effect 的错误', () => {
+    const broken = state(false)
+    let cleanups = 0
+    const app = createVobs({
+      render: () => {
+        const root = createElement('div')
+        insertErrorBoundary(root, null, {
+          children: () => {
+            const text = createText('ready')
+            effect(() => {
+              if (broken.value) throw new Error('effect failure')
+              return () => { cleanups++ }
+            })
+            return text
+          },
+          fallback: error => createText(`error: ${error.message}`)
+        })
+        return root
+      }
+    })
+    const container = document.createElement('div')
+    app.mount(container)
+    broken.value = true
+    app.update()
+    expect(container.textContent).toBe('error: effect failure')
+    expect(cleanups).toBe(1)
+    app.destroy()
+  })
+
+  it('组件形态复用同一边界协议，并在路由 key 变化时恢复子树', () => {
+    const broken = state(true)
+    let retry!: () => void
+    const app = createVobs({
+      render: () => ErrorBoundary({
+        children: () => {
+          if (broken.value) throw new Error('broken')
+          return createText('ready')
+        },
+        fallback: (error, nextRetry) => {
+          retry = nextRetry
+          return createText(`error: ${error.message}`)
+        }
+      })
+    })
+    const container = document.createElement('div')
+    app.mount(container)
+    app.update()
+    expect(container.textContent).toBe('error: broken')
+
+    broken.value = false
+    retry()
+    app.update()
+    expect(container.textContent).toBe('ready')
+    app.destroy()
+  })
+})

package/src/fragment.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { createElement, createFragment, createText, createVobs, insertBefore, insertDynamic, state } from '@vobs/vobs'
+
+describe('Fragment', () => {
+  it('渲染多个同级节点且不产生元素包装', () => {
+    const app = createVobs({
+      render: () => createFragment((parent, anchor) => {
+        insertBefore(parent, createText('one'), anchor)
+        insertBefore(parent, createText('two'), anchor)
+      })
+    })
+    const container = document.createElement('div')
+    app.mount(container)
+
+    expect(container.textContent).toBe('onetwo')
+    expect(container.children).toHaveLength(0)
+    app.destroy()
+  })
+
+  it('能作为动态分支插入和移除整个节点范围', () => {
+    const visible = state(true)
+    const app = createVobs({
+      render: () => {
+        const root = createElement('div')
+        insertDynamic(root, null, () => visible.value ? createFragment((parent, anchor) => {
+          insertBefore(parent, createText('one'), anchor)
+          insertBefore(parent, createText('two'), anchor)
+        }) : null)
+        return root
+      }
+    })
+    const container = document.createElement('div')
+    app.mount(container)
+    expect(container.textContent).toBe('onetwo')
+
+    visible.value = false
+    app.update()
+    expect(container.textContent).toBe('')
+    app.destroy()
+  })
+})

package/src/index.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { state } from '@vobs/vobs'
+import { addEventListener, bindText, createElement, createText, insertBefore } from '@vobs/dom'
+import { mount } from './index'
+
+describe('test-utils', () => {
+  it('在内存渲染器中挂载、交互和更新', () => {
+    const count = state(0)
+    const app = mount(() => {
+      const button = createElement('button')
+      const text = createText('')
+      insertBefore(button, text, null)
+      bindText(text, () => `count: ${count.value}`)
+      addEventListener(button, 'click', () => { count.value++ })
+      return button
+    })
+
+    expect(app.queryByText('count: 0')).toBeTruthy()
+    app.fireEvent('click', { target: 'button' })
+    app.update()
+    expect(app.queryByText('count: 1')).toBeTruthy()
+
+    app.destroy()
+    expect(app.container.children).toHaveLength(0)
+  })
+})

package/src/index.ts

@@ -0,0 +1,212 @@
+import {
+  createVobs,
+  type VobsApp,
+  type VobsConfig,
+  type VobsPlugin
+} from '@vobs/vobs'
+import { batch, scheduler } from '@vobs/reactivity'
+import type { VobsRenderer } from '@vobs/runtime'
+
+export type TestNode = TestElement | TestText | TestComment
+
+export interface TestElement {
+  type: 'element'
+  tag: string
+  attrs: Record<string, string>
+  props: Record<string, unknown>
+  events: Record<string, EventListener>
+  children: TestNode[]
+  parent: TestElement | null
+}
+
+export interface TestText {
+  type: 'text'
+  content: string
+  parent: TestElement | null
+}
+
+export interface TestComment {
+  type: 'comment'
+  content: string
+  parent: TestElement | null
+}
+
+export interface TestRenderer {
+  readonly container: TestElement
+  readonly renderer: VobsRenderer<TestNode, TestText, TestElement, TestComment>
+  queryByText(text: string): TestNode | null
+  queryByTag(tag: string): TestElement | null
+  queryByAttr(name: string, value: string): TestElement | null
+}
+
+export interface MountedTestApp {
+  readonly app: VobsApp<TestNode>
+  readonly container: TestElement
+  update(): void
+  destroy(): void
+  queryByText(text: string): TestNode | null
+  queryByTag(tag: string): TestElement | null
+  queryByAttr(name: string, value: string): TestElement | null
+  fireEvent(event: string, options: { target: string }): void
+}
+
+/** Execute test updates as one deterministic reactive transaction. */
+export function act<T>(fn: () => T): T {
+  return batch(fn)
+}
+
+/** Flush queued effects without relying on implementation-specific timers. */
+export function flushEffects(): void {
+  scheduler.flush()
+}
+
+/** Resolve pending Promise continuations and then flush reactive effects. */
+export async function flushPromises(): Promise<void> {
+  await Promise.resolve()
+  scheduler.flush()
+}
+
+export interface PerformanceMeasurement<T = unknown> {
+  readonly label: string
+  readonly duration: number
+  readonly result: T
+}
+
+/** Small deterministic measurement helper for component/runtime baselines. */
+export function measure<T>(label: string, fn: () => T): PerformanceMeasurement<T> {
+  const started = typeof performance !== 'undefined' ? performance.now() : Date.now()
+  const result = fn()
+  const ended = typeof performance !== 'undefined' ? performance.now() : Date.now()
+  return { label, duration: Math.max(0, ended - started), result }
+}
+
+export function createTestRenderer(): TestRenderer {
+  const container = createElementNode('root')
+  const renderer: VobsRenderer<TestNode, TestText, TestElement, TestComment> = {
+    createText(content: string): TestText {
+      return { type: 'text', content, parent: null }
+    },
+
+    createElement(tag: string): TestElement {
+      return createElementNode(tag)
+    },
+
+    createComment(content: string): TestComment {
+      return { type: 'comment', content, parent: null }
+    },
+
+    insertBefore(parent: TestElement, child: TestNode, anchor: TestNode | null): void {
+      if (child.parent) removeChildNode(child.parent, child)
+      const index = anchor ? parent.children.indexOf(anchor) : -1
+      if (index >= 0) parent.children.splice(index, 0, child)
+      else parent.children.push(child)
+      child.parent = parent
+    },
+
+    removeChild(parent: TestElement, child: TestNode): void {
+      removeChildNode(parent, child)
+    },
+
+    setTextContent(node: TestText, content: string): void {
+      node.content = content
+    },
+
+    setProperty(node: TestElement, key: string, value: unknown): void {
+      node.props[key] = value
+    },
+
+    setAttribute(node: TestElement, key: string, value: string): void {
+      node.attrs[key] = value
+    },
+
+    addEventListener(node: TestElement, event: string, handler: EventListener): void {
+      node.events[event] = handler
+    },
+
+    removeEventListener(node: TestElement, event: string, handler: EventListener): void {
+      if (node.events[event] === handler) delete node.events[event]
+    },
+
+    nextSibling(node: TestNode): TestNode | null {
+      const parent = node.parent
+      if (!parent) return null
+      const index = parent.children.indexOf(node)
+      return index >= 0 ? parent.children[index + 1] ?? null : null
+    },
+
+    clear(node: TestElement): void {
+      for (const child of node.children) child.parent = null
+      node.children.length = 0
+    }
+  }
+
+  return {
+    container,
+    renderer,
+    queryByText: text => findNode(container, node => node.type === 'text' && node.content === text),
+    queryByTag: tag => findNode(container, node => node.type === 'element' && node.tag === tag) as TestElement | null,
+    queryByAttr: (name, value) => findNode(
+      container,
+      node => node.type === 'element' && node.attrs[name] === value
+    ) as TestElement | null
+  }
+}
+
+export function mount(
+  render: VobsConfig['render'],
+  options: { plugins?: VobsPlugin[] } = {}
+): MountedTestApp {
+  const testRenderer = createTestRenderer()
+  const app = createVobs({
+    render,
+    renderer: testRenderer.renderer,
+    plugins: options.plugins
+  })
+  app.mount(testRenderer.container)
+
+  return {
+    app,
+    container: testRenderer.container,
+    update: () => app.update(),
+    destroy: () => app.destroy(),
+    queryByText: testRenderer.queryByText,
+    queryByTag: testRenderer.queryByTag,
+    queryByAttr: testRenderer.queryByAttr,
+    fireEvent(event, { target }): void {
+      const node = testRenderer.queryByTag(target)
+      const handler = node?.events[event]
+      if (!handler) throw new Error(`Vobs test-utils: 未找到 ${target} 的 ${event} 事件处理器`)
+      handler.call(node, { type: event, target: node } as unknown as Event)
+    }
+  }
+}
+
+function createElementNode(tag: string): TestElement {
+  return {
+    type: 'element',
+    tag,
+    attrs: {},
+    props: {},
+    events: {},
+    children: [],
+    parent: null
+  }
+}
+
+function removeChildNode(parent: TestElement, child: TestNode): void {
+  const index = parent.children.indexOf(child)
+  if (index < 0) throw new Error('Vobs test-utils: 节点不属于指定父节点')
+  parent.children.splice(index, 1)
+  child.parent = null
+}
+
+function findNode(root: TestElement, predicate: (node: TestNode) => boolean): TestNode | null {
+  for (const child of root.children) {
+    if (predicate(child)) return child
+    if (child.type === 'element') {
+      const result = findNode(child, predicate)
+      if (result) return result
+    }
+  }
+  return null
+}

package/dist/index.d.ts

@@ -1,57 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/test-utils
- */
-import { type I18nInstance, type I18nOptions } from '@vobs/i18n';
-import { type IconDefinition, type IconRegistry } from '@vobs/icons';
-import type { PageEnvironment, PageInstance, TemplateEnvironment } from '@vobs/runtime-core';
-import { type PageDefinition } from '@vobs/runtime-dom';
-import { type RenderPageOptions, type RenderPageResult } from '@vobs/server-renderer';
-import { type ThemeController, type ThemeControllerOptions, type ThemeTarget } from '@vobs/ui';
-import { type UiEnvironment } from '@vobs/ui/icons';
-export interface TestEnvironmentOptions<InitialState = unknown> extends Partial<PageEnvironment<InitialState>> {
-    readonly baseUrl?: string;
-    readonly errors?: unknown[];
-}
-export interface TestContainer extends Element {
-    readonly items: Element[];
-}
-export interface TestPageHarness<InitialState = unknown> {
-    readonly container: TestContainer;
-    readonly environment: PageEnvironment<InitialState>;
-    readonly instance: PageInstance;
-    cleanup(): void;
-}
-export interface UiTestContextOptions {
-    readonly i18n?: I18nOptions;
-    readonly icons?: Readonly<Record<string, IconDefinition>>;
-    readonly theme?: Omit<ThemeControllerOptions, 'target'>;
-}
-export interface UiTestContext {
-    readonly i18n: I18nInstance;
-    readonly icons: IconRegistry;
-    readonly ui: UiEnvironment;
-    readonly themeTarget: TestThemeTarget;
-    readonly theme: ThemeController;
-    cleanup(): void;
-}
-export interface TestThemeTarget extends ThemeTarget {
-    readonly attributes: Readonly<Record<string, string>>;
-    readonly variables: ReadonlyMap<string, string>;
-}
-export declare function createTestEnvironment<InitialState = unknown>(options?: TestEnvironmentOptions<InitialState>): PageEnvironment<InitialState>;
-export declare function createTestContainer(initialRoot?: Element): TestContainer;
-export declare function mountTestPage(page: PageDefinition, options?: {
-    readonly container?: TestContainer;
-    readonly environment?: TestEnvironmentOptions;
-}): Promise<TestPageHarness>;
-export declare function hydrateTestPage(page: PageDefinition, options: {
-    readonly container: TestContainer;
-    readonly environment?: TestEnvironmentOptions;
-}): Promise<TestPageHarness>;
-export declare function renderTestPage<Scope extends object, InitialState = unknown>(options: Omit<RenderPageOptions<Scope, InitialState>, 'environment'> & {
-    readonly environment?: TemplateEnvironment;
-}): RenderPageResult;
-export declare function createUiTestContext(options?: UiTestContextOptions): UiTestContext;
-export declare function createThemeTestTarget(): TestThemeTarget;
-export declare function cleanup(): void;

package/dist/index.js

@@ -1,146 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/test-utils
- */
-import { createI18n } from '@vobs/i18n';
-import { createIconRegistry } from '@vobs/icons';
-import { Scheduler } from '@vobs/reactivity';
-import { createDefaultUrlPolicy } from '@vobs/runtime-dom';
-import { renderPage } from '@vobs/server-renderer';
-import { createThemeController, } from '@vobs/ui';
-import { createUiEnvironment } from '@vobs/ui/icons';
-const cleanups = new Set();
-export function createTestEnvironment(options = {}) {
-    const errors = options.errors;
-    const environment = {
-        scheduler: options.scheduler ?? new Scheduler(),
-        security: options.security ?? {
-            urlPolicy: createDefaultUrlPolicy(options.baseUrl ?? 'https://example.test/'),
-        },
-        onError: options.onError ??
-            ((error) => {
-                errors?.push(error);
-                if (errors === undefined)
-                    throw error;
-            }),
-        ...(options.components === undefined ? {} : { components: options.components }),
-        ...(options.slots === undefined ? {} : { slots: options.slots }),
-        ...(options.route === undefined ? {} : { route: options.route }),
-        ...(options.initialState === undefined ? {} : { initialState: options.initialState }),
-    };
-    return environment;
-}
-export function createTestContainer(initialRoot) {
-    const items = initialRoot === undefined ? [] : [initialRoot];
-    const appendNodes = (nodes) => {
-        for (const node of nodes) {
-            if (typeof node !== 'string')
-                items.push(node);
-        }
-    };
-    return {
-        items,
-        get firstElementChild() {
-            return items[0] ?? null;
-        },
-        append(...nodes) {
-            appendNodes(nodes);
-        },
-        replaceChildren(...nodes) {
-            items.length = 0;
-            appendNodes(nodes);
-        },
-        querySelectorAll() {
-            return [];
-        },
-    };
-}
-export async function mountTestPage(page, options = {}) {
-    const container = options.container ?? createTestContainer();
-    const environment = createTestEnvironment(options.environment);
-    const instance = await page.mount(environment);
-    container.append(instance.root);
-    return createPageHarness(container, environment, instance);
-}
-export async function hydrateTestPage(page, options) {
-    const environment = createTestEnvironment(options.environment);
-    const instance = await page.hydrate(options.container, environment);
-    return createPageHarness(options.container, environment, instance);
-}
-export function renderTestPage(options) {
-    return renderPage({
-        ...options,
-        environment: options.environment ?? createTestEnvironment(),
-    });
-}
-export function createUiTestContext(options = {}) {
-    const i18n = createI18n(options.i18n ?? { locale: 'en-US', messages: {} });
-    const icons = createIconRegistry(options.icons ?? {});
-    const ui = createUiEnvironment({ icons });
-    const themeTarget = createThemeTestTarget();
-    const theme = createThemeController({
-        target: themeTarget,
-        ...(options.theme ?? {}),
-    });
-    const cleanup = trackCleanup(() => {
-        theme.destroy();
-    });
-    return {
-        i18n,
-        icons,
-        ui,
-        themeTarget,
-        theme,
-        cleanup,
-    };
-}
-export function createThemeTestTarget() {
-    const attributes = {};
-    const variables = new Map();
-    return {
-        attributes,
-        variables,
-        setAttribute(name, value) {
-            attributes[name] = value;
-        },
-        style: {
-            setProperty(name, value) {
-                variables.set(name, value);
-            },
-            removeProperty(name) {
-                const current = variables.get(name) ?? '';
-                variables.delete(name);
-                return current;
-            },
-        },
-    };
-}
-export function cleanup() {
-    const pending = Array.from(cleanups).reverse();
-    cleanups.clear();
-    for (const dispose of pending)
-        dispose();
-}
-function createPageHarness(container, environment, instance) {
-    const cleanupHarness = trackCleanup(() => {
-        instance.destroy();
-    });
-    return {
-        container,
-        environment,
-        instance,
-        cleanup: cleanupHarness,
-    };
-}
-function trackCleanup(dispose) {
-    let active = true;
-    const cleanupOnce = () => {
-        if (!active)
-            return;
-        active = false;
-        cleanups.delete(cleanupOnce);
-        dispose();
-    };
-    cleanups.add(cleanupOnce);
-    return cleanupOnce;
-}