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

package/README.md

@@ -1,18 +1,21 @@
 # @testforgejs/vue-test-core
 
-> Core runtime & declarative testing infrastructure for Vue 3
+> Core runtime and declarative testing infrastructure for Vue 3.
 
 `@testforgejs/vue-test-core` is the core runtime of **TestForge**. It provides the framework for creating reusable, type-safe component test factories and coordinating managed Vue ecosystem plugins.
 
 The core package provides:
 
-- type-safe `testComponentFactory` instances
-- plugin registration and lifecycle management
-- project-level preset configuration
-- reusable component test factories
-- a hierarchical configuration merge pipeline (Preset → Factory → Test → Extra)
+- type-safe `testComponentFactory` instances;
+- plugin registration and lifecycle management;
+- preset-based runtime configuration;
+- reusable component test factories;
+- a hierarchical configuration resolution pipeline:
+  **Preset → Factory → Test → Extra Options**.
 
-The core package itself does **not** include or configure any Vue ecosystem plugins. Plugins are provided by separate TestForge plugin packages and made available to the framework through a **preset**.
+The core package itself does **not** include or configure Vue ecosystem plugins. Plugin integrations are provided by separate TestForge packages and become available to the framework through presets.
+
+> Core defines the runtime. Plugins define integrations. Base presets define shared environments. Runner-specific recommended presets add runner-specific behavior. The host application provides Vue ecosystem dependencies.
 
 ## Installation
 
@@ -36,35 +39,139 @@ npm install -D @testforgejs/vue-test-core
 yarn add -D @testforgejs/vue-test-core
 ```
 
+> [!NOTE]
+> TestForge requires **[Vue](https://vuejs.org/) 3.3.0 or higher**.
+>
+> `vue` and `@vue/test-utils` are peer dependencies of `@testforgejs/vue-test-core`. Make sure they are installed in your project.
+
+For most projects, you will also want to install a preset package that defines the managed Vue plugins available to your tests.
+
+---
+
 ## Presets
 
-A **preset** defines the managed plugins available to your TestForge runtime and provides their project-level default configuration.
+A **preset** defines a TestForge runtime environment.
+
+A preset controls:
+
+- which managed plugins are available;
+- which plugins are enabled by default;
+- the default configuration for those plugins.
+
+The preset system keeps the TestForge core independent from specific Vue ecosystem integrations. The core runtime does not need built-in knowledge of Pinia, Vue Router, Vue I18n, Vuetify, PrimeVue, or other integrations.
+
+### Single and Multiple Presets
+
+`createTestFramework()` supports two mutually exclusive ways to configure presets.
 
-The preset system separates the TestForge core from individual Vue ecosystem integrations. This means the core package does not need to know about Pinia, Vue Router, Vue I18n, Vuetify, PrimeVue, or other integrations unless they are explicitly registered through a preset.
+Use `preset` when the framework needs a single runtime environment:
 
-TestForge provides an official recommended preset:
+```typescript
+createTestFramework({
+  preset: projectPreset,
+});
+```
+
+Use `presets` when the framework should provide multiple named runtime environments:
+
+```typescript
+createTestFramework({
+  presets: {
+    default: projectPreset,
+    i18n: i18nPreset,
+    router: routerPreset,
+  },
+});
+```
+
+These options cannot be used together.
+
+A single `preset` is treated as the framework's `default` preset internally. A `presets` registry allows individual factory invocations to select a named preset through `extraOptions.preset`.
+
+For example:
+
+```typescript
+const { testComponentFactory } = createTestFramework({
+  presets: {
+    default: defaultPreset,
+    i18n: i18nPreset,
+  },
+});
+
+const factory = testComponentFactory(MyComponent);
+
+factory(
+  {},
+  {},
+  {},
+  {
+    preset: "i18n",
+  },
+);
+```
+
+This distinction allows a project to start with a single custom runtime environment and introduce named runtime profiles later without changing the preset definition itself.
+
+### Official preset packages
+
+TestForge provides a layered preset architecture:
+
+```text
+@testforgejs/vue-test-preset-base
+            │
+            ├── @testforgejs/vue-test-preset-recommended
+            │       Vitest defaults
+            │
+            └── @testforgejs/vue-test-preset-recommended-jest
+                    Jest defaults
+```
+
+`@testforgejs/vue-test-preset-base` provides shared Vue plugin configuration.
+
+Runner-specific recommended presets build on top of the base presets and add configuration required by a particular test runner.
+
+For example, the recommended Vitest preset provides `vi.fn` as the Pinia `createSpy` implementation.
+
+### Recommended presets
+
+For Vitest:
 
 ```bash
 pnpm add -D @testforgejs/vue-test-preset-recommended
 ```
 
-The recommended preset provides commonly used integrations such as:
+For Jest:
+
+```bash
+pnpm add -D @testforgejs/vue-test-preset-recommended-jest
+```
+
+The recommended presets include configurations for commonly used managed integrations such as:
+
+- Pinia;
+- Vue I18n;
+- Vue Router.
 
-- Pinia
-- Vue Router
-- Vue I18n
+The recommended preset is a convenient starting point for exploring TestForge and its approach to reusable component test environments.
 
-Additional integrations, such as Vuetify and PrimeVue, are available as separate plugin packages and can be included in your own preset configuration.
+However, recommended presets are intentionally generic. Real applications usually have application-specific routes, managed plugins, and plugin defaults. Most projects will therefore eventually benefit from a project-specific preset that extends or adapts an existing preset to the application's runtime environment.
+
+The recommended preset packages are optional. You can also use the base preset directly or create your own project-specific preset.
 
 > [!TIP]
-> The recommended preset is optional. If your project requires a different set of plugins or configurations, you can create a custom preset.
+> If you are getting started with TestForge, use the recommended preset that matches your test runner.
+
+See the [Getting Started Guide](https://github.com/testforgejs/testforge/blob/main/docs/getting-started.md) for the recommended setup and the [Preset Authoring Guide](https://github.com/testforgejs/testforge/blob/main/docs/preset-authoring-guide.md) for creating and composing custom presets.
 
-👉 See the [Getting Started Guide](https://github.com/testforgejs/testforge/blob/main/docs/getting-started.md) for the recommended setup and the [Preset Authoring Guide](https://github.com/testforgejs/testforge/blob/main/docs/preset-authoring-guide.md) for custom presets.
+---
 
 ## Quick Usage
 
+The following example uses Vitest and the recommended Vitest preset registry.
+
 ```typescript
-// tests/setup.ts (or any other initialization file in your project)
+// tests/setup.ts
+
 import { createTestFramework } from "@testforgejs/vue-test-core";
 import { presets } from "@testforgejs/vue-test-preset-recommended";
 
@@ -75,44 +182,84 @@ const { testComponentFactory } = createTestFramework({
 export { testComponentFactory };
 ```
 
+This setup is a good starting point for exploring TestForge. As the application-specific testing environment grows, the project can define its own preset while continuing to reuse the official preset as a base.
+
 The resulting `testComponentFactory` can then be imported and reused throughout your component tests.
 
 ```typescript
-// MyComponent.spec.ts (example component test)
+// MyComponent.spec.ts
+
+import { describe, expect, it } from "vitest";
+
 import { testComponentFactory } from "@/tests/setup";
 import MyComponent from "@/components/MyComponent.vue";
 
 const factory = testComponentFactory(MyComponent);
 
-test("renders correctly", () => {
-  const wrapper = factory();
+describe("MyComponent.vue", () => {
+  it("renders correctly", () => {
+    const wrapper = factory();
 
-  expect(wrapper.exists()).toBe(true);
+    expect(wrapper.exists()).toBe(true);
+  });
 });
 ```
 
+For Jest projects, use `@testforgejs/vue-test-preset-recommended-jest` instead.
+
 👉 For a complete walkthrough, continue with the [Getting Started Guide](https://github.com/testforgejs/testforge/blob/main/docs/getting-started.md).
 
+---
+
+## Project-Specific Presets
+
+Most applications will eventually benefit from some application-specific preset configuration.
+
+For example, a project can extend the recommended preset with its own locale configuration:
+
+```typescript
+import { extendPreset } from "@testforgejs/vue-test-core";
+import { presets as recommendedPresets } from "@testforgejs/vue-test-preset-recommended";
+
+const projectPreset = extendPreset(recommendedPresets.default, {
+  defaults: {
+    i18n: () => ({
+      ...recommendedPresets.default.defaults.i18n(),
+      locale: "uk",
+    }),
+  },
+});
+```
+
+---
+
 ## Documentation
 
 - [Getting Started Guide](https://github.com/testforgejs/testforge/blob/main/docs/getting-started.md) — Set up TestForge in a project and create reusable component test factories.
-- [Configuration & Advanced Usage](https://github.com/testforgejs/testforge/blob/main/docs/configuration.md) — Learn about configuration layers, merge strategies, execution flags, and plugin lifecycle behavior.
+- [Configuration & Advanced Usage](https://github.com/testforgejs/testforge/blob/main/docs/configuration.md) — Learn about configuration layers, merge strategies, execution controls, and plugin lifecycle behavior.
+- [Preset Authoring Guide](https://github.com/testforgejs/testforge/blob/main/docs/preset-authoring-guide.md) — Create and compose custom presets.
 - [Plugin Authoring Guide](https://github.com/testforgejs/testforge/blob/main/docs/plugin-authoring-guide.md) — Create custom TestForge plugins.
-- [Preset Authoring Guide](https://github.com/testforgejs/testforge/blob/main/docs/preset-authoring-guide.md) — Create custom presets for your project or organization.
 
 ## Project
 
 This package is part of the **TestForge** monorepo.
 
-- **[TestForge Project Overview](https://github.com/testforgejs/testforge#readme)** — project overview, package ecosystem, roadmap and repository information.
+- **[TestForge Project Overview](https://github.com/testforgejs/testforge#readme)** — Project overview, package ecosystem, roadmap, and repository information.
 - **Repository:** https://github.com/testforgejs/testforge
 
-## Related packages
+## Related Packages
+
+### Presets
 
+- `@testforgejs/vue-test-preset-base`
 - `@testforgejs/vue-test-preset-recommended`
-- `@testforgejs/vue-test-plugin-router`
+- `@testforgejs/vue-test-preset-recommended-jest`
+
+### Managed Plugins
+
 - `@testforgejs/vue-test-plugin-pinia`
 - `@testforgejs/vue-test-plugin-i18n`
+- `@testforgejs/vue-test-plugin-router`
 - `@testforgejs/vue-test-plugin-vuetify`
 - `@testforgejs/vue-test-plugin-primevue`
 

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   createPluginInstance: () => createPluginInstance,
   createTestFramework: () => createTestFramework,
   createVuePlugin: () => createVuePlugin,
+  extendPreset: () => extendPreset,
   validatePreset: () => validatePreset,
   validatePresets: () => validatePresets
 });
@@ -55,16 +56,29 @@ var FRAMEWORK_NAME = "TestForge";
 var ERROR_PREFIX = `[${FRAMEWORK_NAME}]`;
 var DEFAULT_PRESET_NAME = "default";
 
-// src/validators/validatePreset.ts
+// src/guards/isPlainObject.ts
+function isPlainObject(item) {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(item);
+  return prototype === Object.prototype || prototype === null;
+}
+
+// src/presets/validators/validatePreset.ts
 function validatePreset(name, preset) {
   if (!preset) {
     throw new Error(`${ERROR_PREFIX} Preset "${name}" is null or undefined.`);
   }
-  if (!Array.isArray(preset.manifest)) {
+  if (!isPlainObject(preset)) {
+    throw new Error(`${ERROR_PREFIX} Preset "${name}" must be a plain object.`);
+  }
+  const manifest = preset.manifest;
+  if (!Array.isArray(manifest)) {
     throw new Error(`${ERROR_PREFIX} Preset "${name}" must have a "manifest" array.`);
   }
   const manifestPluginNames = /* @__PURE__ */ new Set();
-  preset.manifest.forEach((entry, index) => {
+  manifest.forEach((entry, index) => {
     const { module: module2, enabled } = entry;
     if (!module2 || typeof module2.getName !== "function") {
       throw new Error(`${ERROR_PREFIX} Invalid module at manifest[${index}] in preset "${name}".`);
@@ -82,26 +96,27 @@ function validatePreset(name, preset) {
     }
     manifestPluginNames.add(pluginName);
   });
-  if (preset.defaults) {
-    const defaultKeys = Object.keys(preset.defaults);
-    defaultKeys.forEach((key) => {
-      if (!manifestPluginNames.has(key)) {
-        throw new Error(
-          `${ERROR_PREFIX} Preset "${name}" contains defaults for unknown plugin "${key}". This plugin is not present in the manifest.`
-        );
-      }
-      const value = preset.defaults[key];
-      const isObject = value !== null && typeof value === "object" && !Array.isArray(value);
-      if (!isObject) {
-        throw new Error(
-          `${ERROR_PREFIX} Invalid default configuration for plugin "${key}" in preset "${name}". Expected Object, but received ${typeof value}.`
-        );
-      }
-    });
+  const defaults = preset.defaults;
+  if (!isPlainObject(defaults)) {
+    throw new Error(`${ERROR_PREFIX} Preset "${name}" must have a "defaults" plain object.`);
   }
+  const defaultKeys = Object.keys(defaults);
+  defaultKeys.forEach((key) => {
+    if (!manifestPluginNames.has(key)) {
+      throw new Error(
+        `${ERROR_PREFIX} Preset "${name}" contains defaults for unknown plugin "${key}". This plugin is not present in the manifest.`
+      );
+    }
+    const value = defaults[key];
+    if (typeof value !== "function") {
+      throw new Error(
+        `${ERROR_PREFIX} Invalid default configuration for plugin "${key}" in preset "${name}". Expected a plugin options factory function, but received ${typeof value}.`
+      );
+    }
+  });
 }
 
-// src/utils/getActivePreset.ts
+// src/presets/getActivePreset.ts
 function getActivePreset(presets = {}, extraOptions) {
   const requestedPresetName = extraOptions?.preset?.trim();
   const activeName = requestedPresetName || DEFAULT_PRESET_NAME;
@@ -331,15 +346,6 @@ var withBaseMountOptions = (ctx) => {
   });
 };
 
-// src/guards/isPlainObject.ts
-function isPlainObject(item) {
-  if (item === null || typeof item !== "object" || Array.isArray(item)) {
-    return false;
-  }
-  const prototype = Object.getPrototypeOf(item);
-  return prototype === Object.prototype || prototype === null;
-}
-
 // src/utils/mergeConfigs.ts
 function mergeConfigs(target, source) {
   const arrays = Array.isArray(target) && Array.isArray(source);
@@ -416,12 +422,29 @@ var withPluginsManifest = (ctx) => {
   });
 };
 
+// src/presets/utils/buildPluginOptions.ts
+function buildPluginOptions(pluginName, factory) {
+  const options = factory();
+  if (!isPlainObject(options)) {
+    throw new Error(
+      `${ERROR_PREFIX} Plugin options factory for "${pluginName}" must return a plain object.`
+    );
+  }
+  return options;
+}
+
 // src/pipeline/middleware/transformers/withPreset.ts
 var withPreset = (ctx) => {
   const { preset } = ctx;
   if (!preset?.defaults) return ctx;
+  const pluginDefaultsState = Object.fromEntries(
+    Object.entries(preset.defaults).map(([pluginName, factory]) => [
+      pluginName,
+      buildPluginOptions(pluginName, factory)
+    ])
+  );
   return patchResultState(ctx, {
-    pluginDefaultsState: { ...preset.defaults }
+    pluginDefaultsState
   });
 };
 
@@ -625,8 +648,8 @@ function mountWithPlugins(component, ctx, overrides = {}, runtimeOptions = {
   });
 }
 
-// src/validators/validatePresets.ts
-function validatePresets(presets = {}) {
+// src/presets/validators/validatePresets.ts
+function validatePresets(presets) {
   if (!isPlainObject(presets)) {
     throw new Error(`${ERROR_PREFIX} Presets must be a plain object.`);
   }
@@ -635,8 +658,8 @@ function validatePresets(presets = {}) {
   });
 }
 
-// src/assertions/assertIsPlainObject.ts
-function assertIsPlainObject(value, name = "value") {
+// src/assertions/assertIsPlainObjectValue.ts
+function assertIsPlainObjectValue(value, name = "value") {
   if (!isPlainObject(value)) {
     throw new Error(`${name} must be a plain object.`);
   }
@@ -644,8 +667,14 @@ function assertIsPlainObject(value, name = "value") {
 
 // src/validators/validateCreateTestFrameworkOptions.ts
 function validateCreateTestFrameworkOptions(options = {}) {
-  assertIsPlainObject(options, "createTestFramework options");
-  const { shallowByDefault, presets } = options;
+  assertIsPlainObjectValue(options, "createTestFramework options");
+  const { preset, presets, shallowByDefault } = options;
+  if (preset !== void 0 && presets !== void 0) {
+    throw new Error(`${ERROR_PREFIX} "preset" and "presets" cannot be used together.`);
+  }
+  if (preset !== void 0) {
+    validatePreset("default", preset);
+  }
   if (presets !== void 0) {
     validatePresets(presets);
   }
@@ -748,10 +777,21 @@ function validateComponentFactoryArguments(props, mountOptions, slots, extraOpti
   validateComponentFactoryExtraOptions(extraOptions, presets);
 }
 
+// src/core/utils/resolvePresets.ts
+function resolvePresets(options) {
+  if (options.preset !== void 0) {
+    return {
+      default: options.preset
+    };
+  }
+  return options.presets ?? {};
+}
+
 // src/core/createTestFramework.ts
 function createTestFramework(options = {}) {
   validateCreateTestFrameworkOptions(options);
-  const { presets = {}, shallowByDefault = false } = options;
+  const { shallowByDefault = false } = options;
+  const presets = resolvePresets(options);
   const testComponentFactory = (component, defaultProps = {}, defaultMountOptions = {}, defaultSlots = {}) => {
     validateTestComponentFactoryArguments(
       component,
@@ -850,6 +890,95 @@ function captureInstance() {
   };
 }
 
+// src/presets/validators/validatePluginDefaults.ts
+function validatePluginDefaults(pluginName, value) {
+  if (typeof value !== "function") {
+    throw new Error(
+      `${ERROR_PREFIX} Invalid defaults for plugin "${pluginName}". Preset defaults must be provided as a plugin options factory function.`
+    );
+  }
+}
+
+// src/presets/validators/validatePresetExtension.ts
+function validatePresetExtension(basePreset, extension) {
+  if (!basePreset) {
+    throw new Error(`${ERROR_PREFIX} Cannot extend a null or undefined preset.`);
+  }
+  if (!extension) {
+    throw new Error(`${ERROR_PREFIX} Preset extension is null or undefined.`);
+  }
+  const basePluginNames = new Set(basePreset.manifest.map((entry) => entry.module.getName()));
+  const extensionManifest = extension.manifest ?? [];
+  const extensionManifestPlugins = /* @__PURE__ */ new Set();
+  for (const entry of extensionManifest) {
+    const pluginName = entry.module.getName();
+    if (extensionManifestPlugins.has(pluginName)) {
+      throw new Error(
+        `${ERROR_PREFIX} Duplicate plugin "${pluginName}" in preset extension manifest.`
+      );
+    }
+    extensionManifestPlugins.add(pluginName);
+    const isNewPlugin = !basePluginNames.has(pluginName);
+    if (isNewPlugin) {
+      if (entry.enabled === void 0) {
+        throw new Error(
+          `${ERROR_PREFIX} Cannot add plugin "${pluginName}" to an extended preset without specifying "enabled".`
+        );
+      }
+      const pluginDefaults = extension.defaults?.[pluginName];
+      if (pluginDefaults === void 0) {
+        throw new Error(
+          `${ERROR_PREFIX} Cannot add plugin "${pluginName}" to an extended preset without defining its defaults.`
+        );
+      }
+    }
+  }
+  if (extension.defaults) {
+    for (const [pluginName, pluginDefaults] of Object.entries(extension.defaults)) {
+      validatePluginDefaults(pluginName, pluginDefaults);
+      const isKnownPlugin = basePluginNames.has(pluginName) || extensionManifestPlugins.has(pluginName);
+      if (!isKnownPlugin) {
+        throw new Error(
+          `${ERROR_PREFIX} Cannot define defaults for unknown plugin "${pluginName}" in a preset extension. The plugin must be declared in the manifest.`
+        );
+      }
+    }
+  }
+}
+
+// src/presets/extendPreset.ts
+function extendPreset(basePreset, extension) {
+  validatePresetExtension(basePreset, extension);
+  const manifest = basePreset.manifest.map((entry) => ({ ...entry }));
+  const defaults = { ...basePreset.defaults };
+  const manifestByName = new Map(manifest.map((entry) => [entry.module.getName(), entry]));
+  const extensionManifest = extension.manifest ?? [];
+  for (const entry of extensionManifest) {
+    const pluginName = entry.module.getName();
+    const existingEntry = manifestByName.get(pluginName);
+    if (existingEntry) {
+      if (entry.enabled !== void 0) {
+        existingEntry.enabled = entry.enabled;
+      }
+    } else {
+      manifest.push({
+        module: entry.module,
+        enabled: entry.enabled
+      });
+      manifestByName.set(pluginName, manifest[manifest.length - 1]);
+    }
+  }
+  if (extension.defaults) {
+    for (const [pluginName, pluginDefaults] of Object.entries(extension.defaults)) {
+      defaults[pluginName] = pluginDefaults;
+    }
+  }
+  return {
+    manifest,
+    defaults
+  };
+}
+
 // src/index.ts
 var Types = {};
 // Annotate the CommonJS export names for ESM import in node:
@@ -859,6 +988,7 @@ var Types = {};
   createPluginInstance,
   createTestFramework,
   createVuePlugin,
+  extendPreset,
   validatePreset,
   validatePresets
 });

package/dist/index.d.cts

@@ -29,7 +29,14 @@ type SupportedPluginsMap = Record<PluginName, SupportedPluginState>;
 type RuntimePluginConfig = Record<string, any>;
 type RuntimePluginOption = RuntimePluginConfig | false;
 type ResolvedPluginOptions = Record<PluginName, RuntimePluginOption>;
-type PluginConfigDefaults = Record<PluginName, RuntimePluginConfig>;
+/**
+ * Default plugin configuration factories.
+ *
+ * Only plugins that require preset-level default configuration
+ * need to be included.
+ */
+type PluginConfigDefaults = Record<PluginName, PluginOptionsFactory<RuntimePluginConfig>>;
+type ResolvedPluginDefaults = Record<PluginName, RuntimePluginConfig>;
 interface PluginRuntimeMeta<TInstance> {
     __sharedInstance?: TInstance;
     expose?: (instance: TInstance) => void;
@@ -97,10 +104,23 @@ type ComponentFactoryExtraOptions = {
  * `plugin.getName()` for plugins declared in `manifest`.
  */
 interface PresetDefinition {
+    /** Plugins available to the preset and their enabled state. */
     manifest: PluginManifestEntry<any, any>[];
+    /**
+     * Default plugin configurations.
+     *
+     * A plugin declared in `manifest` does not have to be present here.
+     * Missing defaults mean that the preset provides no default configuration
+     * for that plugin.
+     */
     defaults: PluginConfigDefaults;
 }
 type TestFrameworkPresets = Record<string, PresetDefinition>;
+interface PresetExtension {
+    manifest?: PluginManifestEntry<any, any>[];
+    defaults?: PluginConfigDefaults;
+}
+type PluginOptionsFactory<TOptions> = () => TOptions;
 interface PipelineContext {
     defaultMountOptions: ComponentFactoryOptions;
     mountOptions: ComponentFactoryOptions;
@@ -119,7 +139,7 @@ type MountOptionsState = Partial<MountingOptions<any, any>>;
 interface PipelineContextResult {
     mountOptions: MountOptionsState;
     global: NonNullable<MountingOptions<any, any>["global"]>;
-    pluginDefaultsState: PluginConfigDefaults;
+    pluginDefaultsState: ResolvedPluginDefaults;
     plugins: ResolvedPluginOptions;
 }
 /**
@@ -154,9 +174,7 @@ type ComponentDataInput<T extends Component> = Partial<ComponentData<T>>;
  * 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;
+interface CommonCreateTestFrameworkOptions {
     /**
      * Default value for Vue Test Utils `shallow` mounting.
      *
@@ -167,6 +185,17 @@ interface CreateTestFrameworkOptions {
      */
     shallowByDefault?: boolean;
 }
+interface SinglePresetOptions extends CommonCreateTestFrameworkOptions {
+    /** Single preset used by the framework. */
+    preset: PresetDefinition;
+    presets?: never;
+}
+interface MultiplePresetsOptions extends CommonCreateTestFrameworkOptions {
+    /** Named preset configurations for plugins. */
+    preset?: never;
+    presets?: TestFrameworkPresets;
+}
+type CreateTestFrameworkOptions = SinglePresetOptions | MultiplePresetsOptions;
 interface ComponentFactoryCreator {
     <T extends Component>(component: T, defaultProps?: ComponentPropsInput<T>, defaultMountOptions?: ComponentFactoryOptions<ComponentPropsInput<T>, ComponentSlotsInput<T>, ComponentDataInput<T>>, defaultSlots?: ComponentSlotsInput<T>): ComponentFactory<T>;
 }
@@ -185,10 +214,12 @@ declare function createVuePlugin<TPlugin extends Plugin, TOptions extends object
 
 declare function captureInstance<T = unknown>(): InstanceCapture<T>;
 
-declare function validatePreset(name: PluginName, preset: PresetDefinition): void;
+declare function extendPreset(basePreset: PresetDefinition, extension: PresetExtension): PresetDefinition;
+
+declare function validatePreset(name: string, preset: unknown): asserts preset is PresetDefinition;
 
-declare function validatePresets(presets?: TestFrameworkPresets): void;
+declare function validatePresets(presets: unknown): asserts presets is TestFrameworkPresets;
 
 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 };
+export { type ComponentFactory, type ComponentFactoryCreator, type ComponentFactoryExtraOptions, type ComponentFactoryOptions, type CreateTestFrameworkOptions, type MountPlugin, type PluginControlOptions, type PluginManifestEntry, type PluginModule, type PluginOptionsFactory, type PluginOptionsInput, type PluginOptionsMap, type PluginOverridesInput, type PresetDefinition, type PresetExtension, type TestFramework, type TestFrameworkPresets, Types, captureInstance, createPluginInstance, createTestFramework, createVuePlugin, extendPreset, validatePreset, validatePresets };

package/dist/index.d.ts

@@ -29,7 +29,14 @@ type SupportedPluginsMap = Record<PluginName, SupportedPluginState>;
 type RuntimePluginConfig = Record<string, any>;
 type RuntimePluginOption = RuntimePluginConfig | false;
 type ResolvedPluginOptions = Record<PluginName, RuntimePluginOption>;
-type PluginConfigDefaults = Record<PluginName, RuntimePluginConfig>;
+/**
+ * Default plugin configuration factories.
+ *
+ * Only plugins that require preset-level default configuration
+ * need to be included.
+ */
+type PluginConfigDefaults = Record<PluginName, PluginOptionsFactory<RuntimePluginConfig>>;
+type ResolvedPluginDefaults = Record<PluginName, RuntimePluginConfig>;
 interface PluginRuntimeMeta<TInstance> {
     __sharedInstance?: TInstance;
     expose?: (instance: TInstance) => void;
@@ -97,10 +104,23 @@ type ComponentFactoryExtraOptions = {
  * `plugin.getName()` for plugins declared in `manifest`.
  */
 interface PresetDefinition {
+    /** Plugins available to the preset and their enabled state. */
     manifest: PluginManifestEntry<any, any>[];
+    /**
+     * Default plugin configurations.
+     *
+     * A plugin declared in `manifest` does not have to be present here.
+     * Missing defaults mean that the preset provides no default configuration
+     * for that plugin.
+     */
     defaults: PluginConfigDefaults;
 }
 type TestFrameworkPresets = Record<string, PresetDefinition>;
+interface PresetExtension {
+    manifest?: PluginManifestEntry<any, any>[];
+    defaults?: PluginConfigDefaults;
+}
+type PluginOptionsFactory<TOptions> = () => TOptions;
 interface PipelineContext {
     defaultMountOptions: ComponentFactoryOptions;
     mountOptions: ComponentFactoryOptions;
@@ -119,7 +139,7 @@ type MountOptionsState = Partial<MountingOptions<any, any>>;
 interface PipelineContextResult {
     mountOptions: MountOptionsState;
     global: NonNullable<MountingOptions<any, any>["global"]>;
-    pluginDefaultsState: PluginConfigDefaults;
+    pluginDefaultsState: ResolvedPluginDefaults;
     plugins: ResolvedPluginOptions;
 }
 /**
@@ -154,9 +174,7 @@ type ComponentDataInput<T extends Component> = Partial<ComponentData<T>>;
  * 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;
+interface CommonCreateTestFrameworkOptions {
     /**
      * Default value for Vue Test Utils `shallow` mounting.
      *
@@ -167,6 +185,17 @@ interface CreateTestFrameworkOptions {
      */
     shallowByDefault?: boolean;
 }
+interface SinglePresetOptions extends CommonCreateTestFrameworkOptions {
+    /** Single preset used by the framework. */
+    preset: PresetDefinition;
+    presets?: never;
+}
+interface MultiplePresetsOptions extends CommonCreateTestFrameworkOptions {
+    /** Named preset configurations for plugins. */
+    preset?: never;
+    presets?: TestFrameworkPresets;
+}
+type CreateTestFrameworkOptions = SinglePresetOptions | MultiplePresetsOptions;
 interface ComponentFactoryCreator {
     <T extends Component>(component: T, defaultProps?: ComponentPropsInput<T>, defaultMountOptions?: ComponentFactoryOptions<ComponentPropsInput<T>, ComponentSlotsInput<T>, ComponentDataInput<T>>, defaultSlots?: ComponentSlotsInput<T>): ComponentFactory<T>;
 }
@@ -185,10 +214,12 @@ declare function createVuePlugin<TPlugin extends Plugin, TOptions extends object
 
 declare function captureInstance<T = unknown>(): InstanceCapture<T>;
 
-declare function validatePreset(name: PluginName, preset: PresetDefinition): void;
+declare function extendPreset(basePreset: PresetDefinition, extension: PresetExtension): PresetDefinition;
+
+declare function validatePreset(name: string, preset: unknown): asserts preset is PresetDefinition;
 
-declare function validatePresets(presets?: TestFrameworkPresets): void;
+declare function validatePresets(presets: unknown): asserts presets is TestFrameworkPresets;
 
 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 };
+export { type ComponentFactory, type ComponentFactoryCreator, type ComponentFactoryExtraOptions, type ComponentFactoryOptions, type CreateTestFrameworkOptions, type MountPlugin, type PluginControlOptions, type PluginManifestEntry, type PluginModule, type PluginOptionsFactory, type PluginOptionsInput, type PluginOptionsMap, type PluginOverridesInput, type PresetDefinition, type PresetExtension, type TestFramework, type TestFrameworkPresets, Types, captureInstance, createPluginInstance, createTestFramework, createVuePlugin, extendPreset, validatePreset, validatePresets };

package/dist/index.js

@@ -23,16 +23,29 @@ var FRAMEWORK_NAME = "TestForge";
 var ERROR_PREFIX = `[${FRAMEWORK_NAME}]`;
 var DEFAULT_PRESET_NAME = "default";
 
-// src/validators/validatePreset.ts
+// src/guards/isPlainObject.ts
+function isPlainObject(item) {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(item);
+  return prototype === Object.prototype || prototype === null;
+}
+
+// src/presets/validators/validatePreset.ts
 function validatePreset(name, preset) {
   if (!preset) {
     throw new Error(`${ERROR_PREFIX} Preset "${name}" is null or undefined.`);
   }
-  if (!Array.isArray(preset.manifest)) {
+  if (!isPlainObject(preset)) {
+    throw new Error(`${ERROR_PREFIX} Preset "${name}" must be a plain object.`);
+  }
+  const manifest = preset.manifest;
+  if (!Array.isArray(manifest)) {
     throw new Error(`${ERROR_PREFIX} Preset "${name}" must have a "manifest" array.`);
   }
   const manifestPluginNames = /* @__PURE__ */ new Set();
-  preset.manifest.forEach((entry, index) => {
+  manifest.forEach((entry, index) => {
     const { module, enabled } = entry;
     if (!module || typeof module.getName !== "function") {
       throw new Error(`${ERROR_PREFIX} Invalid module at manifest[${index}] in preset "${name}".`);
@@ -50,26 +63,27 @@ function validatePreset(name, preset) {
     }
     manifestPluginNames.add(pluginName);
   });
-  if (preset.defaults) {
-    const defaultKeys = Object.keys(preset.defaults);
-    defaultKeys.forEach((key) => {
-      if (!manifestPluginNames.has(key)) {
-        throw new Error(
-          `${ERROR_PREFIX} Preset "${name}" contains defaults for unknown plugin "${key}". This plugin is not present in the manifest.`
-        );
-      }
-      const value = preset.defaults[key];
-      const isObject = value !== null && typeof value === "object" && !Array.isArray(value);
-      if (!isObject) {
-        throw new Error(
-          `${ERROR_PREFIX} Invalid default configuration for plugin "${key}" in preset "${name}". Expected Object, but received ${typeof value}.`
-        );
-      }
-    });
+  const defaults = preset.defaults;
+  if (!isPlainObject(defaults)) {
+    throw new Error(`${ERROR_PREFIX} Preset "${name}" must have a "defaults" plain object.`);
   }
+  const defaultKeys = Object.keys(defaults);
+  defaultKeys.forEach((key) => {
+    if (!manifestPluginNames.has(key)) {
+      throw new Error(
+        `${ERROR_PREFIX} Preset "${name}" contains defaults for unknown plugin "${key}". This plugin is not present in the manifest.`
+      );
+    }
+    const value = defaults[key];
+    if (typeof value !== "function") {
+      throw new Error(
+        `${ERROR_PREFIX} Invalid default configuration for plugin "${key}" in preset "${name}". Expected a plugin options factory function, but received ${typeof value}.`
+      );
+    }
+  });
 }
 
-// src/utils/getActivePreset.ts
+// src/presets/getActivePreset.ts
 function getActivePreset(presets = {}, extraOptions) {
   const requestedPresetName = extraOptions?.preset?.trim();
   const activeName = requestedPresetName || DEFAULT_PRESET_NAME;
@@ -299,15 +313,6 @@ var withBaseMountOptions = (ctx) => {
   });
 };
 
-// src/guards/isPlainObject.ts
-function isPlainObject(item) {
-  if (item === null || typeof item !== "object" || Array.isArray(item)) {
-    return false;
-  }
-  const prototype = Object.getPrototypeOf(item);
-  return prototype === Object.prototype || prototype === null;
-}
-
 // src/utils/mergeConfigs.ts
 function mergeConfigs(target, source) {
   const arrays = Array.isArray(target) && Array.isArray(source);
@@ -384,12 +389,29 @@ var withPluginsManifest = (ctx) => {
   });
 };
 
+// src/presets/utils/buildPluginOptions.ts
+function buildPluginOptions(pluginName, factory) {
+  const options = factory();
+  if (!isPlainObject(options)) {
+    throw new Error(
+      `${ERROR_PREFIX} Plugin options factory for "${pluginName}" must return a plain object.`
+    );
+  }
+  return options;
+}
+
 // src/pipeline/middleware/transformers/withPreset.ts
 var withPreset = (ctx) => {
   const { preset } = ctx;
   if (!preset?.defaults) return ctx;
+  const pluginDefaultsState = Object.fromEntries(
+    Object.entries(preset.defaults).map(([pluginName, factory]) => [
+      pluginName,
+      buildPluginOptions(pluginName, factory)
+    ])
+  );
   return patchResultState(ctx, {
-    pluginDefaultsState: { ...preset.defaults }
+    pluginDefaultsState
   });
 };
 
@@ -593,8 +615,8 @@ function mountWithPlugins(component, ctx, overrides = {}, runtimeOptions = {
   });
 }
 
-// src/validators/validatePresets.ts
-function validatePresets(presets = {}) {
+// src/presets/validators/validatePresets.ts
+function validatePresets(presets) {
   if (!isPlainObject(presets)) {
     throw new Error(`${ERROR_PREFIX} Presets must be a plain object.`);
   }
@@ -603,8 +625,8 @@ function validatePresets(presets = {}) {
   });
 }
 
-// src/assertions/assertIsPlainObject.ts
-function assertIsPlainObject(value, name = "value") {
+// src/assertions/assertIsPlainObjectValue.ts
+function assertIsPlainObjectValue(value, name = "value") {
   if (!isPlainObject(value)) {
     throw new Error(`${name} must be a plain object.`);
   }
@@ -612,8 +634,14 @@ function assertIsPlainObject(value, name = "value") {
 
 // src/validators/validateCreateTestFrameworkOptions.ts
 function validateCreateTestFrameworkOptions(options = {}) {
-  assertIsPlainObject(options, "createTestFramework options");
-  const { shallowByDefault, presets } = options;
+  assertIsPlainObjectValue(options, "createTestFramework options");
+  const { preset, presets, shallowByDefault } = options;
+  if (preset !== void 0 && presets !== void 0) {
+    throw new Error(`${ERROR_PREFIX} "preset" and "presets" cannot be used together.`);
+  }
+  if (preset !== void 0) {
+    validatePreset("default", preset);
+  }
   if (presets !== void 0) {
     validatePresets(presets);
   }
@@ -716,10 +744,21 @@ function validateComponentFactoryArguments(props, mountOptions, slots, extraOpti
   validateComponentFactoryExtraOptions(extraOptions, presets);
 }
 
+// src/core/utils/resolvePresets.ts
+function resolvePresets(options) {
+  if (options.preset !== void 0) {
+    return {
+      default: options.preset
+    };
+  }
+  return options.presets ?? {};
+}
+
 // src/core/createTestFramework.ts
 function createTestFramework(options = {}) {
   validateCreateTestFrameworkOptions(options);
-  const { presets = {}, shallowByDefault = false } = options;
+  const { shallowByDefault = false } = options;
+  const presets = resolvePresets(options);
   const testComponentFactory = (component, defaultProps = {}, defaultMountOptions = {}, defaultSlots = {}) => {
     validateTestComponentFactoryArguments(
       component,
@@ -818,6 +857,95 @@ function captureInstance() {
   };
 }
 
+// src/presets/validators/validatePluginDefaults.ts
+function validatePluginDefaults(pluginName, value) {
+  if (typeof value !== "function") {
+    throw new Error(
+      `${ERROR_PREFIX} Invalid defaults for plugin "${pluginName}". Preset defaults must be provided as a plugin options factory function.`
+    );
+  }
+}
+
+// src/presets/validators/validatePresetExtension.ts
+function validatePresetExtension(basePreset, extension) {
+  if (!basePreset) {
+    throw new Error(`${ERROR_PREFIX} Cannot extend a null or undefined preset.`);
+  }
+  if (!extension) {
+    throw new Error(`${ERROR_PREFIX} Preset extension is null or undefined.`);
+  }
+  const basePluginNames = new Set(basePreset.manifest.map((entry) => entry.module.getName()));
+  const extensionManifest = extension.manifest ?? [];
+  const extensionManifestPlugins = /* @__PURE__ */ new Set();
+  for (const entry of extensionManifest) {
+    const pluginName = entry.module.getName();
+    if (extensionManifestPlugins.has(pluginName)) {
+      throw new Error(
+        `${ERROR_PREFIX} Duplicate plugin "${pluginName}" in preset extension manifest.`
+      );
+    }
+    extensionManifestPlugins.add(pluginName);
+    const isNewPlugin = !basePluginNames.has(pluginName);
+    if (isNewPlugin) {
+      if (entry.enabled === void 0) {
+        throw new Error(
+          `${ERROR_PREFIX} Cannot add plugin "${pluginName}" to an extended preset without specifying "enabled".`
+        );
+      }
+      const pluginDefaults = extension.defaults?.[pluginName];
+      if (pluginDefaults === void 0) {
+        throw new Error(
+          `${ERROR_PREFIX} Cannot add plugin "${pluginName}" to an extended preset without defining its defaults.`
+        );
+      }
+    }
+  }
+  if (extension.defaults) {
+    for (const [pluginName, pluginDefaults] of Object.entries(extension.defaults)) {
+      validatePluginDefaults(pluginName, pluginDefaults);
+      const isKnownPlugin = basePluginNames.has(pluginName) || extensionManifestPlugins.has(pluginName);
+      if (!isKnownPlugin) {
+        throw new Error(
+          `${ERROR_PREFIX} Cannot define defaults for unknown plugin "${pluginName}" in a preset extension. The plugin must be declared in the manifest.`
+        );
+      }
+    }
+  }
+}
+
+// src/presets/extendPreset.ts
+function extendPreset(basePreset, extension) {
+  validatePresetExtension(basePreset, extension);
+  const manifest = basePreset.manifest.map((entry) => ({ ...entry }));
+  const defaults = { ...basePreset.defaults };
+  const manifestByName = new Map(manifest.map((entry) => [entry.module.getName(), entry]));
+  const extensionManifest = extension.manifest ?? [];
+  for (const entry of extensionManifest) {
+    const pluginName = entry.module.getName();
+    const existingEntry = manifestByName.get(pluginName);
+    if (existingEntry) {
+      if (entry.enabled !== void 0) {
+        existingEntry.enabled = entry.enabled;
+      }
+    } else {
+      manifest.push({
+        module: entry.module,
+        enabled: entry.enabled
+      });
+      manifestByName.set(pluginName, manifest[manifest.length - 1]);
+    }
+  }
+  if (extension.defaults) {
+    for (const [pluginName, pluginDefaults] of Object.entries(extension.defaults)) {
+      defaults[pluginName] = pluginDefaults;
+    }
+  }
+  return {
+    manifest,
+    defaults
+  };
+}
+
 // src/index.ts
 var Types = {};
 export {
@@ -826,6 +954,7 @@ export {
   createPluginInstance,
   createTestFramework,
   createVuePlugin,
+  extendPreset,
   validatePreset,
   validatePresets
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testforgejs/vue-test-core",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "description": "Core testing utilities and pipeline orchestration for the TestForge component testing framework",
   "homepage": "https://github.com/testforgejs/testforge#readme",
@@ -51,10 +51,8 @@
     "vue": "^3.3.0"
   },
   "devDependencies": {
-    "vue-router": "^5.0.0",
-    "@testforgejs/vue-test-plugin-i18n": "1.0.0-beta.0",
-    "@testforgejs/vue-test-plugin-pinia": "1.0.0-beta.0",
-    "@testforgejs/vue-test-plugin-router": "1.0.0-beta.0"
+    "@vue/test-utils": "^2.0.0",
+    "vue": "^3.3.0"
   },
   "tsd": {
     "directory": "test-d"