agentleFS
caiqianhacaiqianha/vue-skills/skills/vue-testing-vitest/SKILL.md

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.

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
  1. Very specific:

    Unit suite stays under ~10 s locally: Use happy-dom unless a test needs jsdom features.

    line 37
  2. Distinctive:

    Pick the lowest layer that proves the behaviour: If the bug is in a formatter, test the formatter, not the page that calls it.

    line 54
  3. Distinctive:

    If it grew by more than a second, find out why.

    line 61
  4. Very specific:

    Use a real createRouter with createMemoryHistory() only when guards themselves are under test.

    line 112

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-test targets instead.
  • Select by data-test or role, never by CSS class or Element Plus internal structure. .el-table__row changes 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() (or nextTick) 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, ElSelect with teleport) with global.stubs when their internals are irrelevant.
  • Unit suite stays under ~10 s locally. Use happy-dom unless a test needs jsdom features; put slow integration tests in a separate test:integration script.
  • 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

  1. Look at the existing setup: vitest.config.ts (environment, setup files, aliases), test/setup.ts (global plugins), where tests live (__tests__/ vs *.spec.ts beside the file). Match it.
  2. Pick the lowest layer that proves the behaviour. If the bug is in a formatter, test the formatter, not the page that calls it.
  3. Write the failing test first with the real inputs from the bug report, run it, watch it fail for the right reason.
  4. Mock only the boundary: the api module, useRouter when navigation is asserted, time with vi.useFakeTimers() for debounce/polling.
  5. 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.
  6. 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

SymptomCauseFix
Test passes but behaviour brokenAssertion ran before promise resolvedawait flushPromises()
find returns nothing for dialog contentRendered via Teleport outside wrapperStub Teleport globally or attachTo: document.body
Tests pass alone, fail togetherPinia or mocks shared across filessetActivePinia(createPinia()) in beforeEach, vi.restoreAllMocks()
Every markup tweak breaks 40 testsSnapshot testsDelete them, assert behaviour
Test breaks on Element Plus upgradeSelectors on .el-* internalsdata-test / getByRole
Suite takes 90 sjsdom everywhere, E2E in unit scripthappy-dom, separate scripts
useRouter() is undefinedComponent uses router, no mockMock vue-router or install a memory router
Debounce test waits 300 ms real timeReal timersvi.useFakeTimers() + advanceTimersByTimeAsync
Coverage gate forces junk testsGlobal 80% rulePer-layer thresholds in vitest.config.ts
E2E flaky on CIShared backend, unseeded dataLocal server + seeded fixtures, API-based login
ResizeObserver is not definedhappy-dom lacks it, Element Plus table needs itPolyfill 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-test or 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.