web-testing-vue-test-utils

Quick Guide: mount() renders a component with its children; shallowMount() stubs them all and is the exception rather than the default. Query with get() when the element must exist and find() when it may not, using data-test attributes rather than classes. Every DOM-updating method returns a promise and is awaited; anything Vue's reactivity does not track — a request, a timer — needs flushPromises() as well. A component's environment arrives through the global mounting options.

Detailed Resources:

• examples/core.md — mounting, slots, get/find/findAll, trigger, setValue
• examples/async.md — flushPromises, nextTick, debounced input, async setup() under Suspense
• examples/composables.md — through a component, in isolation, and with injected dependencies
• examples/mocking.md — the four global seams: plugins, stubs, mocks, provide — and a custom mount that composes them
• reference.md — wrapper API tables, mounting options, emitted-event patterns, debug checklist

---

Which path applies

• A component is the subject — mount it and drive the wrapper; examples/core.md.
• A composable is the subject — mount a minimal component that calls it, so it runs inside a real setup scope; examples/composables.md. Calling a composable outside a component works only for ones that register no lifecycle hooks and inject nothing.
• The subject has an async setup() — it must be mounted inside Suspense, or it never resolves; examples/async.md.

---

<critical_requirements>

Before writing Vue Test Utils code

Await every DOM-updating method — trigger(), setValue(), setProps(), setData(). Each returns a promise that resolves after Vue has flushed, so an un-awaited call leaves the assertion looking at the pre-update DOM.

Call flushPromises() after anything Vue's reactivity does not own — a request, a timer callback, a promise chain started in onMounted. Awaiting the interaction flushes Vue's queue and nothing else.

Reach for mount() first, and treat shallowMount() as the exception. Stubbing every child changes how the component behaves, so a shallow test passes for a tree that does not render.

Select with data-test attributes. Classes and ids belong to styling and move under a restyle; a data-test attribute is a stated contract that a reader can see is load-bearing.

Supply the component's environment through the global mounting options — plugins, stubs, mocks, provide. That is the seam the library gives you, and it keeps the arrangement visible at the mount rather than hidden in module-level substitution.

</critical_requirements>

---

Auto-detection: @vue/test-utils, mount, shallowMount, VueWrapper, DOMWrapper, wrapper.get, wrapper.find, findAll, findComponent, findAllComponents, getComponent, trigger, setValue, setProps, setData, flushPromises, emitted, enableAutoUnmount, attachTo, renderStubDefaultSlot, config.global

Applies to:

• Mounting a Vue component and asserting on what it rendered
• Driving clicks, typing, selection and keyboard events through the wrapper
• Asserting on emitted events and their payloads
• Deciding between full mount, selective stubs and shallow rendering
• Testing a composable, in a component or in isolation
• Supplying plugins, stubs, global properties and injected values at mount time

Handled elsewhere:

• Test runner mechanics — the file's describe/it, the assertion API, module substitution, mock functions and fake timers all belong to whatever runs the file
• Store design and its own test helpers — a store's testing plugin is installed through global.plugins, and how to configure it is settled by whoever owns the store
• Route definition and navigation guards — a router installs as a plugin like any other
• Journeys spanning navigations and a real backend — browser-driven end-to-end coverage
• Whether the rendered result still looks right — pixel comparison against an approved image

---

<philosophy>

Philosophy

Vue's DOM updates are asynchronous, and the library's API is shaped around that one fact. trigger, setValue, setProps and setData all return promises for the same reason: the effect of the change is not observable on the line after it. Most flaky Vue component tests are a missing await on one of those four.

Two async queues, two tools. Awaiting a wrapper method flushes Vue's own render queue. flushPromises() drains the microtask queue, which is where a resolved request or a settled promise chain is waiting. A component that fetches on mount needs the second even though nothing was triggered.

Stubbing is a dial, not a switch. shallowMount is the far end of it — every child replaced, slots inert, integration coverage gone. Stubbing the one heavy child by name keeps the rest of the tree real and usually solves the actual problem, which is a chart library or a network call rather than depth.

</philosophy>

---

<patterns>

Core patterns

Pattern 1: Mounting

import { mount, shallowMount } from "@vue/test-utils";

// Default: children render, slots work, events bubble
const wrapper = mount(TodoList, {
  props: { todos: [{ id: 1, text: "Test", done: false }] },
});

// Every child stubbed - reach for this only when depth itself is the problem
const shallow = shallowMount(TodoList, { props: { todos: [] } });

// Usually better than shallow: stub the one child that misbehaves
const selective = mount(Dashboard, {
  global: { stubs: { HeavyChartWidget: { template: "<div />" } } },
});

Full code: examples/core.md

Pattern 2: Querying the Wrapper

get* throws with a useful message when the element is missing; find* returns an empty wrapper you then check with .exists(). The same split applies to getComponent / findComponent.

const input = wrapper.get('[data-test="search-input"]'); // must exist
expect(wrapper.find('[data-test="error"]').exists()).toBe(false); // may not exist
expect(wrapper.findAll('[data-test="result"]')).toHaveLength(3);

expect(wrapper.getComponent(ChildComponent).props("message")).toBe("Hello");

Using find() where get() was meant is the quiet failure: the empty wrapper satisfies nothing, and the assertion after it reports a confusing type error rather than "element not found".

Full code: examples/core.md

Pattern 3: Interaction and Emitted Events

await wrapper.get('[data-test="email"]').setValue("test@example.com");
await wrapper.get('[data-test="form"]').trigger("submit.prevent");

expect(wrapper.emitted("submit")).toBeTruthy();
expect(wrapper.emitted("submit")![0]).toEqual([{ email: "test@example.com" }]);

emitted() accumulates across the whole test, so index into it rather than asserting on the array as a whole after several interactions.

Full code: examples/core.md

Pattern 4: flushPromises for Untracked Async

import { mount, flushPromises } from "@vue/test-utils";

const wrapper = mount(UserProfile, { props: { userId: 1 } });

expect(wrapper.find('[data-test="loading"]').exists()).toBe(true);

await flushPromises(); // the request settles, then Vue re-renders

expect(wrapper.get('[data-test="user-name"]').text()).toBe("John Doe");

flushPromises() drains microtasks only. A setTimeout needs the runner's fake timers advanced first, and then flushPromises() for whatever the callback started.

Full code: examples/async.md

Pattern 5: Testing Composables

Mount a component whose only job is to call the composable, so lifecycle hooks and inject work as they do in production.

function withSetup<T>(composable: () => T) {
  let result!: T;
  const wrapper = mount(
    defineComponent({ setup: () => ((result = composable()), () => null) }),
  );
  return { result, unmount: () => wrapper.unmount() };
}

const { result, unmount } = withSetup(() =>
  useLocalStorage("draft", "initial"),
);

Where the composable is inseparable from its UI, render a small template around it and assert on the DOM instead — the reactivity is then covered rather than assumed.

Full code: examples/composables.md

Pattern 6: The global Mounting Options

Four seams, each for a different kind of dependency, all set at the mount and all settable project-wide through config.global.

mount(Component, {
  global: {
    plugins: [
      /* anything installed with app.use() - a store, a router, an i18n instance */
    ],
    stubs: { RouterLink: true, HeavyChart: { template: "<div />" } },
    mocks: { $t: (key: string) => key }, // global properties the template reads
    provide: { [THEME_KEY]: { theme: ref("light") } }, // what an ancestor would provide
  },
});

Wrap these in a custom mount once, so a test states only what makes it different.

Full code: examples/mocking.md

</patterns>

---

<red_flags>

Red flags

Breaks at runtime:

• A trigger(), setValue(), setProps() or setData() without await — the assertion reads the DOM before Vue has flushed, so the test passes or fails by timing
• No flushPromises() after a request resolves — the loading branch is still rendered when the assertion runs
• setData() on a component written with the Composition API — it only reaches an Options API data() function, so the call silently changes nothing
• A component with an async setup() mounted directly instead of inside Suspense — it never resolves and the wrapper stays on the fallback
• isVisible() without attachTo: document.body — the element is not in a rendered document, so visibility cannot be computed correctly
• trigger("click") on a disabled element — the browser drops it, and so does the library; that is correct behaviour rather than a bug to work around

Surprising behaviour:

• shallowMount stubs every child including ones from a component library, so a test can pass against a tree that renders nothing
• find() returns an empty wrapper rather than throwing, which turns a missing element into a confusing error one line later
• emitted() accumulates for the lifetime of the wrapper — asserting a length after several interactions counts all of them
• setValue() applies only to <input>, <textarea> and <select>; on anything else it is a no-op
• trigger() already awaits nextTick, so an extra await nextTick() after it is redundant
• Reaching into wrapper.vm to call a method or read state couples the test to the implementation; drive the component through the DOM instead
• A wrapper mounted with attachTo stays in the document until unmounted — register enableAutoUnmount once rather than remembering per test

</red_flags>