Easily mock routing interactions in your Vue 3 apps
pnpm i -D vue-router-mock
# or
yarn add -D vue-router-mock
# or
npm install -D vue-router-mockThis library
@vue/test-utils>= 2.4.0- vue 3 and vue router 4
The goal of Vue Router Mock is to enable users to unit and integration test navigation scenarios. This means tests that are isolated enough to not be end to end tests (e.g. using Cypress) or are edge cases (e.g. network failures). Because of this, some scenarios are more interesting as end to end tests, using the real vue router.
Vue Router Mock exposes a few functions to be used individually and they are all documented through TS. But most of the time you want to globally inject the router in a setupFilesAfterEnv file. Create a tests/router-mock-setup.js file at the root of your project (it can be named differently):
import {
VueRouterMock,
createRouterMock,
injectRouterMock,
} from 'vue-router-mock'
import { config } from '@vue/test-utils'
// create one router per test file
const router = createRouterMock()
beforeEach(() => {
router.reset() // reset the router state
injectRouterMock(router)
})
// Add properties to the wrapper
config.plugins.VueWrapper.install(VueRouterMock)Note: you might need to write this file in CommonJS for Jest. In Vite, you can write it in Typescript
Then add this line to your jest.config.js:
setupFilesAfterEnv: ['<rootDir>/tests/router-mock-setup.js'],or to your vitest.config.ts:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
environment: 'happy-dom', // <- or jsdom, needed to mount Vue Components
setupFiles: ['./tests/setup-router-mock.ts'],
},
})This will inject a router in all your tests. If for specific tests, you need to inject a different version of the router, you can do so:
import { createRouterMock, injectRouterMock } from 'vue-router-mock'
describe('SearchUsers', () => {
// create one mock instance, pass options
const router = createRouterMock({
// ...
})
beforeEach(() => {
// inject it globally to ensure `useRoute()`, `$route`, etc work
// properly and give you access to test specific functions
injectRouterMock(router)
})
it('should paginate', async () => {
const wrapper = mount(SearchUsers)
expect(wrapper.router).toBe(router)
// go to the next page
// this will internally trigger `router.push({ query: { page: 2 }})`
wrapper.find('button.next-page').click()
expect(wrapper.router.push).toHaveBeenCalledWith(
expect.objectContaining({ query: { page: 2 } })
)
expect(wrapper.router.push).toHaveBeenCalledTimes(1)
// if we had a navigation guard fetching the search results,
// waiting for it to be done will allow us to wait until it's done.
// Note you need to mock the fetch and to activate navigation
// guards as explained below
await router.getPendingNavigation()
// wait for the component to render again if we want to check
await wrapper.vm.nextTick()
expect(wrapper.find('#user-results .user').text()).toMatchSnapshot()
})
})If you need to create a specific version of the router for one single test (or a nested suite of them), you should call the same functions:
it('should paginate', async () => {
const router = createRouterMock()
injectRouterMock(router)
const wrapper = mount(SearchUsers)
})You can access the instance of the router mock in multiple ways:
-
Access
wrapper.router:it('tests something', async () => { const wrapper = mount(MyComponent) await wrapper.router.push('/new-location') })
-
Access it through
wrapper.vm:it('tests something', async () => { const wrapper = mount(MyComponent) await wrapper.vm.$router.push('/new-location') expect(wrapper.vm.$route.name).toBe('NewLocation') })
-
Call
getRouter()inside of a test:it('tests something', async () => { // can be called before creating the wrapper const router = getRouter() const wrapper = mount(MyComponent) await router.push('/new-location') })
setParams allows you to change route params without triggering a navigation:
it('should display the user details', async () => {
const wrapper = mount(UserDetails)
getRouter().setParams({ userId: 12 })
// test...
})It can be awaited if you need to wait for Vue to render again:
it('should display the user details', async () => {
const wrapper = mount(UserDetails)
await getRouter().setParams({ userId: 12 })
// test...
})setQuery and setHash are very similar.
They can be used to set the route query or hash without triggering a navigation,
and can be awaited too.
By default the router mock starts on START_LOCATION. In some scenarios this might need to be adjusted by pushing a new location and awaiting it before testing:
it('should paginate', async () => {
await router.push('/users?q=haruno')
const wrapper = mount(SearchUsers)
// test...
})You can also set the initial location for all your tests by passing an initialLocation:
const router = createRouterMock({
initialLocation: '/users?q=jolyne',
})initialLocation accepts anything that can be passed to router.push().
You can simulate the failure of the next navigation
By default, all navigation guards are ignored so that you can simulate the return of the next guard by using setNextGuardReturn() without depending on existing ones:
// simulate a navigation guard that returns false
router.setNextGuardReturn(false)
// simulate a redirection
router.setNextGuardReturn('/login')If you want to still run existing navigation guards inside component, you can active them when creating your router mock:
const router = createRouterMock({
// run `onBeforeRouteLeave()`, `onBeforeRouteUpdate()`, `beforeRouteEnter()`, `beforeRouteUpdate()`, and `beforeRouteLeave()`
runInComponentGuards: true,
// run `beforeEnter` of added routes. Note that you must manually add these routes with `router.addRoutes()`
runPerRouteGuards: true,
})By default, both <router-link> and <router-view> are stubbed but you can override them locally. This is specially useful when you have nested <router-view> and you rely on them for a test:
const wrapper = mount(MyComponent, {
global: {
stubs: { RouterView: MyNestedComponent },
},
})You need to manually specify the component that is supposed to be displayed because the mock won't be able to know the level of nesting.
NOTE: this might change to become automatic if the necessary routes are provided.
Vue Router Mock automatically detects if you are using Sinon.js, Jest, or Vitest and use their spying methods. You can of course configure Vue Router Mock to use any spying library you want.
For example, if you use Vitest with globals: false,
then you need to manually configure the spy option and pass vi.fn() to it:
const router = createRouterMock({
spy: {
create: fn => vi.fn(fn),
reset: spy => spy.mockClear(),
},
})By default, the router mock comes with one single catch all route. You can add routes calling the router.addRoute() function but if you add nested routes and you are relying on running navigation guards, you must manually set the depth of the route you are displaying. This is because the router has no way to know which level of nesting you are trying to display. e.g. Imagine the following routes:
const routes = [
{
path: '/users',
// we are not testing this one so it doesn't matter
component: UserView,
children: [
// UserDetail must be the same component we are unit testing
{ path: ':id', component: UserDetail },
],
},
]// 0 would be if we were testing UserView at /users
router.depth.value = 1
const wrapper = mount(UserDetail)Remember, this is not necessary if you are not adding routes or if they are not nested.
- Jest
- Vitest
- Sinon.js
- Vue Test Utils
- Vue Router
- Vuex Mock Store - A Vuex 3.x mock
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent