@testforgejs/vue-test-plugin-router 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -1,6 +1,6 @@
 # @testforgejs/vue-test-plugin-router
 
-Official TestForge plugin for Vue Router integration in component tests.
+Vue Router integration for TestForge component tests.
 
 ## Installation
 
@@ -24,13 +24,63 @@ npm install -D @testforgejs/vue-test-plugin-router@beta
 yarn add -D @testforgejs/vue-test-plugin-router@beta
 ```
 
-> `@testforgejs/vue-test-core` is required.
+> `@testforgejs/vue-test-core` and `vue-router` are required.
 
 ## Usage
 
-Register `routerPlugin` in the TestForge plugin manifest.
+### Using plugin defaults
+
+The plugin provides a project-independent default configuration through `getDefaultOptions()`:
+
+```typescript
+import { createTestFramework } from "@testforgejs/vue-test-core";
+import { routerPlugin } from "@testforgejs/vue-test-plugin-router";
+
+const framework = createTestFramework({
+  presets: {
+    default: {
+      manifest: [
+        {
+          module: routerPlugin,
+          enabled: true,
+        },
+      ],
+      defaults: {
+        router: routerPlugin.getDefaultOptions(),
+      },
+    },
+  },
+});
+
+const factory = framework.testComponentFactory(MyComponent);
+
+const wrapper = factory();
+```
+
+`getDefaultOptions()` returns an options factory suitable for use in a preset.
+
+The plugin-provided defaults are equivalent to:
 
 ```typescript
+{
+  history: createMemoryHistory(),
+  routes: [],
+}
+```
+
+The in-memory history keeps router state isolated from the browser environment, while the empty route table avoids introducing application-specific routes.
+
+These defaults provide the minimum Vue Router configuration required to create a router instance. They do not define routes or other routing behavior on behalf of the application.
+
+Plugin defaults are **not applied automatically**. Adding the plugin to a preset manifest declares that the plugin is available and whether it is enabled; the preset explicitly decides whether to use the plugin-provided defaults or provide its own configuration.
+
+### Providing custom options
+
+You can define the Vue Router configuration directly in the preset instead:
+
+```typescript
+import { createMemoryHistory } from "vue-router";
+
 import { createTestFramework } from "@testforgejs/vue-test-core";
 import { routerPlugin } from "@testforgejs/vue-test-plugin-router";
 
@@ -45,34 +95,130 @@ const framework = createTestFramework({
       ],
       defaults: {
         router: () => ({
+          history: createMemoryHistory(),
           routes: [
             {
               path: "/",
               component: { render: () => null },
             },
+            {
+              path: "/users/:id",
+              component: UserDetails,
+            },
           ],
         }),
       },
     },
   },
 });
+```
 
-const factory = framework.testComponentFactory(MyComponent);
+Using `getDefaultOptions()` is optional. Define custom defaults when tests require application-specific routes, a different history implementation, navigation behavior, or other Vue Router configuration.
 
-const wrapper = factory();
+For tests that depend on application routes, [create a project-specific preset](https://github.com/testforgejs/testforge/blob/main/docs/preset-authoring-guide.md) that provides the router configuration required by the application.
+
+## Configuration
+
+### Vue Router options
+
+The plugin integrates TestForge with Vue Router by creating a router from the provided Vue Router options.
+
+Configuration fields such as `history`, `routes`, `scrollBehavior`, `linkActiveClass`, and other router options belong to Vue Router.
+
+TestForge does not define an alternative router configuration format. The integration passes these options to Vue Router when creating the router instance.
+
+Refer to the Vue Router documentation for the complete set of supported router options and their behavior.
+
+### TestForge plugin defaults
+
+The defaults provided by this package intentionally contain only the configuration required to create an isolated, project-independent router:
+
+```typescript
+{
+  history: createMemoryHistory(),
+  routes: [],
+}
 ```
 
-`defaults.router` is an options factory. Each invocation produces a fresh Vue Router options object for the current pipeline context.
+`createMemoryHistory()` is used regardless of whether the test environment exposes browser globals. This keeps the default router isolated from `window.location` and browser history state and makes the configuration consistent across test environments.
 
-The default configuration provides a minimal `/` route so that Vue Router is ready to use without requiring application-specific routes.
+The route table is empty because TestForge does not know the routes defined by the application. Application routes should be supplied by a project-specific preset or other explicit test configuration.
 
-For tests that depend on application routes, [create a project-specific preset](https://github.com/testforgejs/testforge/blob/main/docs/preset-authoring-guide.md) that provides the router configuration required by the application.
+The plugin does not add a synthetic `/` route or otherwise define application routing behavior.
+
+If tests require actual routes, provide them explicitly:
+
+```typescript
+defaults: {
+  router: () => ({
+    history: createMemoryHistory(),
+    routes: [
+      {
+        path: "/users/:id",
+        component: UserDetails,
+      },
+    ],
+  }),
+},
+```
+
+Likewise, if tests specifically depend on browser history behavior, provide the appropriate Vue Router history implementation explicitly.
+
+### Options factories
+
+Preset defaults are defined as factories:
+
+```typescript
+defaults: {
+  router: () => ({
+    history: createMemoryHistory(),
+    routes: [],
+  }),
+},
+```
+
+Each invocation of the factory produces a fresh options object for the current TestForge pipeline execution, including a fresh in-memory history instance.
+
+`routerPlugin.getDefaultOptions()` follows the same contract: it returns an options factory rather than a shared options object.
+
+This allows presets to choose explicitly between:
+
+- the minimal project-independent defaults provided by the plugin; and
+- a custom Vue Router configuration defined by the preset.
+
+## Package exports
+
+The package provides both descriptive and standardized plugin exports:
+
+```typescript
+import { routerPlugin, plugin, PLUGIN_NAME } from "@testforgejs/vue-test-plugin-router";
+```
+
+### `routerPlugin`
+
+The descriptive Vue Router plugin module export.
+
+### `plugin`
+
+The standardized plugin module export.
+
+It references the same plugin module as `routerPlugin` and provides a consistent package-level API across TestForge plugin packages.
+
+### `PLUGIN_NAME`
+
+The standardized plugin identifier export.
+
+For this package:
+
+```typescript
+PLUGIN_NAME === "router";
+```
 
-The plugin provides Vue Router integration for components mounted through TestForge.
+The standardized `plugin` and `PLUGIN_NAME` exports are useful for tooling and other code that works with TestForge plugin packages generically.
 
 ## Supported versions
 
-- Vue: 3.x
+- Vue: 3.3.0 or higher
 - Vue Router: 4.x and 5.x
 
 ## Documentation

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  PLUGIN_NAME: () => ROUTER_PLUGIN_NAME,
+  plugin: () => routerPlugin,
   routerPlugin: () => routerPlugin
 });
 module.exports = __toCommonJS(index_exports);
@@ -31,14 +33,27 @@ function createRouterPlugin(options) {
   return (0, import_vue_test_core.createPluginInstance)(import_vue_router.createRouter, options);
 }
 
+// src/defaults.ts
+var import_vue_router2 = require("vue-router");
+var defaultOptions = () => () => ({
+  history: (0, import_vue_router2.createMemoryHistory)(),
+  routes: []
+});
+
+// src/constants/constants.ts
+var ROUTER_PLUGIN_NAME = "router";
+
 // src/module/routerPlugin.ts
 var routerPlugin = {
-  getName: () => "router",
+  getName: () => ROUTER_PLUGIN_NAME,
   getDefinition: () => ({
     create: createRouterPlugin
-  })
+  }),
+  getDefaultOptions: defaultOptions
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PLUGIN_NAME,
+  plugin,
   routerPlugin
 });

package/dist/index.d.cts

@@ -1,17 +1,38 @@
 import { RouterOptions, Router } from 'vue-router';
-import { PluginControlOptions, PluginModule } from '@testforgejs/vue-test-core';
+import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+
+/**
+ * Stable TestForge identifier for the managed Vue Router plugin.
+ *
+ * Use this identifier when declaring Router configuration
+ * in presets and other plugin-aware TestForge APIs.
+ */
+declare const ROUTER_PLUGIN_NAME: "router";
 
 /**
  * Configuration options for the Vue Router test plugin.
  *
- * This interface integrates standard router initialization settings
- * and TestForge test kernel control options (such as `expose`).
+ * Combines standard Vue Router configuration (`RouterOptions` from `vue-router`)
+ * with TestForge plugin control options.
  *
- * @see {@link RouterOptions} from the `vue-router` package for configuring routes and history.
- * @see {@link PluginControlOptions} from the `@testforgejs/vue-test-core` package for instance interception.
+ * @example
+ * Configure the managed Vue Router plugin for a component test:
+ *
+ * ```ts
+ * factory({}, {
+ *   plugins: {
+ *     router: {
+ *       history: createMemoryHistory(),
+ *       routes: [],
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see `RouterOptions` from `vue-router` for configuring routes and history.
+ * @see `PluginControlOptions` from `@testforgejs/vue-test-core` for instance capturing and exposure mechanisms.
  */
-interface VueTestRouterOptions extends RouterOptions, PluginControlOptions<Router> {
-}
+type VueTestRouterOptions = RouterOptions & PluginControlOptions<Router>;
 
 /**
  * Extending TestForge kernel types for Vue Router integration.
@@ -42,13 +63,16 @@ declare module "@testforgejs/vue-test-core" {
          * });
          * ```
          */
-        router: VueTestRouterOptions;
+        [ROUTER_PLUGIN_NAME]: VueTestRouterOptions;
     }
 }
 
 /**
- * A Vue Router plugin module for the TestForge testing framework.
+ * Managed Vue Router plugin module for TestForge.
+ *
+ * Provides the runtime definition for creating Vue Router instances
+ * and exposes the default configuration used by TestForge-managed presets.
  */
-declare const routerPlugin: PluginModule<Router, VueTestRouterOptions>;
+declare const routerPlugin: PluginModuleWithDefaults<Router, VueTestRouterOptions>;
 
-export { type VueTestRouterOptions, routerPlugin };
+export { ROUTER_PLUGIN_NAME as PLUGIN_NAME, type VueTestRouterOptions, routerPlugin as plugin, routerPlugin };

package/dist/index.d.ts

@@ -1,17 +1,38 @@
 import { RouterOptions, Router } from 'vue-router';
-import { PluginControlOptions, PluginModule } from '@testforgejs/vue-test-core';
+import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+
+/**
+ * Stable TestForge identifier for the managed Vue Router plugin.
+ *
+ * Use this identifier when declaring Router configuration
+ * in presets and other plugin-aware TestForge APIs.
+ */
+declare const ROUTER_PLUGIN_NAME: "router";
 
 /**
  * Configuration options for the Vue Router test plugin.
  *
- * This interface integrates standard router initialization settings
- * and TestForge test kernel control options (such as `expose`).
+ * Combines standard Vue Router configuration (`RouterOptions` from `vue-router`)
+ * with TestForge plugin control options.
  *
- * @see {@link RouterOptions} from the `vue-router` package for configuring routes and history.
- * @see {@link PluginControlOptions} from the `@testforgejs/vue-test-core` package for instance interception.
+ * @example
+ * Configure the managed Vue Router plugin for a component test:
+ *
+ * ```ts
+ * factory({}, {
+ *   plugins: {
+ *     router: {
+ *       history: createMemoryHistory(),
+ *       routes: [],
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see `RouterOptions` from `vue-router` for configuring routes and history.
+ * @see `PluginControlOptions` from `@testforgejs/vue-test-core` for instance capturing and exposure mechanisms.
  */
-interface VueTestRouterOptions extends RouterOptions, PluginControlOptions<Router> {
-}
+type VueTestRouterOptions = RouterOptions & PluginControlOptions<Router>;
 
 /**
  * Extending TestForge kernel types for Vue Router integration.
@@ -42,13 +63,16 @@ declare module "@testforgejs/vue-test-core" {
          * });
          * ```
          */
-        router: VueTestRouterOptions;
+        [ROUTER_PLUGIN_NAME]: VueTestRouterOptions;
     }
 }
 
 /**
- * A Vue Router plugin module for the TestForge testing framework.
+ * Managed Vue Router plugin module for TestForge.
+ *
+ * Provides the runtime definition for creating Vue Router instances
+ * and exposes the default configuration used by TestForge-managed presets.
  */
-declare const routerPlugin: PluginModule<Router, VueTestRouterOptions>;
+declare const routerPlugin: PluginModuleWithDefaults<Router, VueTestRouterOptions>;
 
-export { type VueTestRouterOptions, routerPlugin };
+export { ROUTER_PLUGIN_NAME as PLUGIN_NAME, type VueTestRouterOptions, routerPlugin as plugin, routerPlugin };

package/dist/index.js

@@ -5,13 +5,26 @@ function createRouterPlugin(options) {
   return createPluginInstance(createRouter, options);
 }
 
+// src/defaults.ts
+import { createMemoryHistory } from "vue-router";
+var defaultOptions = () => () => ({
+  history: createMemoryHistory(),
+  routes: []
+});
+
+// src/constants/constants.ts
+var ROUTER_PLUGIN_NAME = "router";
+
 // src/module/routerPlugin.ts
 var routerPlugin = {
-  getName: () => "router",
+  getName: () => ROUTER_PLUGIN_NAME,
   getDefinition: () => ({
     create: createRouterPlugin
-  })
+  }),
+  getDefaultOptions: defaultOptions
 };
 export {
+  ROUTER_PLUGIN_NAME as PLUGIN_NAME,
+  routerPlugin as plugin,
   routerPlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testforgejs/vue-test-plugin-router",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "type": "module",
   "description": "Official TestForge plugin for Vue Router integration in component tests",
   "homepage": "https://github.com/testforgejs/testforge#readme",
@@ -44,12 +44,18 @@
   "license": "MIT",
   "author": "Roman Levchenko",
   "peerDependencies": {
-    "vue-router": ">=4.0.0 <6.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "vue-router": "^4.0.0 || ^5.0.0",
+    "@testforgejs/vue-test-core": "1.0.0-beta.3"
   },
   "devDependencies": {
     "vue-router": "^5.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "@testforgejs/vue-test-core": "1.0.0-beta.3"
+  },
+  "testforge": {
+    "plugin": {
+      "schemaVersion": 1,
+      "displayName": "Vue Router"
+    }
   },
   "scripts": {
     "build": "tsup",