Find the Vue.js 2 version here.
Since a router usually involves multiple components operating together, often routing tests take place further up the , right up at the e2e/integration test level. However, having some unit tests around your routing can be beneficial as well.
Much like previous sections discuss, there are two ways to test components that interact with a router:
- Using an real router instance
- Mocking the
$route
and$router
global objects
Since most Vue applications use the official Vue Router, this guide will focus on that.
The source code for the tests described on this page can be found here and .
Creating the Components
We will build a simple <App>
, that has a /nested-child
route. Visiting /nested-child
renders a <NestedRoute>
component. Create an App.vue
file, and insert the following minimal component:
<NestedRoute>
is equally as minimal:
<template>
<div>Nested Route</div>
</template>
<script>
export default {
name: "NestedRoute"
}
</script>
Creating the Router and Routes
Now we need some routes to test. Let’s start with the routes:
import NestedRoute from "@/components/NestedRoute.vue"
export default [
{ path: "/nested-route", component: NestedRoute }
]
In a real app, you normally would create a router.js
file and import the routes we made, and write something like this:
import { createRouter, createMemoryHistory } from "vue-router"
import { createApp } from "vue"
import routes from "./routes.js"
import App from './App.vue'
const router = createRouter({
history: createMemoryHistory(),
routes
})
app.use(router)
app.mount("#app")
Much like with Vuex, we will create the router on a test by test basis. This will let us have more fine grained control over the state of the application during the unit tests.
Let’s look at some code, then talk about what’s going on. We are testing App.vue
, so in App.spec.js
add the following:
import { mount } from "@vue/test-utils"
import App from "../../src/App.vue"
import { createRouter, createMemoryHistory } from "vue-router"
import NestedRoute from "../../src/components/NestedRoute.vue"
import routes from "../../src/routes.js"
describe("App", () => {
it("renders a child component via routing", async () => {
const router = createRouter({
history: createMemoryHistory(),
routes
})
router.push("/nested-route")
await router.isReady()
const wrapper = mount(App, {
global: {
plugins: [router]
}
})
expect(wrapper.findComponent(NestedRoute).exists()).toBe(true)
})
})
- Notice the tests are marked
await
and callnextTick
. See here for more details on why.
Another interesting point is we are doing the following before mounting the component:
router.push("/nested-route")
await router.isReady()
Vue Router 4 (the one that works with Vue 3) has asynchronous routing. That means we need to ensure the router has finished the initial routing before mounting the component. This is easily accomplished with await router.isReady()
.
Finally, note we are using mount
. If we use shallowMount
, <router-link>
will be stubbed out, regardless of the current route, a useless stub component will be rendered.
Workaround for large render trees using mount
Using mount
is fine in some cases, but sometimes it is not ideal. For example, if you are rendering your entire <App>
component, chances are the render tree is large, containing many components with their own children components and so on. A lot of children components will trigger various lifecycle hooks, making API requests and the such.
If you are using Jest, its powerful mocking system provides an elegent solution to this problem. You can simply mock the child components, in this case <NestedRoute>
. The following mock can be used and the above test will still pass:
Using a Mock Router
Sometimes a real router is not necessary. Let’s update <NestedRoute>
to show a username based on the current path’s query string. This time we will use TDD to implement the feature. Here is a basic test that simply renders the component and makes an assertion:
import { mount } from "@vue/test-utils"
import NestedRoute from "@/components/NestedRoute.vue"
import routes from "@/routes.js"
describe("NestedRoute", () => {
const username = "alice"
const wrapper = mount(NestedRoute)
expect(wrapper.find(".username").text()).toBe(username)
})
})
We don’t have a <div class="username">
yet, so running the test gives us:
FAIL tests/unit/NestedRoute.spec.js
NestedRoute
✕ renders a username from query string (25ms)
● NestedRoute › renders a username from query string
[vue-test-utils]: find did not return .username, cannot call text() on empty Wrapper
Update <NestedRoute>
:
<template>
<div>
Nested Route
<div class="username">
{{ $route.params.username }}
</div>
</div>
</template>
Now the test fails with:
FAIL tests/unit/NestedRoute.spec.js
NestedRoute
✕ renders a username from query string (17ms)
● NestedRoute › renders a username from query string
TypeError: Cannot read property 'params' of undefined
This is because $route
does not exist. We could use a real router, but in this case it is easier to just use the mocks
mounting option:
it("renders a username from query string", () => {
const username = "alice"
const wrapper = mount(NestedRoute, {
global: {
mocks: {
$route: {
params: { username }
}
}
}
})
expect(wrapper.find(".username").text()).toBe(username)
})
Now the test passes. In this case, we don’t do any navigation or anything that relies on the implementation of the router, so using mocks
is good. We don’t really care how username
comes to be in the query string, only that it is present.
Vue Router provides several types of router hooks, called . Two such examples are:
- Global guards (
router.beforeEach
). Declared on the router instance. - In component guards, such as
beforeRouteEnter
. Declared in components.
Making sure these behave correctly is usually a job for an integration test, since you need to have a user navigate from one route to another. However, you can also use unit tests to see if the functions called in the navigation guards are working correctly and get faster feedback about potential bugs. Here are some strategies on decoupling logic from nagivation guards, and writing unit tests around them.
Global Guards
Let’s say you have a bustCache
function that should be called on every route that contains the shouldBustCache
meta field. You routes might look like this:
Using the shouldBustCache
meta field, you want to invalidate the current cache to ensure the user does not get stale data. An implementation might look like this:
import Vue from "vue"
import { createRouter, createMemoryHistory } from "vue-router"
import routes from "./routes.js"
import { bustCache } from "./bust-cache.js"
const router = createRouter({
history: createMemoryHistory(),
routes
})
router.beforeEach((to, from, next) => {
if (to.matched.some(record => record.meta.shouldBustCache)) {
bustCache()
}
next()
})
export default router
In your unit test, you could import the router instance, and attempt to call beforeEach
by typing router.beforeHooks[0]()
. This will throw an error about next
- since you didn’t pass the correct arguments. Instead of this, one strategy is to decouple and independently export the beforeEach
navigation hook, before coupling it to the router. How about:
export function beforeEach(to, from, next) {
bustCache()
}
next()
router.beforeEach((to, from, next) => beforeEach(to, from, next))
export default router
Now writing a test is easy, albeit a little long:
import { beforeEach } from "@/router.js"
import mockModule from "@/bust-cache.js"
jest.mock("@/bust-cache.js", () => ({ bustCache: jest.fn() }))
describe("beforeEach", () => {
afterEach(() => {
mockModule.bustCache.mockClear()
})
it("busts the cache when going to /user", () => {
const to = {
matched: [{ meta: { shouldBustCache: true } }]
}
const next = jest.fn()
beforeEach(to, undefined, next)
expect(mockModule.bustCache).toHaveBeenCalled()
expect(next).toHaveBeenCalled()
})
it("does not bust the cache when going to /user", () => {
const to = {
matched: [{ meta: { shouldBustCache: false } }]
}
const next = jest.fn()
beforeEach(to, undefined, next)
expect(mockModule.bustCache).not.toHaveBeenCalled()
expect(next).toHaveBeenCalled()
})
})
The main point of interest is we mock the entire module using jest.mock
, and reset the mock using the afterEach
hook. By exporting the beforeEach
as a decoupled, regular JavaScript function, it become trivial to test.
To ensure the hook is actually calling bustCache
and showing the most recent data, a e2e testing tool like Cypress.io, which comes with applications scaffolded using vue-cli, can be used.
Component Guards
Component Guards are also easy to test, once you see them as decoupled, regular JavaScript functions. Let’s say we added a beforeRouteLeave
hook to <NestedRoute>
:
<script>
import { bustCache } from "@/bust-cache.js"
export default {
name: "NestedRoute",
beforeRouteLeave(to, from, next) {
bustCache()
next()
}
}
</script>
We can test this in exactly the same way as the global guard:
// ...
import NestedRoute from "@/components/NestedRoute.vue"
import mockModule from "@/bust-cache.js"
jest.mock("@/bust-cache.js", () => ({ bustCache: jest.fn() }))
it("calls bustCache and next when leaving the route", async () => {
const wrapper = shallowMount(NestedRoute);
const next = jest.fn()
NestedRoute.beforeRouteLeave.call(wrapper.vm, undefined, undefined, next)
await wrapper.vm.$nextTick()
expect(mockModule.bustCache).toHaveBeenCalled()
expect(next).toHaveBeenCalled()
})
While this style of unit test can be useful for immediate feedback during development, since routers and navigation hooks often interact with several components to achieve some effect, you should also have integration tests to ensure everything is working as expected.
- testing components conditionally rendered by Vue Router
- mocking Vue components using
jest.mock
andlocalVue
- using to mock a module
The source code for the test described on this page can be found and here.