@testforgejs/vue-test-preset-recommended 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -2,9 +2,42 @@
 
 Recommended **Vitest** presets for the [TestForge](https://github.com/testforgejs/testforge) Vue 3 component testing framework.
 
-This package builds on [`@testforgejs/vue-test-preset-base`](https://www.npmjs.com/package/@testforgejs/vue-test-preset-base) and provides recommended defaults for projects using **Vitest**.
+This package builds on [`@testforgejs/vue-test-preset-base`](https://www.npmjs.com/package/@testforgejs/vue-test-preset-base) and adds Vitest-specific configuration where required.
 
-The main difference from the base presets is the Pinia configuration: the recommended presets configure Pinia to use Vitest's `vi.fn` as its `createSpy` implementation.
+The primary difference from the base presets is the Pinia configuration:
+
+```typescript
+piniaPlugin.getDefaultOptions(vi);
+```
+
+This allows the Pinia plugin to use Vitest's `vi.fn` as the `createSpy` implementation required by `@pinia/testing` when an explicit runner is provided.
+
+Vue I18n and Vue Router do not require Vitest-specific configuration, so their presets are inherited directly from the base package.
+
+Conceptually:
+
+```text
+plugin
+→ owns reusable integration knowledge
+
+base preset
+→ consumes runner-independent plugin defaults
+→ composes plugins without choosing a test runner
+
+recommended preset
+→ consumes runner-aware plugin defaults
+→ adds Vitest-specific runner integration
+
+project-owned preset
+→ materializes concrete plugin configuration
+→ owns application-specific policy
+```
+
+The distinction between the recommended preset and a project-owned preset is intentional.
+
+The TestForge-maintained recommended preset may use `getDefaultOptions()` because it deliberately follows the integration baseline exported by the installed plugin version.
+
+A project-owned preset should normally materialize the concrete configuration it wants to preserve in its own source code.
 
 ## Installation
 
@@ -32,7 +65,7 @@ yarn add -D @testforgejs/vue-test-preset-recommended@beta
 
 ## Quick Usage
 
-Import the `presets` object and pass it to `createTestFramework()`:
+For a single runtime environment, pass the recommended default preset through `preset`:
 
 ```typescript
 // tests/setup.ts
@@ -41,16 +74,17 @@ import { createTestFramework } from "@testforgejs/vue-test-core";
 import { presets } from "@testforgejs/vue-test-preset-recommended";
 
 const { testComponentFactory } = createTestFramework({
-  presets,
+  preset: presets.default,
 });
 
 export { testComponentFactory };
 ```
 
-You can then use `testComponentFactory` in your component tests:
+You can then use `testComponentFactory` in component tests:
 
 ```typescript
 import { describe, expect, it } from "vitest";
+
 import { testComponentFactory } from "./setup";
 import MyComponent from "./MyComponent.vue";
 
@@ -64,6 +98,50 @@ describe("MyComponent", () => {
 });
 ```
 
+## Single vs. Multiple Presets
+
+`createTestFramework()` supports two mutually exclusive preset configuration forms.
+
+Use `preset` when the framework needs a single runtime environment:
+
+```typescript
+const { testComponentFactory } = createTestFramework({
+  preset: presets.default,
+});
+```
+
+A single preset is treated as the framework's default runtime environment.
+
+Use `presets` when the framework should expose multiple named runtime environments:
+
+```typescript
+const { testComponentFactory } = createTestFramework({
+  presets,
+});
+```
+
+The exported registry contains:
+
+```text
+default
+piniaPreset
+i18nPreset
+routerPreset
+```
+
+Named presets registered through `presets` can be selected for individual component factory invocations through `extraOptions.preset`.
+
+In general:
+
+```text
+preset
+→ one runtime environment
+
+presets
+→ multiple named runtime environments
+→ runtime selection through extraOptions.preset
+```
+
 ## Available Presets
 
 The package exports four presets:
@@ -73,136 +151,271 @@ The package exports four presets:
 - `presets.i18nPreset`
 - `presets.routerPreset`
 
-The presets are based on the corresponding presets from `@testforgejs/vue-test-preset-base`.
+They are built from the corresponding presets exported by `@testforgejs/vue-test-preset-base`.
+
+The current composition is equivalent to:
+
+```typescript
+import { vi } from "vitest";
+
+import { extendPreset } from "@testforgejs/vue-test-core";
+import { presets as basePresets } from "@testforgejs/vue-test-preset-base";
+import { piniaPlugin, PLUGIN_NAME as PINIA_PLUGIN_NAME } from "@testforgejs/vue-test-plugin-pinia";
+
+export const presets = {
+  default: extendPreset(basePresets.default, {
+    defaults: {
+      [PINIA_PLUGIN_NAME]: piniaPlugin.getDefaultOptions(vi),
+    },
+  }),
+
+  piniaPreset: extendPreset(basePresets.piniaPreset, {
+    defaults: {
+      [PINIA_PLUGIN_NAME]: piniaPlugin.getDefaultOptions(vi),
+    },
+  }),
+
+  i18nPreset: basePresets.i18nPreset,
+  routerPreset: basePresets.routerPreset,
+};
+```
+
+Preset definitions use the standardized `PLUGIN_NAME` export as the configuration key instead of repeating plugin name literals.
+
+This keeps the identifier exported by the plugin package as the single source of truth.
+
+Because this package is a TestForge-maintained reusable preset, it intentionally obtains its runner-aware Pinia baseline through `getDefaultOptions(vi)`.
+
+When only one of these environments is needed, use it directly through `createTestFramework({ preset })`.
 
 ### `presets.default`
 
-The default recommended preset enables:
+The default recommended preset contains:
+
+- Pinia — enabled;
+- Vue I18n — enabled;
+- Vue Router — declared but disabled.
+
+It inherits the plugin composition from `presets.default` in the base package.
 
-- Pinia;
-- Vue I18n;
-- Vue Router — disabled by default.
+The Pinia defaults are replaced with the runner-aware defaults provided by the Pinia plugin:
 
-It also provides default option factories for these managed plugins.
+```typescript
+piniaPlugin.getDefaultOptions(vi);
+```
 
-For Pinia, the recommended preset additionally configures Vitest's `vi.fn` as the `createSpy` implementation.
+The resulting Pinia options are currently equivalent to:
+
+```typescript
+{
+  createSpy: vi.fn,
+}
+```
+
+TestForge does not override other `@pinia/testing` behavior.
+
+In particular, actions follow the upstream `createTestingPinia()` behavior and are stubbed by default unless a project explicitly configures:
+
+```typescript
+stubActions: false;
+```
+
+Vue I18n and Vue Router continue to use the defaults selected by the base preset.
 
 ```typescript
 const { testComponentFactory } = createTestFramework({
-  presets: {
-    default: presets.default,
-  },
+  preset: presets.default,
 });
 ```
 
-This is the preset intended for most Vitest-based TestForge projects.
+This is the general-purpose preset intended for Vitest-based TestForge projects.
 
 ### `presets.piniaPreset`
 
-A minimal preset for tests that require Pinia.
-
-It enables Pinia and configures its spy factory to use Vitest:
+A minimal preset containing only Pinia.
 
 ```typescript
 const { testComponentFactory } = createTestFramework({
-  presets: {
-    default: presets.piniaPreset,
-  },
+  preset: presets.piniaPreset,
 });
 ```
 
-The Pinia option factory is based on the base preset and adds Vitest's `vi.fn`:
+The preset is based on `basePresets.piniaPreset`, but replaces its runner-neutral Pinia defaults with:
 
 ```typescript
-pinia: () => ({
-  ...basePiniaOptions,
-  createSpy: vi.fn,
-});
+piniaPlugin.getDefaultOptions(vi);
 ```
 
-This makes the preset immediately usable with `@pinia/testing` under Vitest.
+This provides the Vitest spy implementation explicitly rather than relying on test-runner globals.
 
-### `presets.i18nPreset`
+The current Pinia defaults are equivalent to:
 
-A minimal preset for tests that require Vue I18n.
+```typescript
+{
+  createSpy: vi.fn,
+}
+```
 
-It enables Vue I18n using the base preset's default configuration:
+Other Pinia testing behavior remains controlled by `@pinia/testing` unless the project overrides it.
 
-- Composition API mode (`legacy: false`);
-- English locale;
-- English fallback locale;
-- empty messages;
-- disabled missing-translation warnings.
+### `presets.i18nPreset`
 
-The plugin defaults are provided through a plugin options factory, so each pipeline context receives fresh plugin options.
+A minimal preset containing only Vue I18n.
 
 ```typescript
 const { testComponentFactory } = createTestFramework({
-  presets: {
-    default: presets.i18nPreset,
-  },
+  preset: presets.i18nPreset,
 });
 ```
 
-### `presets.routerPreset`
+This preset is inherited directly from `@testforgejs/vue-test-preset-base` because Vue I18n does not require Vitest-specific configuration.
+
+The plugin defaults selected by the base preset are currently equivalent to:
+
+```typescript
+{
+  legacy: false,
+  globalInjection: true,
+}
+```
+
+These options provide a project-independent Vue 3 integration baseline.
+
+The preset intentionally does not choose:
 
-A minimal preset for tests that require Vue Router.
+- an application locale;
+- a fallback locale;
+- translation messages;
+- formatting configuration;
+- missing-translation or fallback warning policy.
 
-It enables the managed Vue Router integration using the base preset's default router configuration.
+Those settings belong in project-specific configuration.
+
+### `presets.routerPreset`
+
+A minimal preset containing only Vue Router.
 
 ```typescript
 const { testComponentFactory } = createTestFramework({
-  presets: {
-    default: presets.routerPreset,
-  },
+  preset: presets.routerPreset,
 });
 ```
 
-The router preset provides a test-oriented router configuration suitable for isolated component tests.
+This preset is inherited directly from `@testforgejs/vue-test-preset-base`.
 
-Its plugin defaults are provided through a plugin options factory, which produces fresh options for each pipeline context.
+The Router defaults selected by the base preset are currently equivalent to:
 
-## Recommended vs Base Presets
+```typescript
+{
+  history: createMemoryHistory(),
+  routes: [],
+}
+```
+
+The in-memory history keeps routing isolated from browser URL state.
 
-`@testforgejs/vue-test-preset-base` provides framework-neutral preset definitions.
+The empty route table ensures that TestForge does not invent application-specific routes.
 
-`@testforgejs/vue-test-preset-recommended` builds on those presets and adds Vitest-specific configuration where necessary.
+Projects that need actual routes or another history implementation should provide them explicitly in a project-owned preset.
+
+## Recommended vs Base Presets
 
-In particular:
+`@testforgejs/vue-test-preset-base` provides runner-independent preset definitions.
+
+`@testforgejs/vue-test-preset-recommended` adds Vitest-specific configuration only where it is required.
 
 ```text
 @testforgejs/vue-test-preset-base
-        │
-        ├── default
-        ├── piniaPreset
-        ├── i18nPreset
-        └── routerPreset
-                │
-                ▼
+       │
+       ├── default
+       │      └── Pinia defaults without a runner
+       │
+       ├── piniaPreset
+       │      └── Pinia defaults without a runner
+       │
+       ├── i18nPreset
+       │
+       └── routerPreset
+              │
+              ▼
 @testforgejs/vue-test-preset-recommended
-        │
-        ├── default       → adds Vitest vi.fn to Pinia
-        ├── piniaPreset   → adds Vitest vi.fn to Pinia
-        ├── i18nPreset    → inherited from base
-        └── routerPreset  → inherited from base
+       │
+       ├── default
+       │      └── piniaPlugin.getDefaultOptions(vi)
+       │
+       ├── piniaPreset
+       │      └── piniaPlugin.getDefaultOptions(vi)
+       │
+       ├── i18nPreset
+       │      └── inherited unchanged
+       │
+       └── routerPreset
+              └── inherited unchanged
 ```
 
-This separation keeps the base preset independent from a particular test runner while allowing the recommended preset to provide runner-specific defaults.
+This separation keeps runner knowledge out of the base preset.
+
+It also keeps knowledge about how Vitest integrates with Pinia inside the Pinia plugin rather than duplicating that configuration in the TestForge-maintained preset package.
 
-The Vitest-specific Pinia defaults are implemented as a **plugin options factory**. The factory invokes the base Pinia options factory and adds `createSpy`:
+In other words:
+
+```text
+recommended preset
+→ knows that the runner is Vitest
+
+Pinia plugin
+→ knows how Vitest runner support maps to Pinia configuration
+```
+
+## Plugin Defaults Are Explicit
+
+Plugin defaults are not automatically applied simply because a plugin appears in a preset manifest.
+
+For example:
 
 ```typescript
-const defaultVitestPinia = (() => ({
-  ...defaultPinia(),
-  createSpy: vi.fn,
-})) satisfies PluginOptionsFactory<VueTestPiniaOptions>;
+manifest: [
+  {
+    module: piniaPlugin,
+    enabled: true,
+  },
+];
+```
+
+does not implicitly call:
+
+```typescript
+piniaPlugin.getDefaultOptions(vi);
 ```
 
-The resulting factory can be reused by both the `default` and `piniaPreset` profiles.
+The recommended preset explicitly selects the runner-aware Pinia defaults using the identifier exported by the plugin package:
+
+```typescript
+defaults: {
+  [PINIA_PLUGIN_NAME]: piniaPlugin.getDefaultOptions(vi),
+}
+```
+
+The `PLUGIN_NAME` export identifies the plugin consistently across its module and preset configuration, while `getDefaultOptions()` provides the configuration factory selected by this TestForge-maintained preset.
+
+Because the recommended preset deliberately references `getDefaultOptions(vi)`, it intentionally follows the runner-aware integration baseline provided by the installed Pinia plugin version.
+
+Project-owned presets that need their concrete configuration to remain visible and stable across plugin baseline changes should materialize that configuration explicitly instead.
 
 ## Switching Presets at Runtime
 
-A **component factory invocation** can select a different registered preset using the fourth `extraOptions` argument:
+Use the preset registry when the same TestForge framework instance should expose multiple named runtime environments:
+
+```typescript
+import { createTestFramework } from "@testforgejs/vue-test-core";
+import { presets } from "@testforgejs/vue-test-preset-recommended";
+
+const { testComponentFactory } = createTestFramework({
+  presets,
+});
+```
+
+A component factory invocation can then select another registered preset using the fourth `extraOptions` argument:
 
 ```typescript
 const factory = testComponentFactory(MyComponent);
@@ -217,9 +430,7 @@ factory(
 );
 ```
 
-The selected preset defines the complete managed plugin runtime for that component factory invocation.
-
-This allows the same TestForge framework instance to use different runtime environments without creating a separate framework instance.
+The selected preset defines the complete managed-plugin runtime for that invocation.
 
 For example:
 
@@ -234,64 +445,380 @@ factory(
 );
 ```
 
-selects the Pinia-only runtime environment for that invocation.
+selects the Pinia-only runtime environment.
+
+This allows a single TestForge framework instance to expose several predefined runtime profiles.
+
+The similarly named options operate at different levels:
+
+```text
+createTestFramework({ preset })
+→ configures one framework-wide runtime environment
+
+createTestFramework({ presets })
+→ registers multiple named runtime environments
+
+extraOptions.preset
+→ selects one registered runtime environment for a factory invocation
+```
+
+Runtime selection through `extraOptions.preset` applies to named presets registered through `presets`.
 
 ## Customizing Presets
 
-The recommended presets are ordinary TestForge preset definitions and can be composed with [`extendPreset()`](https://github.com/testforgejs/testforge).
+The recommended presets are ordinary TestForge preset definitions and can be composed with `extendPreset()`.
+
+Application-specific behavior should normally be added in a project-owned preset rather than in TestForge plugin defaults.
+
+When a project replaces a plugin factory, it should normally materialize the concrete configuration it wants to own rather than call `getDefaultOptions()` again.
+
+This keeps the project's effective test environment visible in source and prevents future changes to a plugin baseline from silently changing that materialized configuration.
+
+### Customizing Pinia
 
-For example, a project can create its own preset from the recommended default:
+For example, a project may want real Pinia actions to execute instead of using the upstream testing default that stubs them.
+
+A project-owned preset can materialize both the required Vitest integration and the project-specific action policy:
 
 ```typescript
+import { vi } from "vitest";
+
 import { extendPreset } from "@testforgejs/vue-test-core";
+import { PLUGIN_NAME as PINIA_PLUGIN_NAME } from "@testforgejs/vue-test-plugin-pinia";
+import { presets as recommendedPresets } from "@testforgejs/vue-test-preset-recommended";
+
+const projectPreset = extendPreset(recommendedPresets.default, {
+  defaults: {
+    [PINIA_PLUGIN_NAME]: () => ({
+      createSpy: vi.fn,
+      stubActions: false,
+    }),
+  },
+});
+```
+
+This produces:
+
+```typescript
+{
+  createSpy: vi.fn,
+  stubActions: false,
+}
+```
+
+The recommended preset obtains `createSpy: vi.fn` through the Pinia plugin's runner-aware defaults.
+
+The project-owned preset materializes that value in its own source together with its `stubActions: false` policy.
+
+Conceptually:
+
+```text
+recommended preset
+→ follows runner-aware plugin baseline
+
+project-owned preset
+→ materializes createSpy: vi.fn
+→ adds stubActions: false
+→ owns the resulting configuration
+```
 
+A project using this single runtime environment can pass it directly to TestForge:
+
+```typescript
+const { testComponentFactory } = createTestFramework({
+  preset: projectPreset,
+});
+```
+
+### Customizing Vue I18n
+
+Application locale and translation messages should be configured explicitly.
+
+A project-owned preset should also materialize the integration values it intends to preserve:
+
+```typescript
+import { extendPreset } from "@testforgejs/vue-test-core";
+import { PLUGIN_NAME as I18N_PLUGIN_NAME } from "@testforgejs/vue-test-plugin-i18n";
 import { presets as recommendedPresets } from "@testforgejs/vue-test-preset-recommended";
 
-const projectPresets = {
-  default: extendPreset(recommendedPresets.default, {
-    defaults: {
-      pinia: () => ({
-        ...recommendedPresets.default.defaults.pinia(),
-        // project-specific options
-      }),
-    },
-  }),
-};
+const projectPreset = extendPreset(recommendedPresets.default, {
+  defaults: {
+    [I18N_PLUGIN_NAME]: () => ({
+      legacy: false,
+      globalInjection: true,
+
+      locale: "en",
+      messages: {
+        en: {
+          hello: "Hello",
+        },
+      },
+    }),
+  },
+});
 ```
 
-Because `defaults.pinia` is a plugin options factory, the base Pinia options are obtained by invoking the factory.
+Here:
 
-When extending a preset, explicitly preserve any base plugin options that should remain enabled. Managed plugin configuration is intentionally replaced when an extension provides configuration for that plugin.
+```text
+legacy / globalInjection
+→ materialized integration baseline
 
-For details about preset composition and configuration layering, see the [TestForge core documentation](https://github.com/testforgejs/testforge/blob/main/packages/vue-test-core/README.md).
+locale / messages
+→ project-specific policy
+```
 
-## Using a Preset with Other Framework Configuration
+All of these values are now visible and owned by the project preset.
 
-The exported presets can be combined with other TestForge configuration options:
+Use it directly when no runtime preset switching is needed:
 
 ```typescript
 const { testComponentFactory } = createTestFramework({
-  presets,
-  shallowByDefault: true,
+  preset: projectPreset,
+});
+```
+
+### Customizing Vue Router
+
+Application routes should also be configured explicitly.
+
+The recommended default preset declares Router but keeps it disabled, so a project that wants Router as part of its default runtime should explicitly enable it and materialize its Router configuration:
+
+```typescript
+import { createMemoryHistory } from "vue-router";
+import { extendPreset } from "@testforgejs/vue-test-core";
+import {
+  routerPlugin,
+  PLUGIN_NAME as ROUTER_PLUGIN_NAME,
+} from "@testforgejs/vue-test-plugin-router";
+import { presets as recommendedPresets } from "@testforgejs/vue-test-preset-recommended";
+
+const projectPreset = extendPreset(recommendedPresets.default, {
+  manifest: [
+    {
+      module: routerPlugin,
+      enabled: true,
+    },
+  ],
+
+  defaults: {
+    [ROUTER_PLUGIN_NAME]: () => ({
+      history: createMemoryHistory(),
+
+      routes: [
+        {
+          path: "/",
+          component: HomeView,
+        },
+      ],
+    }),
+  },
+});
+```
+
+The project now owns both decisions:
+
+```text
+manifest
+→ Router is enabled
+
+defaults
+→ createMemoryHistory()
+→ application routes
+```
+
+The in-memory history is explicit project-owned configuration rather than an indirect dependency on `routerPlugin.getDefaultOptions()`.
+
+If the application requires another history implementation, replace it directly:
+
+```typescript
+import { createWebHistory } from "vue-router";
+
+const projectPreset = extendPreset(recommendedPresets.default, {
+  manifest: [
+    {
+      module: routerPlugin,
+      enabled: true,
+    },
+  ],
+
+  defaults: {
+    [ROUTER_PLUGIN_NAME]: () => ({
+      history: createWebHistory(),
+      routes,
+    }),
+  },
 });
 ```
 
-The preset provides the runtime plugin baseline, while individual component factory invocations and tests can override configuration when needed.
+## Replacing Preset Defaults
+
+When an extension provides a plugin options factory, that factory replaces the corresponding factory from the source preset.
+
+For example:
+
+```typescript
+extendPreset(recommendedPresets.default, {
+  defaults: {
+    [PINIA_PLUGIN_NAME]: () => ({
+      createSpy: vi.fn,
+      stubActions: false,
+    }),
+  },
+});
+```
+
+TestForge does not implicitly merge this factory with:
+
+```typescript
+piniaPlugin.getDefaultOptions(vi);
+```
+
+or with the factory already present in `recommendedPresets.default`.
+
+For a project-owned preset, explicit replacement is normally preferable because the effective configuration is visible in project source:
+
+```typescript
+[PINIA_PLUGIN_NAME]: () => ({
+  createSpy: vi.fn,
+  stubActions: false,
+})
+```
+
+A project can instead deliberately preserve and spread the source preset factory:
+
+```typescript
+const sourcePinia = recommendedPresets.default.defaults.pinia;
+
+const projectPreset = extendPreset(recommendedPresets.default, {
+  defaults: {
+    [PINIA_PLUGIN_NAME]: () => ({
+      ...sourcePinia(),
+      stubActions: false,
+    }),
+  },
+});
+```
+
+This has different semantics.
+
+The project now intentionally continues to depend on the Pinia factory provided by `recommendedPresets.default`.
+
+If that source factory changes after a dependency update, the effective project configuration can change as well.
+
+Conceptually:
+
+```text
+spread source preset factory
+→ continue following source preset behavior
+
+explicit replacement factory
+→ project owns the resulting configuration
+```
+
+For a stable project-owned preset, prefer explicit materialization:
+
+```typescript
+const projectPreset = extendPreset(recommendedPresets.default, {
+  defaults: {
+    [PINIA_PLUGIN_NAME]: () => ({
+      createSpy: vi.fn,
+      stubActions: false,
+    }),
+  },
+});
+```
 
 ## Plugin Options Factory Isolation
 
-The `defaults` values in the presets are **plugin options factories**, not shared plugin configuration objects.
+Preset `defaults` values are plugin options factories rather than shared configuration objects.
+
+The recommended preset stores its Pinia options factory under the exported plugin identifier:
+
+```typescript
+defaults: {
+  [PINIA_PLUGIN_NAME]: piniaPlugin.getDefaultOptions(vi),
+}
+```
+
+Because `PINIA_PLUGIN_NAME` resolves to `"pinia"`, the resolved preset can still be consumed through its normal property key.
+
+Each invocation produces a fresh options object for the current pipeline context:
+
+```typescript
+const first = presets.default.defaults.pinia();
+const second = presets.default.defaults.pinia();
 
-When a plugin options factory is invoked, it produces fresh plugin options for the current pipeline context.
+first !== second; // true
+```
+
+Runner-independent presets preserve the same factory-based isolation.
+
+For Router, the options factory also creates a fresh in-memory history instance for each invocation:
+
+```typescript
+const first = presets.routerPreset.defaults.router();
+const second = presets.routerPreset.defaults.router();
+
+first.history !== second.history; // true
+```
+
+This avoids unintentionally sharing mutable plugin configuration or runtime state between independent pipeline contexts.
+
+A plugin options factory and a component factory operate at different levels:
+
+```text
+plugin options factory
+→ creates plugin configuration
+
+testComponentFactory()
+→ creates a reusable component mounting factory
+
+component factory invocation
+→ creates an individual component test runtime
+```
+
+The `getDefaultOptions(vi)` example in this section describes the implementation of the TestForge-maintained recommended preset.
+
+A project-owned preset can preserve the same factory isolation while materializing its configuration explicitly:
+
+```typescript
+defaults: {
+  [PINIA_PLUGIN_NAME]: () => ({
+    createSpy: vi.fn,
+  }),
+}
+```
+
+## Using a Preset with Other Framework Configuration
+
+When using a single runtime environment, combine it with other framework options through `preset`:
+
+```typescript
+const { testComponentFactory } = createTestFramework({
+  preset: presets.default,
+  shallowByDefault: true,
+});
+```
+
+When multiple named environments are required, use the registry form instead:
+
+```typescript
+const { testComponentFactory } = createTestFramework({
+  presets,
+  shallowByDefault: true,
+});
+```
 
-This keeps mutable configuration isolated between independent pipeline contexts.
+The selected preset provides the managed-plugin runtime baseline.
 
-This is separate from component factory isolation: `testComponentFactory()` creates a reusable function for mounting a component, while each invocation of that component factory establishes its own runtime environment.
+A project-owned preset can materialize and replace that configuration explicitly, while individual component tests can apply local overrides where needed.
 
 ## Related Packages
 
 - [`@testforgejs/vue-test-core`](https://www.npmjs.com/package/@testforgejs/vue-test-core) — TestForge core framework
-- [`@testforgejs/vue-test-preset-base`](https://www.npmjs.com/package/@testforgejs/vue-test-preset-base) — base, runner-neutral presets
+- [`@testforgejs/vue-test-preset-base`](https://www.npmjs.com/package/@testforgejs/vue-test-preset-base) — base runner-independent presets
+- [`@testforgejs/vue-test-preset-recommended-jest`](https://www.npmjs.com/package/@testforgejs/vue-test-preset-recommended-jest) — Jest-specific recommended presets
 - [`@testforgejs/vue-test-plugin-pinia`](https://www.npmjs.com/package/@testforgejs/vue-test-plugin-pinia) — Pinia integration
 - [`@testforgejs/vue-test-plugin-i18n`](https://www.npmjs.com/package/@testforgejs/vue-test-plugin-i18n) — Vue I18n integration
 - [`@testforgejs/vue-test-plugin-router`](https://www.npmjs.com/package/@testforgejs/vue-test-plugin-router) — Vue Router integration

package/dist/index.cjs

@@ -27,20 +27,17 @@ module.exports = __toCommonJS(index_exports);
 // src/presets.ts
 var import_vue_test_core = require("@testforgejs/vue-test-core");
 var import_vue_test_preset_base = require("@testforgejs/vue-test-preset-base");
+var import_vue_test_plugin_pinia = require("@testforgejs/vue-test-plugin-pinia");
 var import_vitest = require("vitest");
-var defaultVitestPinia = (() => ({
-  ...(0, import_vue_test_preset_base.defaultPinia)(),
-  createSpy: import_vitest.vi.fn
-}));
 var presets = {
   default: (0, import_vue_test_core.extendPreset)(import_vue_test_preset_base.presets.default, {
     defaults: {
-      pinia: defaultVitestPinia
+      [import_vue_test_plugin_pinia.PLUGIN_NAME]: import_vue_test_plugin_pinia.piniaPlugin.getDefaultOptions(import_vitest.vi)
     }
   }),
   piniaPreset: (0, import_vue_test_core.extendPreset)(import_vue_test_preset_base.presets.piniaPreset, {
     defaults: {
-      pinia: defaultVitestPinia
+      [import_vue_test_plugin_pinia.PLUGIN_NAME]: import_vue_test_plugin_pinia.piniaPlugin.getDefaultOptions(import_vitest.vi)
     }
   }),
   i18nPreset: import_vue_test_preset_base.presets.i18nPreset,

package/dist/index.d.cts

@@ -3,27 +3,26 @@ import * as vue_router from 'vue-router';
 import * as _testforgejs_vue_test_plugin_i18n from '@testforgejs/vue-test-plugin-i18n';
 import * as vue_i18n from 'vue-i18n';
 import * as _testforgejs_vue_test_core from '@testforgejs/vue-test-core';
-import { PluginOptionsFactory } from '@testforgejs/vue-test-core';
 
 declare const presets: {
     default: _testforgejs_vue_test_core.PresetDefinition;
     piniaPreset: _testforgejs_vue_test_core.PresetDefinition;
     i18nPreset: {
         manifest: {
-            module: _testforgejs_vue_test_core.PluginModule<vue_i18n.I18n<{}, {}, {}, string, boolean>, _testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
+            module: _testforgejs_vue_test_core.PluginModuleWithDefaults<vue_i18n.I18n<{}, {}, {}, string, boolean>, _testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
             enabled: true;
         }[];
         defaults: {
-            i18n: PluginOptionsFactory<_testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
+            i18n: _testforgejs_vue_test_core.PluginOptionsFactory<_testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
         };
     };
     routerPreset: {
         manifest: {
-            module: _testforgejs_vue_test_core.PluginModule<vue_router._RouterClassic, _testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
+            module: _testforgejs_vue_test_core.PluginModuleWithDefaults<vue_router._RouterClassic, _testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
             enabled: true;
         }[];
         defaults: {
-            router: PluginOptionsFactory<_testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
+            router: _testforgejs_vue_test_core.PluginOptionsFactory<_testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
         };
     };
 };

package/dist/index.d.ts

@@ -3,27 +3,26 @@ import * as vue_router from 'vue-router';
 import * as _testforgejs_vue_test_plugin_i18n from '@testforgejs/vue-test-plugin-i18n';
 import * as vue_i18n from 'vue-i18n';
 import * as _testforgejs_vue_test_core from '@testforgejs/vue-test-core';
-import { PluginOptionsFactory } from '@testforgejs/vue-test-core';
 
 declare const presets: {
     default: _testforgejs_vue_test_core.PresetDefinition;
     piniaPreset: _testforgejs_vue_test_core.PresetDefinition;
     i18nPreset: {
         manifest: {
-            module: _testforgejs_vue_test_core.PluginModule<vue_i18n.I18n<{}, {}, {}, string, boolean>, _testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
+            module: _testforgejs_vue_test_core.PluginModuleWithDefaults<vue_i18n.I18n<{}, {}, {}, string, boolean>, _testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
             enabled: true;
         }[];
         defaults: {
-            i18n: PluginOptionsFactory<_testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
+            i18n: _testforgejs_vue_test_core.PluginOptionsFactory<_testforgejs_vue_test_plugin_i18n.VueTestI18nOptions>;
         };
     };
     routerPreset: {
         manifest: {
-            module: _testforgejs_vue_test_core.PluginModule<vue_router._RouterClassic, _testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
+            module: _testforgejs_vue_test_core.PluginModuleWithDefaults<vue_router._RouterClassic, _testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
             enabled: true;
         }[];
         defaults: {
-            router: PluginOptionsFactory<_testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
+            router: _testforgejs_vue_test_core.PluginOptionsFactory<_testforgejs_vue_test_plugin_router.VueTestRouterOptions>;
         };
     };
 };

package/dist/index.js

@@ -1,20 +1,17 @@
 // src/presets.ts
 import { extendPreset } from "@testforgejs/vue-test-core";
-import { defaultPinia, presets as basePresets } from "@testforgejs/vue-test-preset-base";
+import { presets as basePresets } from "@testforgejs/vue-test-preset-base";
+import { piniaPlugin, PLUGIN_NAME as PINIA_PLUGIN_NAME } from "@testforgejs/vue-test-plugin-pinia";
 import { vi } from "vitest";
-var defaultVitestPinia = (() => ({
-  ...defaultPinia(),
-  createSpy: vi.fn
-}));
 var presets = {
   default: extendPreset(basePresets.default, {
     defaults: {
-      pinia: defaultVitestPinia
+      [PINIA_PLUGIN_NAME]: piniaPlugin.getDefaultOptions(vi)
     }
   }),
   piniaPreset: extendPreset(basePresets.piniaPreset, {
     defaults: {
-      pinia: defaultVitestPinia
+      [PINIA_PLUGIN_NAME]: piniaPlugin.getDefaultOptions(vi)
     }
   }),
   i18nPreset: basePresets.i18nPreset,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testforgejs/vue-test-preset-recommended",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "type": "module",
   "description": "Official recommended preset for getting started with the TestForge framework",
   "homepage": "https://github.com/testforgejs/testforge#readme",
@@ -44,19 +44,19 @@
   "license": "MIT",
   "author": "Roman Levchenko",
   "dependencies": {
-    "@testforgejs/vue-test-plugin-i18n": "1.0.0-beta.1",
-    "@testforgejs/vue-test-plugin-pinia": "1.0.0-beta.1",
-    "@testforgejs/vue-test-plugin-router": "1.0.0-beta.1"
+    "@testforgejs/vue-test-plugin-i18n": "1.0.0-beta.3",
+    "@testforgejs/vue-test-plugin-router": "1.0.0-beta.3",
+    "@testforgejs/vue-test-plugin-pinia": "1.0.0-beta.3"
   },
   "peerDependencies": {
     "vitest": "^3.0.0 || ^4.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.1",
-    "@testforgejs/vue-test-preset-base": "1.0.0-beta.1"
+    "@testforgejs/vue-test-core": "1.0.0-beta.3",
+    "@testforgejs/vue-test-preset-base": "1.0.0-beta.3"
   },
   "devDependencies": {
     "vitest": "^3.0.0 || ^4.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.1",
-    "@testforgejs/vue-test-preset-base": "1.0.0-beta.1"
+    "@testforgejs/vue-test-core": "1.0.0-beta.3",
+    "@testforgejs/vue-test-preset-base": "1.0.0-beta.3"
   },
   "scripts": {
     "build": "tsup",