---
icon: flask
---
# test-utils
Unit testing utilities for VuePress.
`vuepress/client` imports generated modules (`@internal/*`) and compile-time defines (`__VUEPRESS_DEV__`, ...) at module scope, so it cannot be imported in a unit test. This package replaces them, so that the client code of a plugin or a theme can be rendered and interacted with in a unit test, instead of running the heavy e2e tests.
## Usage
```bash
npm i -D @vuepress/test-utils@next @vue/test-utils happy-dom
```
```ts title="vitest.config.ts"
import { vuepressTestPlugin } from '@vuepress/test-utils'
import { defineConfig } from 'vitest/config'
export default defineConfig({
plugins: [vuepressTestPlugin()],
})
```
To test `.vue` single file components, add a Vue plugin (e.g. `@vitejs/plugin-vue`) to `plugins` as usual.
If your packages use a module alias that cannot be expressed by `resolve.alias` (e.g. the `@theme/*` alias of `@vuepress/theme-default`, which may resolve to different directories), pass a `resolve` function to the plugin.
```ts title="vitest.config.ts"
export default defineConfig({
plugins: [
vue(),
vuepressTestPlugin({
resolve: (id) =>
id.startsWith('@theme/') ? resolveThemeFile(id) : undefined,
}),
],
})
```
## Guide
### Rendering client code
`renderVuePress()` renders the client app to a string, and works in the `node` environment. It is the cheapest way to assert the markup of every option combination.
```ts
import { renderVuePress } from '@vuepress/test-utils/client'
const html = await renderVuePress({
content: MyComponent,
page: { path: '/', title: 'Home' },
site: { title: 'My Site' },
})
```
`mountVuePress()` mounts the client app with `@vue/test-utils`, which requires a DOM environment:
```ts
// @vitest-environment happy-dom
import { mountVuePress } from '@vuepress/test-utils/client'
const wrapper = await mountVuePress({
content: MyComponent,
page: { path: '/', title: 'Home' },
})
await wrapper.find('.my-button').trigger('click')
```
::: tip
Put `// @vitest-environment happy-dom` at the top of the file, before every import, otherwise Vitest does not read it. `renderVuePress()` does not need it, so prefer it for the tests that do not interact with the DOM.
:::
Both accept the same options as `createTestClient()`, which returns a client that can render and mount multiple times, and exposes the client data and the router:
```ts
const client = await createTestClient({ page: { path: '/', title: 'Home' } })
expect(await client.renderToString()).toContain('Home')
await client.router.push('/other/')
```
The `content` option is the content of the current page (the page chunk), and the layout renders it. `vuepress/client`'s `Content` component is the default layout, so the content is rendered directly when no layout is given. To render a single component without the layout and the root components of the client configs, use the `rootComponent` option instead.
`clientConfigs` accepts the client configs of the plugins and the theme, and applies their `setup`, `enhance`, `layouts` and `rootComponents`, which is required when a composable relies on a provider of a client config. For example, the theme data of `@vuepress/theme-default` is read through `useThemeData()`, which is provided by the theme data plugin, so its client config must be passed to `clientConfigs`.
### Testing option combinations
Plugin options are passed to the client through `define` globals rather than through props. `collectClientDefines()` reads them from a real plugin, and `stubClientDefines()` applies them to `globalThis`, exactly like the bundler does.
```ts
import {
collectClientDefines,
createTestApp,
stubClientDefines,
} from '@vuepress/test-utils'
import { mountVuePress } from '@vuepress/test-utils/client'
import myClientConfig from '../src/client/config.js'
import { myPlugin } from '../src/node/index.js'
const app = await createTestApp({ plugins: [myPlugin({ duration: 3000 })] })
const restore = stubClientDefines(await collectClientDefines(app))
const wrapper = await mountVuePress({
clientConfigs: [myClientConfig],
content: '...',
})
restore()
```
::: tip
A module that reads a define at module scope must be imported after `stubClientDefines()`. Use `vi.resetModules()` with a dynamic import in that case.
:::
### Stubbing generated modules
VuePress generates the client modules that a plugin imports at build time: the `@internal/*` modules, and the `@temp/*` modules created by a generated client config (e.g. `@temp/revealjs/index.js` of `@vuepress/plugin-revealjs`). They do not exist in a unit test, so a module that imports them cannot be imported at all. `stubModule()` registers the exports of such a module and makes it resolvable, in both the `node` and the `happy-dom` environment.
```ts
import { stubModule, stubTempModule } from '@vuepress/test-utils'
const restoreNotice = stubModule('@internal/noticeOptions', {
NOTICE_OPTIONS: [{ path: '/', title: 'Notice' }],
})
const restoreReveal = stubTempModule('revealjs', {
useRevealJs: () => Promise.resolve([Reveal]),
})
vi.resetModules()
const { useNoticeOptions } =
await import('../src/client/composables/useNoticeOptions.js')
restoreNotice()
restoreReveal()
```
`stubTempModule(name, ...)` is a shortcut for `stubModule('@temp//index.js', ...)`. Any module id can be stubbed, including a sub-path alias that only exists at build time, such as `@vuepress/plugin-comment/service` of `@vuepress/plugin-comment`.
The module id is mapped to a generated file in a temporary directory: the id is appended to that directory, and a `.js` extension is added when the id does not end with `.js`. The id, the export names and the module that imports them must match the real generated module. Only identifiers and `default` are supported as export names, because the generated module re-exports them.
::: warning
Vite resolves imports when a module is transformed, which happens before the test runs. The module that imports the stubbed module must therefore be imported dynamically after `stubModule()`, with `vi.resetModules()` when it may already be cached. A statically imported module cannot be stubbed.
:::
For a module that must be imported statically, register the alias in the repo config with the `resolve` option of `vuepressTestPlugin()`:
```ts title="vitest.config.ts"
const CLIENT_ALIASES: Record = {
// A sub-path alias created by a plugin at build time
'@vuepress/plugin-comment/service':
'./plugins/blog/plugin-comment/src/client/components/WalineComment.js',
}
export default defineConfig({
plugins: [vuepressTestPlugin({ resolve: (id) => CLIENT_ALIASES[id] })],
})
```
### Testing the color mode
`setColorMode()` stubs the two things that `@vuepress/theme-default` reads to resolve the dark mode: the `(prefers-color-scheme: dark)` media query and the `vuepress-color-scheme` local storage key. It also sets `data-theme` on ``. All other media queries are forwarded to the real `window.matchMedia()`.
```ts
// @vitest-environment happy-dom
import { setColorMode } from '@vuepress/test-utils/client'
const restore = setColorMode('dark')
const wrapper = await mountVuePress({ rootComponent: MyComponent })
expect(wrapper.find('.my-button').classes()).toContain('dark')
restore()
```
Pass `{ storage: 'auto' }` to keep the stored value at `auto` while the media query still reports dark, which exercises the `prefers-color-scheme` branch of `useDarkMode()`.
### Testing Node side code
`createTestApp()` builds a VuePress app with a temporary source directory, an empty theme and an empty bundler, so that the plugin hooks, the page resolution and the markdown extensions can be tested without a real site.
```ts
import {
createTestApp,
createTestMarkdown,
mockLogger,
} from '@vuepress/test-utils'
const app = await createTestApp({
plugins: [myPlugin()],
files: { 'README.md': '# Home' },
})
expect(app.pages.map(({ path }) => path)).toContain('/')
app.cleanup()
```
`createTestMarkdown()` creates a markdown-it instance with the VuePress defaults, `createTestPage()` creates a page without a source file, and `mockLogger()` silences the VuePress logs and returns the spies for assertions.
## Options
### vuepressTestPlugin
:::: fields
@`base` type=string default=`'/'`
The value of `__VUEPRESS_BASE__`.
@`dev` type=boolean
The value of `__VUEPRESS_DEV__`. The development mode enables HMR branches, which access `__VUE_HMR_RUNTIME__` that does not exist in unit tests.
@`version` type=string
The value of `__VUEPRESS_VERSION__`. It is read from the installed `vuepress` package by default.
@`resolve` type=`(id: string) => string | undefined`
Resolve the module ids that `resolve.alias` cannot express, e.g. `@theme/*` of `@vuepress/theme-default`, or a sub-path alias that only exists at build time such as `@vuepress/plugin-comment/service`. It is called for every import, and should return the file path or `undefined`. A module registered with `stubModule()` is resolved before it is called.
::::
### setColorMode options
Used by `setColorMode()`.
:::: fields
@`storageKey` type=string default=`'vuepress-color-scheme'`
The local storage key that holds the color mode.
@`storage` type=`'auto' | 'light' | 'dark'`
The value to store under `storageKey`. It defaults to the `colorMode` argument.
::::
### Test client options
Shared by `createTestClient()`, `renderVuePress()` and `mountVuePress()`.
:::: fields
@`content` type=`Component | string`
The content of the current page, i.e. the page chunk. A string is rendered as raw HTML.
@`rootComponent` type=Component
The root component. When it is given, the layout and the root components of the client configs are skipped.
@`page` type=TestPageOptions
The current page.
@@`page.path` type=string default=`'/'`
The route path of the page.
@@`page.title` type=string default=`''`
The title of the page.
@@`page.lang` type=string default=`''`
The language of the page. It falls back to the language of the site locale.
@@`page.frontmatter` type=PageFrontmatter
The frontmatter of the page.
@@`page.data` type=`Record`
Extra page data, e.g. `filePathRelative`.
@`route` type=string
The route path of the current page. It defaults to `page.path`.
@`site` type=`Partial`
The site data. For example, its `locales` field switches the site locale data according to the route path.
@`layouts` type=`Record`
The layout components. Its defaults are `Content` for `Layout` and `NotFound`.
@`routes` type=`Record`
Extra routes. Each route accepts `component` and `pageData`.
@`redirects` type=`Record`
The redirects.
@`themeData` type=`Record`
The theme data, read by `useThemeData()` of `@vuepress/plugin-theme-data/client`.
@`clientConfigs` type=`ClientConfig[]`
The client configs to apply. Their `setup`, `enhance`, `layouts` and `rootComponents` all take effect.
@`ssr` type=boolean
Whether to simulate the SSR mode. It defaults to `true` for `renderToString()` and `false` for `mount()`.
::::
### Test app options
Used by `createTestApp()`. It also accepts the other fields of the VuePress app config.
:::: fields
@`files` type=`Record`
The markdown files to generate in the source directory. The key is the relative path.
@`source` type=string
The source directory. It defaults to a temporary directory, which is removed by `app.cleanup()`.
@`theme` type=Theme default=`emptyTheme`
The theme of the app.
@`init` type=boolean
Whether to initialize the app.
@`prepare` type=boolean
Whether to prepare the app after the initialization.
::::