@testforgejs/vue-test-core 1.0.0-beta.0

package/dist/index.d.cts

@@ -0,0 +1,194 @@
+import { Component, Plugin } from 'vue';
+import { MountingOptions, mount } from '@vue/test-utils';
+import { ComponentProps, ComponentSlots } from 'vue-component-type-helpers';
+
+/** Plugin name (e.g., ‘pinia’, ‘i18n’, ‘router’) */
+type PluginName = string;
+/**
+ * Runtime value returned by a TestForge plugin factory.
+ *
+ * The returned value must be compatible with
+ * Vue Test Utils `global.plugins`.
+ */
+type MountPlugin = Plugin | [Plugin, ...unknown[]];
+interface PluginDefinition<TPlugin extends MountPlugin = MountPlugin, TOptions = unknown> {
+    beforeCreate?: (ctx: PipelineContext, options: TOptions) => TOptions;
+    create: (options: TOptions) => TPlugin;
+    afterCreate?: (plugin: TPlugin, ctx: PipelineContext) => void;
+}
+interface PluginModule<TPlugin extends MountPlugin = MountPlugin, TOptions = unknown> {
+    getName(): PluginName;
+    getDefinition(): PluginDefinition<TPlugin, TOptions>;
+}
+interface PluginManifestEntry<TPlugin extends MountPlugin = MountPlugin, TOptions = unknown> {
+    module: PluginModule<TPlugin, TOptions>;
+    enabled: boolean;
+}
+type SupportedPluginState = boolean;
+type SupportedPluginsMap = Record<PluginName, SupportedPluginState>;
+type RuntimePluginConfig = Record<string, any>;
+type RuntimePluginOption = RuntimePluginConfig | false;
+type ResolvedPluginOptions = Record<PluginName, RuntimePluginOption>;
+type PluginConfigDefaults = Record<PluginName, RuntimePluginConfig>;
+interface PluginRuntimeMeta<TInstance> {
+    __sharedInstance?: TInstance;
+    expose?: (instance: TInstance) => void;
+}
+type RuntimePluginOptions<TInstance, TOptions = object> = TOptions & PluginRuntimeMeta<TInstance>;
+interface InstanceCapture<TInstance> {
+    expose(instance: TInstance): void;
+    readonly instance: TInstance | undefined;
+}
+interface PluginMeta {
+    instance?: unknown;
+}
+interface PluginOptionsMap {
+}
+type PluginOptionsInput = {
+    [K in keyof PluginOptionsMap]?: PluginOptionsMap[K] | false;
+};
+interface PluginControlOptions<TInstance> {
+    expose?: (instance: TInstance) => void;
+}
+type PluginOverride<T = unknown> = (T extends Record<string, any> ? Partial<T> & {
+    __meta?: PluginMeta;
+} : T & {
+    __meta?: PluginMeta;
+}) | false;
+type PluginOverridesInput = {
+    [K in keyof PluginOptionsMap]?: PluginOverride<PluginOptionsMap[K]>;
+};
+interface ComponentFactoryOptions<Props = any, Slots = any, Data = any> extends Omit<MountingOptions<Props, Data>, "props" | "slots" | "data"> {
+    /** Strictly typed data */
+    data?: () => Data;
+    /** Strictly typed props */
+    props?: Props;
+    /** Strictly typed slots */
+    slots?: Slots;
+    /** Managed plugin configuration */
+    plugins?: PluginOptionsInput;
+    /** Disable managed plugins from presets */
+    skipManagedPlugins?: boolean;
+}
+type ComponentFactoryExtraOptions = {
+    /**
+     * Name of the preset to activate for this factory call.
+     * Controls which plugins and defaults will be applied.
+     */
+    preset?: keyof TestFrameworkPresets;
+    /**
+     * Skip factory-level default props during merge.
+     */
+    skipDefaultProps?: boolean;
+    /**
+     * Skip factory-level default slots during merge.
+     */
+    skipDefaultSlots?: boolean;
+    /**
+     * Skip BASE_MOUNT_OPTIONS during merge.
+     */
+    skipDefaultOptions?: boolean;
+    plugins?: PluginOverridesInput;
+};
+/**
+ * Default plugin configuration.
+ *
+ * The object keys must correspond to plugin names returned by
+ * `plugin.getName()` for plugins declared in `manifest`.
+ */
+interface PresetDefinition {
+    manifest: PluginManifestEntry<any, any>[];
+    defaults: PluginConfigDefaults;
+}
+type TestFrameworkPresets = Record<string, PresetDefinition>;
+interface PipelineContext {
+    defaultMountOptions: ComponentFactoryOptions;
+    mountOptions: ComponentFactoryOptions;
+    extraOptions: ComponentFactoryExtraOptions;
+    supportedPlugins: SupportedPluginsMap;
+    preset: PresetDefinition | undefined;
+    result: PipelineContextResult;
+}
+/**
+ * Runtime type.
+ *
+ * The pipeline operates without knowledge of a specific component,
+ * therefore Props/Data generics are intentionally erased.
+ */
+type MountOptionsState = Partial<MountingOptions<any, any>>;
+interface PipelineContextResult {
+    mountOptions: MountOptionsState;
+    global: NonNullable<MountingOptions<any, any>["global"]>;
+    pluginDefaultsState: PluginConfigDefaults;
+    plugins: ResolvedPluginOptions;
+}
+/**
+ * Input props accepted by TestForge.
+ *
+ * Props are intentionally typed as Partial<ComponentProps<T>>.
+ *
+ * TestForge merges props from multiple sources:
+ * - factory defaults
+ * - mount option props
+ * - per-test props
+ *
+ * Because each source represents only a partial contribution
+ * to the final prop set, requiring complete component props
+ * at every layer would be unnecessarily restrictive.
+ */
+type ComponentPropsInput<T extends Component> = Partial<ComponentProps<T>>;
+type RelaxedSlot<T> = T extends (props: infer P) => unknown ? (props: P) => unknown : () => unknown;
+type ComponentSlotsInput<T extends Component> = Partial<{
+    [K in keyof ComponentSlots<T>]: RelaxedSlot<ComponentSlots<T>[K]>;
+}>;
+type ComponentData<T extends Component> = T extends {
+    data?(...args: any): infer D;
+} ? D extends Record<string, any> ? D : Record<string, never> : Record<string, never>;
+type ComponentDataInput<T extends Component> = Partial<ComponentData<T>>;
+/**
+ * Main component factory returned by testComponentFactory
+ *
+ * Preserve exact Vue Test Utils wrapper typing.
+ *
+ * TestForge intentionally mirrors VTU mount() return types
+ * instead of maintaining a parallel wrapper type hierarchy.
+ */
+type ComponentFactory<T extends Component> = (props?: ComponentPropsInput<T>, mountOptions?: ComponentFactoryOptions<ComponentPropsInput<T>, ComponentSlotsInput<T>, ComponentDataInput<T>>, slots?: ComponentSlotsInput<T>, extraOptions?: ComponentFactoryExtraOptions) => ReturnType<typeof mount<T>>;
+interface CreateTestFrameworkOptions {
+    /** Preset configurations for plugins */
+    presets?: TestFrameworkPresets;
+    /**
+     * Default value for Vue Test Utils `shallow` mounting.
+     *
+     * Used when a factory call does not explicitly provide
+     * the `shallow` option.
+     *
+     * @default false
+     */
+    shallowByDefault?: boolean;
+}
+interface ComponentFactoryCreator {
+    <T extends Component>(component: T, defaultProps?: ComponentPropsInput<T>, defaultMountOptions?: ComponentFactoryOptions<ComponentPropsInput<T>, ComponentSlotsInput<T>, ComponentDataInput<T>>, defaultSlots?: ComponentSlotsInput<T>): ComponentFactory<T>;
+}
+interface TestFramework {
+    /**
+     * Creates a reusable component mounting factory.
+     */
+    testComponentFactory: ComponentFactoryCreator;
+}
+
+declare function createTestFramework(options?: CreateTestFrameworkOptions): TestFramework;
+
+declare function createPluginInstance<TInstance, TOptions extends object>(factory: (options: TOptions) => TInstance, options: RuntimePluginOptions<TInstance, TOptions>): TInstance;
+
+declare function createVuePlugin<TPlugin extends Plugin, TOptions extends object>(plugin: TPlugin, options: RuntimePluginOptions<[TPlugin, TOptions], TOptions>): [TPlugin, TOptions];
+
+declare function captureInstance<T = unknown>(): InstanceCapture<T>;
+
+declare function validatePreset(name: PluginName, preset: PresetDefinition): void;
+
+declare function validatePresets(presets?: TestFrameworkPresets): void;
+
+declare const Types: {};
+
+export { type ComponentFactory, type ComponentFactoryCreator, type ComponentFactoryExtraOptions, type ComponentFactoryOptions, type MountPlugin, type PluginControlOptions, type PluginModule, type PluginOptionsInput, type PluginOptionsMap, type PluginOverridesInput, type PresetDefinition, type TestFramework, type TestFrameworkPresets, Types, captureInstance, createPluginInstance, createTestFramework, createVuePlugin, validatePreset, validatePresets };

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+import { Component, Plugin } from 'vue';
+import { MountingOptions, mount } from '@vue/test-utils';
+import { ComponentProps, ComponentSlots } from 'vue-component-type-helpers';
+
+/** Plugin name (e.g., ‘pinia’, ‘i18n’, ‘router’) */
+type PluginName = string;
+/**
+ * Runtime value returned by a TestForge plugin factory.
+ *
+ * The returned value must be compatible with
+ * Vue Test Utils `global.plugins`.
+ */
+type MountPlugin = Plugin | [Plugin, ...unknown[]];
+interface PluginDefinition<TPlugin extends MountPlugin = MountPlugin, TOptions = unknown> {
+    beforeCreate?: (ctx: PipelineContext, options: TOptions) => TOptions;
+    create: (options: TOptions) => TPlugin;
+    afterCreate?: (plugin: TPlugin, ctx: PipelineContext) => void;
+}
+interface PluginModule<TPlugin extends MountPlugin = MountPlugin, TOptions = unknown> {
+    getName(): PluginName;
+    getDefinition(): PluginDefinition<TPlugin, TOptions>;
+}
+interface PluginManifestEntry<TPlugin extends MountPlugin = MountPlugin, TOptions = unknown> {
+    module: PluginModule<TPlugin, TOptions>;
+    enabled: boolean;
+}
+type SupportedPluginState = boolean;
+type SupportedPluginsMap = Record<PluginName, SupportedPluginState>;
+type RuntimePluginConfig = Record<string, any>;
+type RuntimePluginOption = RuntimePluginConfig | false;
+type ResolvedPluginOptions = Record<PluginName, RuntimePluginOption>;
+type PluginConfigDefaults = Record<PluginName, RuntimePluginConfig>;
+interface PluginRuntimeMeta<TInstance> {
+    __sharedInstance?: TInstance;
+    expose?: (instance: TInstance) => void;
+}
+type RuntimePluginOptions<TInstance, TOptions = object> = TOptions & PluginRuntimeMeta<TInstance>;
+interface InstanceCapture<TInstance> {
+    expose(instance: TInstance): void;
+    readonly instance: TInstance | undefined;
+}
+interface PluginMeta {
+    instance?: unknown;
+}
+interface PluginOptionsMap {
+}
+type PluginOptionsInput = {
+    [K in keyof PluginOptionsMap]?: PluginOptionsMap[K] | false;
+};
+interface PluginControlOptions<TInstance> {
+    expose?: (instance: TInstance) => void;
+}
+type PluginOverride<T = unknown> = (T extends Record<string, any> ? Partial<T> & {
+    __meta?: PluginMeta;
+} : T & {
+    __meta?: PluginMeta;
+}) | false;
+type PluginOverridesInput = {
+    [K in keyof PluginOptionsMap]?: PluginOverride<PluginOptionsMap[K]>;
+};
+interface ComponentFactoryOptions<Props = any, Slots = any, Data = any> extends Omit<MountingOptions<Props, Data>, "props" | "slots" | "data"> {
+    /** Strictly typed data */
+    data?: () => Data;
+    /** Strictly typed props */
+    props?: Props;
+    /** Strictly typed slots */
+    slots?: Slots;
+    /** Managed plugin configuration */
+    plugins?: PluginOptionsInput;
+    /** Disable managed plugins from presets */
+    skipManagedPlugins?: boolean;
+}
+type ComponentFactoryExtraOptions = {
+    /**
+     * Name of the preset to activate for this factory call.
+     * Controls which plugins and defaults will be applied.
+     */
+    preset?: keyof TestFrameworkPresets;
+    /**
+     * Skip factory-level default props during merge.
+     */
+    skipDefaultProps?: boolean;
+    /**
+     * Skip factory-level default slots during merge.
+     */
+    skipDefaultSlots?: boolean;
+    /**
+     * Skip BASE_MOUNT_OPTIONS during merge.
+     */
+    skipDefaultOptions?: boolean;
+    plugins?: PluginOverridesInput;
+};
+/**
+ * Default plugin configuration.
+ *
+ * The object keys must correspond to plugin names returned by
+ * `plugin.getName()` for plugins declared in `manifest`.
+ */
+interface PresetDefinition {
+    manifest: PluginManifestEntry<any, any>[];
+    defaults: PluginConfigDefaults;
+}
+type TestFrameworkPresets = Record<string, PresetDefinition>;
+interface PipelineContext {
+    defaultMountOptions: ComponentFactoryOptions;
+    mountOptions: ComponentFactoryOptions;
+    extraOptions: ComponentFactoryExtraOptions;
+    supportedPlugins: SupportedPluginsMap;
+    preset: PresetDefinition | undefined;
+    result: PipelineContextResult;
+}
+/**
+ * Runtime type.
+ *
+ * The pipeline operates without knowledge of a specific component,
+ * therefore Props/Data generics are intentionally erased.
+ */
+type MountOptionsState = Partial<MountingOptions<any, any>>;
+interface PipelineContextResult {
+    mountOptions: MountOptionsState;
+    global: NonNullable<MountingOptions<any, any>["global"]>;
+    pluginDefaultsState: PluginConfigDefaults;
+    plugins: ResolvedPluginOptions;
+}
+/**
+ * Input props accepted by TestForge.
+ *
+ * Props are intentionally typed as Partial<ComponentProps<T>>.
+ *
+ * TestForge merges props from multiple sources:
+ * - factory defaults
+ * - mount option props
+ * - per-test props
+ *
+ * Because each source represents only a partial contribution
+ * to the final prop set, requiring complete component props
+ * at every layer would be unnecessarily restrictive.
+ */
+type ComponentPropsInput<T extends Component> = Partial<ComponentProps<T>>;
+type RelaxedSlot<T> = T extends (props: infer P) => unknown ? (props: P) => unknown : () => unknown;
+type ComponentSlotsInput<T extends Component> = Partial<{
+    [K in keyof ComponentSlots<T>]: RelaxedSlot<ComponentSlots<T>[K]>;
+}>;
+type ComponentData<T extends Component> = T extends {
+    data?(...args: any): infer D;
+} ? D extends Record<string, any> ? D : Record<string, never> : Record<string, never>;
+type ComponentDataInput<T extends Component> = Partial<ComponentData<T>>;
+/**
+ * Main component factory returned by testComponentFactory
+ *
+ * Preserve exact Vue Test Utils wrapper typing.
+ *
+ * TestForge intentionally mirrors VTU mount() return types
+ * instead of maintaining a parallel wrapper type hierarchy.
+ */
+type ComponentFactory<T extends Component> = (props?: ComponentPropsInput<T>, mountOptions?: ComponentFactoryOptions<ComponentPropsInput<T>, ComponentSlotsInput<T>, ComponentDataInput<T>>, slots?: ComponentSlotsInput<T>, extraOptions?: ComponentFactoryExtraOptions) => ReturnType<typeof mount<T>>;
+interface CreateTestFrameworkOptions {
+    /** Preset configurations for plugins */
+    presets?: TestFrameworkPresets;
+    /**
+     * Default value for Vue Test Utils `shallow` mounting.
+     *
+     * Used when a factory call does not explicitly provide
+     * the `shallow` option.
+     *
+     * @default false
+     */
+    shallowByDefault?: boolean;
+}
+interface ComponentFactoryCreator {
+    <T extends Component>(component: T, defaultProps?: ComponentPropsInput<T>, defaultMountOptions?: ComponentFactoryOptions<ComponentPropsInput<T>, ComponentSlotsInput<T>, ComponentDataInput<T>>, defaultSlots?: ComponentSlotsInput<T>): ComponentFactory<T>;
+}
+interface TestFramework {
+    /**
+     * Creates a reusable component mounting factory.
+     */
+    testComponentFactory: ComponentFactoryCreator;
+}
+
+declare function createTestFramework(options?: CreateTestFrameworkOptions): TestFramework;
+
+declare function createPluginInstance<TInstance, TOptions extends object>(factory: (options: TOptions) => TInstance, options: RuntimePluginOptions<TInstance, TOptions>): TInstance;
+
+declare function createVuePlugin<TPlugin extends Plugin, TOptions extends object>(plugin: TPlugin, options: RuntimePluginOptions<[TPlugin, TOptions], TOptions>): [TPlugin, TOptions];
+
+declare function captureInstance<T = unknown>(): InstanceCapture<T>;
+
+declare function validatePreset(name: PluginName, preset: PresetDefinition): void;
+
+declare function validatePresets(presets?: TestFrameworkPresets): void;
+
+declare const Types: {};
+
+export { type ComponentFactory, type ComponentFactoryCreator, type ComponentFactoryExtraOptions, type ComponentFactoryOptions, type MountPlugin, type PluginControlOptions, type PluginModule, type PluginOptionsInput, type PluginOptionsMap, type PluginOverridesInput, type PresetDefinition, type TestFramework, type TestFrameworkPresets, Types, captureInstance, createPluginInstance, createTestFramework, createVuePlugin, validatePreset, validatePresets };