@fictjs/testing-library 0.2.3 → 0.3.0

package/dist/index.d.cts

@@ -1,2 +1,492 @@
+import { Queries, queries, BoundFunctions, prettyFormat } from '@testing-library/dom';
+export * from '@testing-library/dom';
+export { prettyDOM, queries } from '@testing-library/dom';
+import { FictNode, Component } from '@fictjs/runtime';
 
-export {  }
+/**
+ * @fileoverview Type definitions for @fictjs/testing-library
+ *
+ * This module provides TypeScript type definitions for the Fict testing library.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Internal reference to a mounted container for cleanup tracking.
+ */
+interface MountedRef {
+    container?: HTMLElement;
+    baseElement?: HTMLElement;
+    ownedContainer?: boolean;
+    teardown: () => void;
+}
+/**
+ * A Fict view function that returns a FictNode.
+ */
+type View = () => FictNode;
+/**
+ * Options for the render function.
+ */
+interface RenderOptions<Q extends Queries = typeof queries> {
+    /**
+     * The container element to render into. If not provided, a div will be created.
+     */
+    container?: HTMLElement;
+    /**
+     * The base element for queries. Defaults to the container when provided,
+     * otherwise defaults to document.body.
+     */
+    baseElement?: HTMLElement;
+    /**
+     * Custom queries to use instead of the default queries.
+     */
+    queries?: Q;
+    /**
+     * A wrapper component to wrap the rendered view with.
+     * Useful for providing context or other providers.
+     */
+    wrapper?: Component<{
+        children: FictNode;
+    }>;
+}
+/**
+ * Debug function type for pretty-printing DOM.
+ */
+type DebugFn = (baseElement?: HTMLElement | HTMLElement[], maxLength?: number, options?: prettyFormat.OptionsReceived) => void;
+/**
+ * Result returned from render().
+ */
+type RenderResult<Q extends Queries = typeof queries> = BoundFunctions<Q> & {
+    /**
+     * Returns the innerHTML of the container as a string.
+     */
+    asFragment: () => string;
+    /**
+     * The container element the view was rendered into.
+     */
+    container: HTMLElement;
+    /**
+     * The base element for queries.
+     */
+    baseElement: HTMLElement;
+    /**
+     * Pretty-print the DOM for debugging.
+     */
+    debug: DebugFn;
+    /**
+     * Unmount the rendered view and clean up.
+     */
+    unmount: () => void;
+    /**
+     * Re-render with a new view.
+     */
+    rerender: (newView: View) => void;
+};
+/**
+ * Options for renderHook function.
+ */
+interface RenderHookOptions<Props extends unknown[]> {
+    /**
+     * Initial props to pass to the hook.
+     */
+    initialProps?: Props;
+    /**
+     * A wrapper component to wrap the hook with.
+     */
+    wrapper?: Component<{
+        children: FictNode;
+    }>;
+}
+/**
+ * Result returned from renderHook().
+ */
+interface RenderHookResult<Result, Props extends unknown[]> {
+    /**
+     * Container holding the result of calling the hook.
+     * Access via `result.current`. Updated when the hook re-runs.
+     */
+    result: {
+        current: Result;
+    };
+    /**
+     * Re-render the hook with new props.
+     * Note: this disposes the previous root and mounts a new one; hook state resets.
+     */
+    rerender: (newProps?: Props) => void;
+    /**
+     * Clean up the hook and dispose of the root.
+     */
+    cleanup: () => void;
+    /**
+     * Alias for cleanup.
+     */
+    unmount: () => void;
+}
+/**
+ * Callback function signature for testEffect.
+ * @param done - Call this function with the result when the effect completes.
+ */
+type TestEffectCallback<T> = (done: (result: T) => void) => void;
+/**
+ * Result returned from renderWithErrorBoundary().
+ */
+type ErrorBoundaryRenderResult<Q extends Queries = typeof queries> = RenderResult<Q> & {
+    /**
+     * Trigger an error in the error boundary by rendering a component that throws.
+     */
+    triggerError: (error: Error) => void;
+    /**
+     * Reset the error boundary to re-render children.
+     */
+    resetErrorBoundary: () => void;
+    /**
+     * Check if the error boundary is currently showing the fallback.
+     */
+    isShowingFallback: () => boolean;
+};
+/**
+ * Options for renderWithErrorBoundary().
+ */
+type ErrorBoundaryRenderOptions<Q extends Queries = typeof queries> = RenderOptions<Q> & {
+    /**
+     * The fallback UI to show when an error is caught.
+     * Can be a FictNode or a function that receives the error and reset function.
+     */
+    fallback?: FictNode | ((err: unknown, reset?: () => void) => FictNode);
+    /**
+     * Callback called when an error is caught.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * Keys that trigger a reset when changed.
+     */
+    resetKeys?: unknown | (() => unknown);
+};
+/**
+ * Result returned from renderWithSuspense().
+ */
+type SuspenseRenderResult<Q extends Queries = typeof queries> = RenderResult<Q> & {
+    /**
+     * Check if the suspense boundary is currently showing the fallback.
+     */
+    isShowingFallback: () => boolean;
+    /**
+     * Wait for the suspense to resolve.
+     */
+    waitForResolution: (options?: {
+        timeout?: number;
+    }) => Promise<void>;
+};
+/**
+ * Options for renderWithSuspense().
+ */
+type SuspenseRenderOptions<Q extends Queries = typeof queries> = RenderOptions<Q> & {
+    /**
+     * The fallback UI to show while suspended.
+     */
+    fallback?: FictNode | ((err?: unknown) => FictNode);
+    /**
+     * Callback called when the suspense resolves.
+     */
+    onResolve?: () => void;
+    /**
+     * Callback called when the suspense rejects.
+     *
+     * Note: providing onReject treats the rejection as handled in the test root
+     * to avoid unhandled promise rejections.
+     */
+    onReject?: (err: unknown) => void;
+    /**
+     * Keys that trigger a reset when changed.
+     */
+    resetKeys?: unknown | (() => unknown);
+};
+/**
+ * Handle returned from createTestSuspenseToken().
+ */
+interface TestSuspenseHandle {
+    /**
+     * The suspense token to throw in a component.
+     */
+    token: {
+        then: PromiseLike<void>['then'];
+    };
+    /**
+     * Resolve the suspense, allowing children to render.
+     */
+    resolve: () => void;
+    /**
+     * Reject the suspense with an error.
+     */
+    reject: (err: unknown) => void;
+}
+
+/**
+ * @fileoverview @fictjs/testing-library - Testing utilities for Fict components
+ *
+ * This library provides utilities for testing Fict components in a manner
+ * similar to @testing-library/react and @solidjs/testing-library.
+ *
+ * ## Key Features
+ *
+ * - `render()` - Render a Fict component and get queries
+ * - `cleanup()` - Clean up rendered components
+ * - `renderHook()` - Test custom reactive code in isolation
+ * - `testEffect()` - Test effects with async assertions
+ *
+ * ## Example Usage
+ *
+ * ```tsx
+ * import { render, screen, cleanup } from '@fictjs/testing-library'
+ *
+ * test('renders greeting', () => {
+ *   render(() => <Greeting name="World" />)
+ *   expect(screen.getByText('Hello, World!')).toBeInTheDocument()
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Render a Fict component for testing.
+ *
+ * @param view - A function that returns the component to render
+ * @param options - Render options (container, baseElement, queries, wrapper)
+ * @returns A render result with queries and utilities
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const { getByText } = render(() => <MyComponent />)
+ * expect(getByText('Hello')).toBeInTheDocument()
+ *
+ * // With wrapper (for context providers)
+ * const { getByText } = render(() => <MyComponent />, {
+ *   wrapper: ({ children }) => <ThemeProvider>{children}</ThemeProvider>
+ * })
+ *
+ * // With custom container
+ * const container = document.createElement('div')
+ * const { getByText } = render(() => <MyComponent />, { container })
+ * ```
+ */
+declare function render<Q extends Queries = typeof queries>(view: View, options?: RenderOptions<Q>): RenderResult<Q>;
+/**
+ * Clean up all rendered components.
+ *
+ * This is called automatically after each test when using Vitest/Jest.
+ * Can be called manually if needed.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   cleanup()
+ * })
+ * ```
+ */
+declare function cleanup(): void;
+/**
+ * Render a hook/reactive code for testing.
+ *
+ * This is useful for testing custom reactive logic that uses
+ * createEffect, createMemo, onMount, etc.
+ *
+ * @param hookFn - A function that contains the reactive code to test
+ * @param options - Options for rendering the hook
+ * @returns Result with the hook's return value and cleanup utilities
+ *
+ * @note
+ * renderHook().rerender() disposes the previous root and mounts a new one.
+ * Hook state does not persist across rerenders.
+ *
+ * @example
+ * ```ts
+ * // Test a counter hook
+ * function useCounter(initial: number) {
+ *   let count = $state(initial)
+ *   const increment = () => count++
+ *   return { count: () => count, increment }
+ * }
+ *
+ * test('counter increments', () => {
+ *   const { result, cleanup } = renderHook(() => useCounter(0))
+ *   expect(result.current.count()).toBe(0)
+ *   result.current.increment()
+ *   expect(result.current.count()).toBe(1)
+ *   cleanup()
+ * })
+ *
+ * // With initial props
+ * const { result, rerender } = renderHook(
+ *   (initial) => useCounter(initial),
+ *   { initialProps: [10] }
+ * )
+ * expect(result.current.count()).toBe(10)
+ * rerender([20]) // Re-run with new props
+ * ```
+ */
+declare function renderHook<Result, Props extends unknown[] = []>(hookFn: (...args: Props) => Result, options?: RenderHookOptions<Props> | Props): RenderHookResult<Result, Props>;
+/**
+ * Test an effect asynchronously.
+ *
+ * This is useful for testing effects that need to wait for async operations
+ * or reactive updates.
+ *
+ * @param fn - A function that receives a `done` callback to signal completion
+ * @param owner - Optional root context to run the effect in
+ * @returns A promise that resolves with the result passed to `done`
+ *
+ * @example
+ * ```ts
+ * // Test an async effect
+ * test('fetches data', async () => {
+ *   const result = await testEffect((done) => {
+ *     let data = $state(null)
+ *
+ *     createEffect(() => {
+ *       if (data !== null) {
+ *         done(data)
+ *       }
+ *     })
+ *
+ *     // Simulate async data fetch
+ *     setTimeout(() => {
+ *       data = 'Hello'
+ *     }, 100)
+ *   })
+ *
+ *   expect(result).toBe('Hello')
+ * })
+ *
+ * // Test reactive updates
+ * test('derived value updates', async () => {
+ *   const result = await testEffect<number>((done) => {
+ *     let count = $state(0)
+ *     const doubled = count * 2
+ *
+ *     createEffect(() => {
+ *       if (doubled === 4) {
+ *         done(doubled)
+ *       }
+ *     })
+ *
+ *     count = 2
+ *   })
+ *
+ *   expect(result).toBe(4)
+ * })
+ * ```
+ */
+declare function testEffect<T = void>(fn: TestEffectCallback<T>): Promise<T>;
+/**
+ * Wait for a condition to be true.
+ * This is a simple wrapper that can be used alongside testEffect.
+ *
+ * @param condition - A function that returns true when the condition is met
+ * @param options - Options for waiting (timeout, interval)
+ * @returns A promise that resolves when the condition is true
+ *
+ * @example
+ * ```ts
+ * await waitForCondition(() => element.textContent === 'Loaded')
+ * ```
+ */
+declare function waitForCondition(condition: () => boolean, options?: {
+    timeout?: number;
+    interval?: number;
+}): Promise<void>;
+/**
+ * Flush pending microtasks and effects.
+ * Useful for ensuring all reactive updates have completed.
+ *
+ * @returns A promise that resolves after microtasks are flushed
+ */
+declare function flush(): Promise<void>;
+/**
+ * Run updates and flush pending microtasks/effects.
+ * Similar to React Testing Library's act().
+ *
+ * @param fn - A function that triggers updates (can be async)
+ * @returns The result of the function after flush
+ */
+declare function act<T>(fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Render a view wrapped in an ErrorBoundary for testing error handling.
+ *
+ * The ErrorBoundary catches errors thrown during child component rendering
+ * and displays a fallback UI. Use this to test error handling behavior.
+ *
+ * @param view - A function that returns the component to render
+ * @param options - Render options including ErrorBoundary props
+ * @returns A render result with error boundary utilities
+ *
+ * @example
+ * ```tsx
+ * // Test error catching - component throws during render
+ * const onError = vi.fn()
+ * const { container, isShowingFallback } = renderWithErrorBoundary(
+ *   () => <ComponentThatMightThrow />,
+ *   {
+ *     fallback: (err) => <div data-testid="error">{err.message}</div>,
+ *     onError,
+ *   }
+ * )
+ *
+ * // If component threw, fallback is shown
+ * if (isShowingFallback()) {
+ *   expect(container.querySelector('[data-testid="error"]')).toBeTruthy()
+ * }
+ * ```
+ */
+declare function renderWithErrorBoundary<Q extends Queries = typeof queries>(view: View, options?: ErrorBoundaryRenderOptions<Q>): ErrorBoundaryRenderResult<Q>;
+/**
+ * Create a test suspense token for controlling suspense in tests.
+ *
+ * @returns A handle with token, resolve, and reject functions
+ *
+ * @example
+ * ```tsx
+ * const { token, resolve, reject } = createTestSuspenseToken()
+ *
+ * const { isShowingFallback, waitForResolution } = renderWithSuspense(
+ *   () => {
+ *     // Throw token to trigger suspense
+ *     throw token
+ *   },
+ *   { fallback: <div>Loading...</div> }
+ * )
+ *
+ * expect(isShowingFallback()).toBe(true)
+ *
+ * // Resolve the suspense
+ * resolve()
+ * await waitForResolution()
+ *
+ * expect(isShowingFallback()).toBe(false)
+ * ```
+ */
+declare function createTestSuspenseToken(): TestSuspenseHandle;
+/**
+ * Render a view wrapped in a Suspense boundary for testing async loading states.
+ *
+ * Note: Suspense in Fict catches async tokens thrown during child rendering.
+ * To test suspense, use createTestSuspenseToken() and throw the token in your component.
+ *
+ * @param view - A function that returns the component to render
+ * @param options - Render options including Suspense props
+ * @returns A render result with suspense utilities
+ *
+ * @example
+ * ```tsx
+ * // Test non-suspending component
+ * const { container } = renderWithSuspense(
+ *   () => <LoadedComponent />,
+ *   { fallback: <div>Loading...</div> }
+ * )
+ * expect(container.textContent).toBe('Loaded')
+ * ```
+ */
+declare function renderWithSuspense<Q extends Queries = typeof queries>(view: View, options?: SuspenseRenderOptions<Q>): SuspenseRenderResult<Q>;
+
+export { type DebugFn, type ErrorBoundaryRenderOptions, type ErrorBoundaryRenderResult, type MountedRef, type RenderHookOptions, type RenderHookResult, type RenderOptions, type RenderResult, type SuspenseRenderOptions, type SuspenseRenderResult, type TestEffectCallback, type TestSuspenseHandle, type View, act, cleanup, createTestSuspenseToken, flush, render, renderHook, renderWithErrorBoundary, renderWithSuspense, testEffect, waitForCondition };