vue-testing-vitest
Skill2 starsChanged 35 days agoMITView on GitHub
Use when adding or fixing tests in a Vue 3 project with Vitest, @vue/test-utils or Playwright. Enforces testing composables and utils first, component tests by behaviour not markup, mocking at the api-module boundary, Pinia/router test setup that does not leak, and a small set of E2E flows kept fast.
In this repository13 other files it gives its agents.
- api-layer-axiosSkill
- element-plus-adminSkill
- nuxt3-appSkill
- pinia-stateSkill
- uni-app-cross-platformSkill
- vue2-to-vue3-migrationSkill
- vue3-compositionSkill
- vue-code-reviewSkill
- vue-forms-validationSkill
- vue-i18n-setupSkill
- vue-performanceSkill
- vue-router-authSkill
- wechat-miniprogramSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Unit suite stays under ~10 s locally: Use happy-dom unless a test needs jsdom features.
- Distinctive: line 54
Pick the lowest layer that proves the behaviour: If the bug is in a formatter, test the formatter, not the page that calls it.
- Distinctive: line 61
If it grew by more than a second, find out why.
- Very specific: line 112
Use a real createRouter with createMemoryHistory() only when guards themselves are under test.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Testing Vue 3 with Vitest and Playwright
This skill covers unit tests for composables, utils and stores, component
tests with @vue/test-utils, and a thin Playwright layer. "Good" means the
unit suite runs under ~10 s, a failing test names the broken behaviour, and
no test breaks when a class name changes. Do not apply it to generate tests
for every component; untested glue code is better than brittle snapshot
tests that get deleted in the next refactor.
Non-negotiables
- Test order of value: utils → composables → stores → components → E2E. Pure functions give the highest confidence per line of test. Components are tested only for behaviour a user can observe.
- No snapshot tests of rendered HTML. They fail on every markup change
and nobody reads the diff. Assert on text, emitted events, called mocks
and
aria/data-testtargets instead. - Select by
data-testor role, never by CSS class or Element Plus internal structure..el-table__rowchanges between minor versions;[data-test="row"]does not. - Mock the API module, not axios.
vi.mock('@/api/user')keeps tests independent of the request layer and the interceptors. Mocking axios means re-testing the interceptor in every component test. - Use
createTestingPinia({ stubActions: false })only when the action logic is under test; default stubbed actions keep component tests about the component. - Every async test awaits
flushPromises()(ornextTick) before asserting. A green test that asserts before the promise resolves is testing nothing. - Element Plus is registered once in a global setup file, not per test.
Stub heavy components (
ElDialog,ElSelectwithteleport) withglobal.stubswhen their internals are irrelevant. - Unit suite stays under ~10 s locally. Use
happy-domunless a test needsjsdomfeatures; put slow integration tests in a separatetest:integrationscript. - Coverage targets by layer, not a global number. Utils and composables ≥ 90% lines; stores ≥ 80%; components judged by behaviour cases, not percent. A global 80% gate pushes people to write worthless tests.
- E2E covers 3–5 critical journeys (login, the main CRUD page, a permission-denied path, logout). Everything else belongs in unit tests because a Playwright run costs minutes.
- Test names read as a sentence:
it('drops the response when a newer request finished first'). "works" and "test1" are not names.
Workflow
- Look at the existing setup:
vitest.config.ts(environment, setup files, aliases),test/setup.ts(global plugins), where tests live (__tests__/vs*.spec.tsbeside the file). Match it. - Pick the lowest layer that proves the behaviour. If the bug is in a formatter, test the formatter, not the page that calls it.
- Write the failing test first with the real inputs from the bug report, run it, watch it fail for the right reason.
- Mock only the boundary: the api module,
useRouterwhen navigation is asserted, time withvi.useFakeTimers()for debounce/polling. - Run the whole unit suite, not just the new file, and check the time. If it grew by more than a second, find out why.
- Add an E2E test only if the change touches a critical journey, and run it against the dev server with seeded data, never against a shared environment.
Patterns
Composable with async loader
vi.mock('@/api/user', () => ({ listUsers: vi.fn() }))
import { listUsers } from '@/api/user'
it('drops the response when a newer request finished first', async () => {
const slow = deferred<Page>(), fast = deferred<Page>()
vi.mocked(listUsers).mockReturnValueOnce(slow.promise).mockReturnValueOnce(fast.promise)
const { rows, load } = useList(listUsers)
load({ q: 'a' }); load({ q: 'ab' })
fast.resolve({ items: [{ id: 2 }], total: 1 })
slow.resolve({ items: [{ id: 1 }], total: 1 })
await flushPromises()
expect(rows.value.map((r) => r.id)).toEqual([2])
})deferred() is a 5-line helper that exposes resolve; write it once in
test/helpers.ts.
Component test by behaviour
const wrapper = mount(UserList, {
global: { plugins: [createTestingPinia(), ElementPlus], stubs: { ElDialog: true } },
})
await flushPromises()
await wrapper.get('[data-test="delete-1"]').trigger('click')
expect(wrapper.emitted('delete')).toEqual([[1]])Assert the emitted event, not that a confirm box appeared with a specific class.
Router in component tests
const push = vi.fn()
vi.mock('vue-router', async (orig) => ({ ...(await orig()), useRouter: () => ({ push }) }))
// ...
expect(push).toHaveBeenCalledWith({ name: 'UserDetail', params: { id: 1 } })Use a real createRouter with createMemoryHistory() only when guards
themselves are under test.
Fake timers for debounce
vi.useFakeTimers()
keyword.value = 'a'; keyword.value = 'ab'
await vi.advanceTimersByTimeAsync(300)
expect(listUsers).toHaveBeenCalledTimes(1)
vi.useRealTimers()Global setup file
// test/setup.ts
import { config } from '@vue/test-utils'
import ElementPlus from 'element-plus'
config.global.plugins = [ElementPlus]
config.global.stubs = { Teleport: true, Transition: true }Stubbing Teleport keeps dialog content inside the wrapper so find works.
Playwright critical path
test('user without permission sees 403, not a blank page', async ({ page }) => {
await loginAs(page, 'viewer')
await page.goto('/system/users')
await expect(page.getByRole('heading', { name: '403' })).toBeVisible()
})loginAs sets the token via the API, not the UI, so each test costs one
request instead of a form fill.
Pitfalls
| Symptom | Cause | Fix |
| Test passes but behaviour broken | Assertion ran before promise resolved | await flushPromises() |
find returns nothing for dialog content | Rendered via Teleport outside wrapper | Stub Teleport globally or attachTo: document.body |
| Tests pass alone, fail together | Pinia or mocks shared across files | setActivePinia(createPinia()) in beforeEach, vi.restoreAllMocks() |
| Every markup tweak breaks 40 tests | Snapshot tests | Delete them, assert behaviour |
| Test breaks on Element Plus upgrade | Selectors on .el-* internals | data-test / getByRole |
| Suite takes 90 s | jsdom everywhere, E2E in unit script | happy-dom, separate scripts |
useRouter() is undefined | Component uses router, no mock | Mock vue-router or install a memory router |
| Debounce test waits 300 ms real time | Real timers | vi.useFakeTimers() + advanceTimersByTimeAsync |
| Coverage gate forces junk tests | Global 80% rule | Per-layer thresholds in vitest.config.ts |
| E2E flaky on CI | Shared backend, unseeded data | Local server + seeded fixtures, API-based login |
ResizeObserver is not defined | happy-dom lacks it, Element Plus table needs it | Polyfill stub in setup.ts |
Before you finish
- New test fails without the fix and passes with it (ran both).
- No snapshot of HTML; selectors are
data-testor roles. - Mocks sit at the api-module boundary;
vi.restoreAllMocks()runs between tests. - Every async assertion is preceded by
flushPromises()/nextTick. - Unit suite still runs under ~10 s; slow tests moved to
test:integration. - Test names describe the behaviour in a sentence.
- E2E added only for a critical journey, logs in via API, uses seeded data.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

