runtime-test

Active contributors: Evan You

Purpose

@vue/runtime-test is the smallest runtime: a custom renderer that produces plain JavaScript objects instead of DOM nodes. It exists to make Vue's own renderer/scheduler/component tests fast and DOM-free. Any test that does not specifically need browser behavior should use it; the contributing guide is explicit about this.

Directory layout

packages/runtime-test/src/
├── index.ts          # createApp/render/serializeInner re-exports
├── nodeOps.ts        # in-memory Node tree
├── patchProp.ts      # mutates props on the JS object
├── serialize.ts      # serializeInner / serialize: pretty-print to a string
└── triggerEvent.ts   # synthetic event dispatch into the JS tree

Total source: ~400 lines across 5 files. The __tests__ directory has a single spec that exercises serialize itself; everything else in the runtime-core test suite consumes this package.

How it works

nodeOps.ts defines a TestNode discriminated union (TestElement, TestText, TestComment) where each node carries type, id, tag, props, children, and eventListeners fields. The renderer options exported from this file implement create/insert/remove against that object tree. The result is a JS data structure shaped like a DOM, but with no real DOM behind it.

import { h, nodeOps, render, serializeInner } from '@vue/runtime-test';

const root = nodeOps.createElement('div');
render(h('div', 'hello'), root);
expect(serializeInner(root)).toBe('<div>hello</div>');

serialize.ts walks the tree and emits a stable, minimal HTML-like string that is the recommended assertion form. triggerEvent.ts synthesizes events and walks the listener list — handy for testing event handler invocation without jsdom.

When to use it

• You're writing a renderer test (mount, patch, unmount).
• You're writing a scheduler test (flushJobs, nextTick, ordering).
• You're writing a component lifecycle test.
• You're writing a directive test that doesn't depend on real DOM behavior.

When not to use it:

• Tests for v-model on real form controls — use jsdom + runtime-dom.
• Tests for hydration — use jsdom + runtime-dom.
• Tests for useCssVars, custom elements, focus management — use jsdom + runtime-dom.

Integration points

• Imported only by other packages' test files. It is not published to npm.
• Consumes @vue/runtime-core via createRenderer({ nodeOps, patchProp }). Anything new you add to RendererOptions needs a stub here too.

Entry points for modification

• New RendererOptions method? Stub it in nodeOps.ts.
• New testing helper? Add to the index.ts and use it from runtime-core's __tests__.
• New event modifier? Make sure triggerEvent.ts propagates stopPropagation etc.