{"id":15042,"library":"vue-router-mock","title":"Vue Router Mock","description":"vue-router-mock is a testing utility designed for Vue 3 applications, specifically to facilitate unit and integration testing of components that interact with the official `vue-router`. Currently stable at version 2.0.2, the library maintains an active release cadence, providing minor updates for bug fixes and compatibility, such as the recent addition of `vue-router` v5 support. Its core purpose is to provide a mock `vue-router` instance that can be injected into components, enabling developers to spy on navigation calls (e.g., `push`, `replace`), simulate route changes, and assert router state without requiring a full browser environment or actual navigation. It differentiates itself from end-to-end testing tools by focusing on isolated scenarios, leading to more granular and faster test execution. The library integrates seamlessly with `@vue/test-utils` and offers flexible setup options for test environments like Jest or Vitest through functions such as `createRouterMock` and `injectRouterMock`.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/posva/vue-router-mock","tags":["javascript","vue","router","mock","spy","stub","jest","test","vue-router","typescript"],"install":[{"cmd":"npm install vue-router-mock","lang":"bash","label":"npm"},{"cmd":"yarn add vue-router-mock","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-router-mock","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for mounting Vue components under test.","package":"vue","optional":false},{"reason":"The library mocks this package; a compatible version is needed for type inference and API consistency.","package":"vue-router","optional":false},{"reason":"Essential for mounting Vue components and accessing the mock router via `config.plugins.VueWrapper.install`.","package":"@vue/test-utils","optional":false}],"imports":[{"note":"Primarily an ESM library. CJS `require` syntax is not recommended and may cause issues.","wrong":"const createRouterMock = require('vue-router-mock')","symbol":"createRouterMock","correct":"import { createRouterMock } from 'vue-router-mock'"},{"note":"This is a named export, not a default export.","wrong":"import injectRouterMock from 'vue-router-mock'","symbol":"injectRouterMock","correct":"import { injectRouterMock } from 'vue-router-mock'"},{"note":"This symbol is specifically used with `@vue/test-utils` to extend wrapper capabilities.","symbol":"VueRouterMock","correct":"import { VueRouterMock } from 'vue-router-mock'"}],"quickstart":{"code":"import { VueRouterMock, createRouterMock, injectRouterMock } from 'vue-router-mock';\nimport { config } from '@vue/test-utils';\nimport { mount } from '@vue/test-utils';\nimport { defineComponent } from 'vue';\n\n// Create a simple component to test\nconst MyComponent = defineComponent({\n  template: `\n    <div>\n      <p>Current path: {{ $route.path }}</p>\n      <button @click=\"$router.push('/about')\">Go to About</button>\n    </div>\n  `\n});\n\n// Create one router per test file/suite setup\nconst router = createRouterMock();\n\nbeforeEach(() => {\n  router.reset(); // Reset the router state before each test\n  injectRouterMock(router); // Inject the mock router globally for the test\n});\n\n// Add properties to the @vue/test-utils wrapper (required for `wrapper.router`)\nconfig.plugins.VueWrapper.install(VueRouterMock);\n\ndescribe('MyComponent with vue-router-mock', () => {\n  it('should display the current path and navigate', async () => {\n    const wrapper = mount(MyComponent);\n\n    // Initial state\n    expect(wrapper.find('p').text()).toContain('/');\n    expect(wrapper.router.path).toBe('/');\n\n    // Simulate navigation\n    await wrapper.find('button').trigger('click');\n    \n    // Assertions on the mock router\n    expect(wrapper.router.push).toHaveBeenCalledTimes(1);\n    expect(wrapper.router.push).toHaveBeenCalledWith('/about');\n\n    // Assertions on component state after navigation (if it reacts to route change)\n    // Note: for reactive updates, you might need await wrapper.vm.$nextTick()\n    // depending on how the component consumes the route changes\n    expect(wrapper.find('p').text()).toContain('/about');\n  });\n});\n","lang":"javascript","description":"This quickstart demonstrates how to globally set up `vue-router-mock` for a test suite using `beforeEach`, inject a mock router, and then mount a component to test its router interactions, asserting on `wrapper.router` calls."},"warnings":[{"fix":"Refer to the official `CHANGELOG.md` for specific migration instructions when upgrading from v1.x to v2.x. Update your testing setup files and component interaction tests accordingly.","message":"Version 2.0.0 introduced significant changes. While the specific breaking changes are detailed in the `CHANGELOG.md` file on GitHub, users upgrading from v1.x should consult it for migration steps, as API surface and integration methods may have changed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use dedicated E2E testing frameworks like Cypress or Playwright with your actual `vue-router` configuration for full application flow tests.","message":"This library is explicitly designed for unit and integration testing and is not suitable for end-to-end (E2E) testing scenarios. For E2E tests, it's recommended to use the real `vue-router` setup within a browser environment.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your test setup file (e.g., `setupFilesAfterEnv` in Jest or `setupFiles` in Vitest) includes `config.plugins.VueWrapper.install(VueRouterMock)` after importing `VueRouterMock`.","message":"To enable `wrapper.router` access in `@vue/test-utils` wrappers, you must explicitly install the `VueRouterMock` plugin via `config.plugins.VueWrapper.install(VueRouterMock)` in your test setup file.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If encountering import errors in Jest, try renaming your setup file to `.cjs` or converting its imports to `require()` syntax. Alternatively, ensure your Jest configuration is set up for ESM.","message":"When using Jest, your test setup file (e.g., in `setupFilesAfterEnv`) might need to be written in CommonJS syntax if Jest's environment does not fully support ESM, leading to import errors. Vitest typically handles ESM better.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `injectRouterMock(router)` is called before mounting the component in your test, and that `config.plugins.VueWrapper.install(VueRouterMock)` is set up globally if accessing via `wrapper.router`.","cause":"The mock router has not been correctly injected into the component under test or its wrapper.","error":"TypeError: Cannot read properties of undefined (reading 'push') or TypeError: this.$router is undefined"},{"fix":"Verify that `injectRouterMock(router)` is being called in your test setup (e.g., `beforeEach`) to ensure the mock router is provided to the components within the test scope.","cause":"The Vue application instance or component hierarchy does not have the mock router provided.","error":"Error: [vue-router]: Injection \"VueRouter\" not found."},{"fix":"Make sure to `import { config } from '@vue/test-utils'` and that the `config.plugins.VueWrapper.install(VueRouterMock)` line is executed after `config` is properly defined.","cause":"The `@vue/test-utils` `config` object or `VueWrapper` is not correctly imported or available when attempting to install the `VueRouterMock` plugin.","error":"TypeError: Cannot read properties of undefined (reading 'install') or Cannot access 'config' before initialization"}],"ecosystem":"npm"}