@testforgejs/vue-test-plugin-pinia 1.0.0-beta.6 → 1.0.0-beta.7

package/README.md

@@ -36,7 +36,6 @@ When using Vitest, you can pass `vi` as the runner:
 
 ```typescript
 import { vi } from "vitest";
-
 import { createTestFramework } from "@testforgejs/vue-test-core";
 import { piniaPlugin } from "@testforgejs/vue-test-plugin-pinia";
 
@@ -95,7 +94,6 @@ You can define the Pinia testing configuration directly in the preset instead:
 
 ```typescript
 import { vi } from "vitest";
-
 import { createTestFramework } from "@testforgejs/vue-test-core";
 import { piniaPlugin } from "@testforgejs/vue-test-plugin-pinia";
 
@@ -148,6 +146,90 @@ TestForge does not redefine these Pinia testing options. The integration passes
 
 Refer to the Pinia documentation for the complete set of `TestingOptions` and their behavior.
 
+For additional store initialization and modification before mounting, see [Configuring stores with `withMockStores()`](#configuring-stores-with-withmockstores).
+
+### Configuring stores with `withMockStores()`
+
+The TestForge Pinia plugin provides the `withMockStores()` helper for configuring stores before a component is mounted. It accepts a callback that receives the testing Pinia instance used by the mounted component.
+
+Unlike the native `initialState` option, which initializes store state, `withMockStores()` lets you access stores directly and perform additional setup, including calling store actions.
+
+```typescript
+import { withMockStores } from "@testforgejs/vue-test-plugin-pinia";
+
+factory(
+  {},
+  {
+    plugins: {
+      pinia: {
+        stubActions: false,
+        ...withMockStores((pinia) => {
+          const store = useCounterStore(pinia);
+          store.setCount(42);
+        }),
+      },
+    },
+  },
+);
+```
+
+The callback runs after the Pinia instance has been resolved and before the component is mounted. This applies to newly created instances and explicitly reused instances alike.
+
+When calling store actions inside `withMockStores()`, configure `stubActions: false` if their implementations need to execute. By default, `createTestingPinia()` stubs store actions.
+
+The configuration returned by `withMockStores()` can be used in per-mount plugin options or factory-level defaults. The callback is invoked for each mount that uses the configuration and receives that mount's resolved Pinia instance.
+
+#### Configuring an existing Pinia instance
+
+The `withMockStores()` callback also runs when an existing Pinia instance is supplied using `withPluginInstance()`. This allows you to configure stores on an explicitly reused instance without creating a new Pinia instance.
+
+```typescript
+import { createTestingPinia } from "@pinia/testing";
+import { vi } from "vitest";
+import { withPluginInstance } from "@testforgejs/vue-test-core";
+import { withMockStores } from "@testforgejs/vue-test-plugin-pinia";
+
+const pinia = createTestingPinia({
+  createSpy: vi.fn,
+  stubActions: false,
+});
+
+factory(
+  {},
+  {},
+  {},
+  {
+    plugins: {
+      pinia: {
+        ...withPluginInstance(pinia),
+        ...withMockStores((pinia) => {
+          const store = useCounterStore(pinia);
+          store.count = 42;
+        }),
+      },
+    },
+  },
+);
+```
+
+In this example:
+
+- TestForge reuses the supplied Pinia instance instead of creating a new one.
+- The `withMockStores()` callback receives that same instance.
+- The callback modifies the store before the component is mounted.
+
+Native `createTestingPinia()` options should be configured when creating the instance. Using `withPluginInstance()` reuses that instance rather than recreating it with new testing options.
+
+#### Shared instance isolation
+
+**Using `withPluginInstance()` explicitly enables instance reuse.** When the same instance is reused across multiple mounts, the mounted components share its stores and reactive state. State changes made during one mount may affect other components using that instance.
+
+The `withMockStores()` callback runs for **each mount** that configures it and operates on the resolved instance. When that instance is shared, the callback can modify stores that were initialized during an earlier mount. TestForge does not automatically reset or clone explicitly reused plugin instances.
+
+For independent tests, let TestForge create a fresh Pinia instance for each mount. If a test requires `withPluginInstance()`, create the supplied Pinia instance separately for each test unless shared state is an intentional part of the scenario.
+
+Reusing the same `withMockStores()` configuration **does not itself share Pinia state**: it is the explicit reuse of an instance via `withPluginInstance()` that causes the mounts to share state, assuming the callback does not depend on other shared mutable data.
+
 ### TestForge plugin defaults
 
 The defaults provided by this package intentionally contain only the runner integration:
@@ -248,13 +330,22 @@ This allows presets to choose explicitly between:
 The package provides both descriptive and standardized plugin exports:
 
 ```typescript
-import { piniaPlugin, plugin, PLUGIN_NAME } from "@testforgejs/vue-test-plugin-pinia";
+import {
+  piniaPlugin,
+  withMockStores,
+  plugin,
+  PLUGIN_NAME,
+} from "@testforgejs/vue-test-plugin-pinia";
 ```
 
 ### `piniaPlugin`
 
 The descriptive Pinia plugin module export.
 
+### `withMockStores()`
+
+A helper that adds a symbol-keyed store setup callback to managed Pinia plugin options. See [Configuring stores with `withMockStores()`](#configuring-stores-with-withmockstores) for examples.
+
 ### `plugin`
 
 The standardized plugin module export.

package/dist/index.cjs

@@ -22,20 +22,28 @@ var index_exports = {};
 __export(index_exports, {
   PLUGIN_NAME: () => PINIA_PLUGIN_NAME,
   piniaPlugin: () => piniaPlugin,
-  plugin: () => piniaPlugin
+  plugin: () => piniaPlugin,
+  withMockStores: () => withMockStores
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/module/createPiniaPlugin.ts
 var import_vue_test_core = require("@testforgejs/vue-test-core");
 var import_testing = require("@pinia/testing");
+
+// src/constants/constants.ts
+var PINIA_PLUGIN_NAME = "pinia";
+var MOCK_STORES = /* @__PURE__ */ Symbol("TestForge.pinia.mockStores");
+
+// src/module/createPiniaPlugin.ts
 function createPiniaPlugin(options) {
+  const { [MOCK_STORES]: mockStores, ...pluginOptions } = options;
   const pinia = (0, import_vue_test_core.createPluginInstance)(
     import_testing.createTestingPinia,
-    options
+    pluginOptions
   );
-  if (options.mockStores) {
-    options.mockStores(pinia);
+  if (mockStores) {
+    mockStores(pinia);
   }
   return pinia;
 }
@@ -53,9 +61,6 @@ var defaultOptions = (runner) => () => {
   };
 };
 
-// src/constants/constants.ts
-var PINIA_PLUGIN_NAME = "pinia";
-
 // src/module/piniaPlugin.ts
 var piniaPlugin = {
   getName: () => PINIA_PLUGIN_NAME,
@@ -75,9 +80,17 @@ var piniaPlugin = {
   }),
   getDefaultOptions: defaultOptions
 };
+
+// src/helpers/withMockStores.ts
+function withMockStores(mockStores) {
+  return {
+    [MOCK_STORES]: mockStores
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PLUGIN_NAME,
   piniaPlugin,
-  plugin
+  plugin,
+  withMockStores
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { TestingOptions, TestingPinia } from '@pinia/testing';
-import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+import { RuntimePluginOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
 
 /**
  * Stable TestForge identifier for the managed Pinia plugin.
@@ -8,12 +8,13 @@ import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue
  * in presets and other plugin-aware TestForge APIs.
  */
 declare const PINIA_PLUGIN_NAME: "pinia";
+declare const MOCK_STORES: unique symbol;
 
 /**
- * A callback for configuring Pinia stores after the testing Pinia instance
- * is created and before the component is mounted.
+ * A callback for configuring Pinia stores after the testing Pinia
+ * instance has been resolved and before the component is mounted.
  *
- * Use it to initialize or modify stores required by the test.
+ * The instance may be newly created or reused through `withPluginInstance()`.
  *
  * @param pinia - The testing Pinia instance used by the mounted component.
  */
@@ -21,36 +22,68 @@ type MockStoresFn = (pinia: TestingPinia) => void;
 /**
  * Configuration options for the Pinia test plugin.
  *
- * Combines native Pinia testing options with TestForge-specific
- * controls for managed plugin instances and store initialization.
+ * Extends native Pinia testing options with TestForge-specific
+ * store initialization support.
  *
- * Instance capturing is handled internally by TestForge using
- * `captureInstance<TestingPinia>()`.
+ * Managed instance controls are provided separately by TestForge
+ * through its plugin configuration types.
  *
- * @see `TestingOptions` from `@pinia/testing` for native Pinia testing configuration.
- * @see `PluginControlOptions` from `@testforgejs/vue-test-core` for type-safe instance capturing.
+ * Use `withMockStores()` to initialize or modify Pinia stores before
+ * the component is mounted.
+ *
+ * The store setup callback runs for both newly created Pinia instances
+ * and pre-created instances reused through `withPluginInstance()`.
+ *
+ * @example
+ * ```ts
+ * import { withMockStores } from "@testforgejs/vue-test-plugin-pinia";
+ *
+ * factory({}, {
+ *   plugins: {
+ *     pinia: {
+ *       stubActions: false,
+ *       ...withMockStores((pinia) => {
+ *         const store = useCounterStore(pinia);
+ *         store.count = 42;
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see `TestingOptions` from `@pinia/testing` for native Pinia configuration.
  */
-type VueTestPiniaOptions = TestingOptions & PluginControlOptions<TestingPinia> & {
+type VueTestPiniaOptions = TestingOptions & {
     /**
-     * A callback for initializing or modifying Pinia stores after the
-     * testing Pinia instance is created and before the component is mounted.
+     * Internal callback for configuring Pinia stores before mounting.
+     *
+     * Use the public `withMockStores()` helper instead of accessing
+     * this property directly.
+     *
+     * The callback runs for both newly created and reused Pinia instances.
      *
-     * @example
-     * ```ts
-     * factory({}, {
-     *   plugins: {
-     *     pinia: {
-     *       mockStores: (pinia) => {
-     *         const store = useCounterStore(pinia);
-     *         store.count = 42;
-     *       },
-     *     },
-     *   },
-     * });
-     * ```
+     * @internal
      */
-    mockStores?: MockStoresFn;
+    [MOCK_STORES]?: MockStoresFn;
 };
+/**
+ * Resolved runtime options for the managed Pinia test plugin.
+ *
+ * Combines {@link VueTestPiniaOptions} with the internal TestForge
+ * controls used to create, reuse, and expose a {@link TestingPinia} instance.
+ *
+ * These options are passed to `createPiniaPlugin()` after the Mount Pipeline
+ * has resolved the plugin configuration.
+ *
+ * Input metadata provided through `withPluginInstance()` is processed
+ * before this stage and is not part of the resolved runtime options.
+ *
+ * @internal
+ *
+ * @see {@link VueTestPiniaOptions}
+ * @see `RuntimePluginOptions` from `@testforgejs/vue-test-core`.
+ */
+type PiniaRuntimeOptions = RuntimePluginOptions<TestingPinia, VueTestPiniaOptions>;
 
 /**
  * TestForge core type augmentation for Pinia integration.
@@ -83,9 +116,43 @@ declare module "@testforgejs/vue-test-core" {
 /**
  * Managed Pinia testing plugin module for TestForge.
  *
- * Provides the runtime definition for creating testing Pinia instances
- * and exposes the default configuration used by TestForge-managed presets.
+ * Provides the runtime definition for creating or reusing testing Pinia
+ * instances and exposes a default configuration factory
+ * that presets can explicitly opt into.
  */
 declare const piniaPlugin: PluginModuleWithDefaults<TestingPinia, VueTestPiniaOptions>;
 
-export { type MockStoresFn, PINIA_PLUGIN_NAME as PLUGIN_NAME, type VueTestPiniaOptions, piniaPlugin, piniaPlugin as plugin };
+/**
+ * Creates Pinia plugin options for initializing or modifying stores
+ * before the component is mounted.
+ *
+ * The callback receives the resolved testing Pinia instance, whether
+ * it was newly created or reused through `withPluginInstance()`.
+ *
+ * Spread the returned options into the Pinia configuration provided
+ * to a TestForge component factory.
+ *
+ * @param mockStores - Callback invoked with the resolved testing Pinia instance.
+ * @returns Plugin options containing the store initialization callback.
+ *
+ * @example
+ * ```ts
+ * import { withMockStores } from "@testforgejs/vue-test-plugin-pinia";
+ *
+ * factory({}, {
+ *   plugins: {
+ *     pinia: {
+ *       ...withMockStores((pinia) => {
+ *         const store = useCounterStore(pinia);
+ *         store.count = 42;
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function withMockStores(mockStores: MockStoresFn): {
+    [MOCK_STORES]: MockStoresFn;
+};
+
+export { type MockStoresFn, PINIA_PLUGIN_NAME as PLUGIN_NAME, type PiniaRuntimeOptions, type VueTestPiniaOptions as PluginOptions, type VueTestPiniaOptions, piniaPlugin, piniaPlugin as plugin, withMockStores };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { TestingOptions, TestingPinia } from '@pinia/testing';
-import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+import { RuntimePluginOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
 
 /**
  * Stable TestForge identifier for the managed Pinia plugin.
@@ -8,12 +8,13 @@ import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue
  * in presets and other plugin-aware TestForge APIs.
  */
 declare const PINIA_PLUGIN_NAME: "pinia";
+declare const MOCK_STORES: unique symbol;
 
 /**
- * A callback for configuring Pinia stores after the testing Pinia instance
- * is created and before the component is mounted.
+ * A callback for configuring Pinia stores after the testing Pinia
+ * instance has been resolved and before the component is mounted.
  *
- * Use it to initialize or modify stores required by the test.
+ * The instance may be newly created or reused through `withPluginInstance()`.
  *
  * @param pinia - The testing Pinia instance used by the mounted component.
  */
@@ -21,36 +22,68 @@ type MockStoresFn = (pinia: TestingPinia) => void;
 /**
  * Configuration options for the Pinia test plugin.
  *
- * Combines native Pinia testing options with TestForge-specific
- * controls for managed plugin instances and store initialization.
+ * Extends native Pinia testing options with TestForge-specific
+ * store initialization support.
  *
- * Instance capturing is handled internally by TestForge using
- * `captureInstance<TestingPinia>()`.
+ * Managed instance controls are provided separately by TestForge
+ * through its plugin configuration types.
  *
- * @see `TestingOptions` from `@pinia/testing` for native Pinia testing configuration.
- * @see `PluginControlOptions` from `@testforgejs/vue-test-core` for type-safe instance capturing.
+ * Use `withMockStores()` to initialize or modify Pinia stores before
+ * the component is mounted.
+ *
+ * The store setup callback runs for both newly created Pinia instances
+ * and pre-created instances reused through `withPluginInstance()`.
+ *
+ * @example
+ * ```ts
+ * import { withMockStores } from "@testforgejs/vue-test-plugin-pinia";
+ *
+ * factory({}, {
+ *   plugins: {
+ *     pinia: {
+ *       stubActions: false,
+ *       ...withMockStores((pinia) => {
+ *         const store = useCounterStore(pinia);
+ *         store.count = 42;
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see `TestingOptions` from `@pinia/testing` for native Pinia configuration.
  */
-type VueTestPiniaOptions = TestingOptions & PluginControlOptions<TestingPinia> & {
+type VueTestPiniaOptions = TestingOptions & {
     /**
-     * A callback for initializing or modifying Pinia stores after the
-     * testing Pinia instance is created and before the component is mounted.
+     * Internal callback for configuring Pinia stores before mounting.
+     *
+     * Use the public `withMockStores()` helper instead of accessing
+     * this property directly.
+     *
+     * The callback runs for both newly created and reused Pinia instances.
      *
-     * @example
-     * ```ts
-     * factory({}, {
-     *   plugins: {
-     *     pinia: {
-     *       mockStores: (pinia) => {
-     *         const store = useCounterStore(pinia);
-     *         store.count = 42;
-     *       },
-     *     },
-     *   },
-     * });
-     * ```
+     * @internal
      */
-    mockStores?: MockStoresFn;
+    [MOCK_STORES]?: MockStoresFn;
 };
+/**
+ * Resolved runtime options for the managed Pinia test plugin.
+ *
+ * Combines {@link VueTestPiniaOptions} with the internal TestForge
+ * controls used to create, reuse, and expose a {@link TestingPinia} instance.
+ *
+ * These options are passed to `createPiniaPlugin()` after the Mount Pipeline
+ * has resolved the plugin configuration.
+ *
+ * Input metadata provided through `withPluginInstance()` is processed
+ * before this stage and is not part of the resolved runtime options.
+ *
+ * @internal
+ *
+ * @see {@link VueTestPiniaOptions}
+ * @see `RuntimePluginOptions` from `@testforgejs/vue-test-core`.
+ */
+type PiniaRuntimeOptions = RuntimePluginOptions<TestingPinia, VueTestPiniaOptions>;
 
 /**
  * TestForge core type augmentation for Pinia integration.
@@ -83,9 +116,43 @@ declare module "@testforgejs/vue-test-core" {
 /**
  * Managed Pinia testing plugin module for TestForge.
  *
- * Provides the runtime definition for creating testing Pinia instances
- * and exposes the default configuration used by TestForge-managed presets.
+ * Provides the runtime definition for creating or reusing testing Pinia
+ * instances and exposes a default configuration factory
+ * that presets can explicitly opt into.
  */
 declare const piniaPlugin: PluginModuleWithDefaults<TestingPinia, VueTestPiniaOptions>;
 
-export { type MockStoresFn, PINIA_PLUGIN_NAME as PLUGIN_NAME, type VueTestPiniaOptions, piniaPlugin, piniaPlugin as plugin };
+/**
+ * Creates Pinia plugin options for initializing or modifying stores
+ * before the component is mounted.
+ *
+ * The callback receives the resolved testing Pinia instance, whether
+ * it was newly created or reused through `withPluginInstance()`.
+ *
+ * Spread the returned options into the Pinia configuration provided
+ * to a TestForge component factory.
+ *
+ * @param mockStores - Callback invoked with the resolved testing Pinia instance.
+ * @returns Plugin options containing the store initialization callback.
+ *
+ * @example
+ * ```ts
+ * import { withMockStores } from "@testforgejs/vue-test-plugin-pinia";
+ *
+ * factory({}, {
+ *   plugins: {
+ *     pinia: {
+ *       ...withMockStores((pinia) => {
+ *         const store = useCounterStore(pinia);
+ *         store.count = 42;
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function withMockStores(mockStores: MockStoresFn): {
+    [MOCK_STORES]: MockStoresFn;
+};
+
+export { type MockStoresFn, PINIA_PLUGIN_NAME as PLUGIN_NAME, type PiniaRuntimeOptions, type VueTestPiniaOptions as PluginOptions, type VueTestPiniaOptions, piniaPlugin, piniaPlugin as plugin, withMockStores };

package/dist/index.js

@@ -1,13 +1,20 @@
 // src/module/createPiniaPlugin.ts
 import { createPluginInstance } from "@testforgejs/vue-test-core";
 import { createTestingPinia } from "@pinia/testing";
+
+// src/constants/constants.ts
+var PINIA_PLUGIN_NAME = "pinia";
+var MOCK_STORES = /* @__PURE__ */ Symbol("TestForge.pinia.mockStores");
+
+// src/module/createPiniaPlugin.ts
 function createPiniaPlugin(options) {
+  const { [MOCK_STORES]: mockStores, ...pluginOptions } = options;
   const pinia = createPluginInstance(
     createTestingPinia,
-    options
+    pluginOptions
   );
-  if (options.mockStores) {
-    options.mockStores(pinia);
+  if (mockStores) {
+    mockStores(pinia);
   }
   return pinia;
 }
@@ -25,9 +32,6 @@ var defaultOptions = (runner) => () => {
   };
 };
 
-// src/constants/constants.ts
-var PINIA_PLUGIN_NAME = "pinia";
-
 // src/module/piniaPlugin.ts
 var piniaPlugin = {
   getName: () => PINIA_PLUGIN_NAME,
@@ -47,8 +51,16 @@ var piniaPlugin = {
   }),
   getDefaultOptions: defaultOptions
 };
+
+// src/helpers/withMockStores.ts
+function withMockStores(mockStores) {
+  return {
+    [MOCK_STORES]: mockStores
+  };
+}
 export {
   PINIA_PLUGIN_NAME as PLUGIN_NAME,
   piniaPlugin,
-  piniaPlugin as plugin
+  piniaPlugin as plugin,
+  withMockStores
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testforgejs/vue-test-plugin-pinia",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.7",
   "type": "module",
   "description": "Official TestForge plugin for Pinia integration in component tests",
   "homepage": "https://github.com/testforgejs/testforge#readme",
@@ -45,12 +45,12 @@
   "peerDependencies": {
     "pinia": "^3.0.0 || ^4.0.0",
     "@pinia/testing": "^1.0.0 || ^2.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.5"
+    "@testforgejs/vue-test-core": "1.0.0-beta.6"
   },
   "devDependencies": {
     "pinia": "^4.0.0",
     "@pinia/testing": "^2.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.5"
+    "@testforgejs/vue-test-core": "1.0.0-beta.6"
   },
   "testforge": {
     "plugin": {