Unit-Test-Vue-Pinia

# unit-test-vue-pinia

Use this skill to create or review unit tests for Vue components, composables, and Pinia stores. Keep tests small, deterministic, and behavior-first.

Workflow

1. Identify the behavior boundary first: component UI behavior, composable behavior, or store behavior.

2. Choose the narrowest test style that can prove that behavior.

3. Set up Pinia with the least powerful option that still covers the scenario.

4. Drive the test through public inputs such as props, form updates, button clicks, emitted child events, and store APIs.

5. Assert observable outputs and side effects before considering any instance-level assertion.

6. Return or review tests with clear behavior-oriented names and note any remaining coverage gaps.

Core Rules

- Test one behavior per test.

- Assert observable input/output behavior first (rendered text, emitted events, callback calls, store state changes).

- Avoid implementation-coupled assertions.

- Access `wrapper.vm` only in exceptional cases when there is no reasonable DOM, prop, emit, or store-level assertion.

- Prefer explicit setup in `beforeEach()` and reset mocks every test.

- Use checked-in reference material in `references/pinia-patterns.md` as the local source of truth for standard Pinia test setups.

Pinia Testing Approach

Use `references/pinia-patterns.md` first, then fall back to Pinia's testing cookbook when the checked-in examples do not cover the case.

Default pattern for component tests

Use `createTestingPinia` as a global plugin while mounting.

Prefer `createSpy: vi.fn` as the default for consistency and easier action-spy assertions.

const wrapper = mount(ComponentUnderTest, {
	global: {
		plugins: [
			createTestingPinia({
				createSpy: vi.fn,
			}),
		],
	},
});

By default, actions are stubbed and spied.

Use `stubActions: true` (default) when the test only needs to verify whether an action was called (or not called).

Accepted minimal Pinia setups

The following are also valid and should not be flagged as incorrect:

- `createTestingPinia({})` when the test does not assert Pinia action spy behavior.

- `createTestingPinia({ initialState: ... })` or `createTestingPinia({ stubActions: ... })` without `createSpy`, when the test only needs state seeding or action stubbing behavior and does not inspect generated spies.

- `setActivePinia(createTestingPinia(...))` in store/composable-focused tests (without mounting a component) when mocking/seeding dependent stores is needed.

Use `createSpy: vi.fn` when action spy assertions are part of the test intent.

Execute real actions only when needed

Use `stubActions: false` only when the test must validate the action's real behavior and side effects. Do not switch it on by default for simple "was called" assertions.

const wrapper = mount(ComponentUnderTest, {
	global: {
		plugins: [
			createTestingPinia({
				createSpy: vi.fn,
				stubActions: false,
			}),
		],
	},
});

Seed store state with `initialState`

const wrapper = mount(ComponentUnderTest, {
	global: {
		plugins: [
			createTestingPinia({
				createSpy: vi.fn,
				initialState: {
					counter: { n: 20 },
					user: { name: "Leia Organa" },
				},
			}),
		],
	},
});

Add Pinia plugins through `createTestingPinia`

const wrapper = mount(ComponentUnderTest, {
	global: {
		plugins: [
			createTestingPinia({
				createSpy: vi.fn,
				plugins: [myPiniaPlugin],
			}),
		],
	},
});

Getter override pattern for edge cases

const pinia = createTestingPinia({ createSpy: vi.fn });
const store = useCounterStore(pinia);

store.double = 999;
// @ts-expect-error test-only reset of overridden getter
store.double = undefined;

Pure store unit tests

Prefer pure store tests with `createPinia()` when the goal is to validate store state transitions and action behavior without component rendering. Use `createTestingPinia()` only when you need stubbed dependent stores, seeded test doubles, or actio