home / skills / vuejs-ai / skills / vue-testing-best-practices

vue-testing-best-practices skill

safe

This skill helps you implement Vue 3 testing practices with Vitest, Vue Test Utils, and Playwright to improve reliability and maintainability.

npx playbooks add skill vuejs-ai/skills --skill vue-testing-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (12)

SKILL.md

2.1 KB

---
name: vue-testing-best-practices
version: 1.0.0
license: MIT
author: github.com/vuejs-ai
description: Use for Vue.js testing. Covers Vitest, Vue Test Utils, component testing, mocking, testing patterns, and Playwright for E2E testing.
---

Vue.js testing best practices, patterns, and common gotchas.

### Testing
- Setting up test infrastructure for Vue 3 projects → See [testing-vitest-recommended-for-vue](reference/testing-vitest-recommended-for-vue.md)
- Tests keep breaking when refactoring component internals → See [testing-component-blackbox-approach](reference/testing-component-blackbox-approach.md)
- Tests fail intermittently with race conditions → See [testing-async-await-flushpromises](reference/testing-async-await-flushpromises.md)
- Composables using lifecycle hooks or inject fail to test → See [testing-composables-helper-wrapper](reference/testing-composables-helper-wrapper.md)
- Getting "injection Symbol(pinia) not found" errors in tests → See [testing-pinia-store-setup](reference/testing-pinia-store-setup.md)
- Components with async setup won't render in tests → See [testing-suspense-async-components](reference/testing-suspense-async-components.md)
- Snapshot tests keep passing despite broken functionality → See [testing-no-snapshot-only](reference/testing-no-snapshot-only.md)
- Choosing end-to-end testing framework for Vue apps → See [testing-e2e-playwright-recommended](reference/testing-e2e-playwright-recommended.md)
- Tests need to verify computed styles or real DOM events → See [testing-browser-vs-node-runners](reference/testing-browser-vs-node-runners.md)
- Testing components created with defineAsyncComponent fails → See [async-component-testing](reference/async-component-testing.md)
- Teleported modal content can't be found in wrapper queries → See [teleport-testing-complexity](reference/teleport-testing-complexity.md)

## Reference

- [Vue.js Testing Guide](https://vuejs.org/guide/scaling-up/testing)
- [Vue Test Utils](https://test-utils.vuejs.org/)
- [Vitest Documentation](https://vitest.dev/)
- [Playwright Documentation](https://playwright.dev/)

Overview

This skill collects practical best practices for testing Vue 3 applications using Vitest, Vue Test Utils, and Playwright. It focuses on reliable component testing, composable testing, mocking patterns, async and Suspense handling, and end-to-end guidance. The content helps teams reduce flaky tests and improve test coverage quality.

How this skill works

The skill inspects common testing pain points and recommends concrete fixes: black-box component testing, proper async/await and flush handling, helper wrappers for composables, Pinia test setup, and strategies for teleports and async components. It also recommends choosing Playwright for deterministic E2E runs and when to use browser vs Node runners for style and real-event assertions.

When to use it

Setting up or standardizing test infrastructure for a Vue 3 project
Refactoring components that break existing tests due to internal changes
Debugging intermittent or race-condition test failures
Testing composables that rely on lifecycle hooks, provide/inject, or Pinia
Writing E2E tests and deciding between Playwright and other runners
Verifying DOM behaviors that need a real browser environment

Best practices

Prefer black-box tests that assert public output and behavior, not internals
Use Vitest with Vue Test Utils as the default unit/component stack
Await asynchronous updates and use utilities like flushPromises or nextTick to avoid race conditions
Wrap composables in lightweight helper components to provide lifecycle, props, and injection contexts
Initialize Pinia and other global plugins in test setup to avoid injection errors
Favor Playwright for E2E where deterministic cross-browser scenarios and real DOM/style checks are required

Example use cases

Migrating a legacy Vue app to Vitest and standardizing test patterns across the repo
Converting brittle snapshot-heavy tests into behavior-driven component tests
Testing a composable that uses onMounted and provide/inject by using a test wrapper component
Reproducing and fixing intermittent test failures caused by unawaited async effects
Writing E2E tests for form flows and file uploads with Playwright for stable CI runs

FAQ

Why do my component tests break when I refactor internals?

Tests that assert internal implementation details are brittle. Write tests that assert rendered output, emitted events, and public behavior so refactors that preserve behavior won’t break tests.

When should I use a real browser test runner?

Use a browser runner (Playwright) when you need accurate layout, computed styles, CSS-driven behavior, or real DOM events; use Node runners for fast unit tests that don't depend on browser APIs.