Registry / testing / vue3-snapshot-serializer

vue3-snapshot-serializer

library2.13.2jsnpmunverified

Vue 3 Snapshot Serializer is a library designed to enhance snapshot testing for Vue 3 components within Vitest and Jest environments. It is currently at version 2.13.2 and actively maintained, with frequent minor releases incorporating bug fixes and new features. The library focuses on providing cleaner, more readable snapshots by intelligently handling Vue-specific elements like scoped styles, dynamic attributes, and prop serialization. A key differentiator is its explicit support for both `@vue/test-utils` and `@testing-library/vue`, offering flexible testing approaches. It directly addresses common snapshot noise, making tests more robust and less prone to irrelevant failures. This package is exclusively for Vue 3 projects, with a separate serializer available for Vue 2.

testing

npm install vue3-snapshot-serializer

github ↗package ↗

INSTALL

IMPORT

SIG · VUE3-SNAPSHOT-SERI

vue3-snapshot-serializer

testingjavascriptv2.13.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serializer

✓ import * as serializer from 'vue3-snapshot-serializer';

✗ const serializer = require('vue3-snapshot-serializer');

For ESM setups (e.g., Vitest's `setupFiles`), import the entire module. For CommonJS (e.g., older Jest configs), `require` is used.

global.vueSnapshots

✓ global.vueSnapshots = { removeComments: true, sortAttributes: true };

Configuration is managed via a global object. This object does not need to be imported; it's set directly on the `global` (or `globalThis`) object in your test setup file.

snapshotSerializers

✓ // vitest.config.js or jest.config.js export default defineConfig({ test: { snapshotSerializers: ['./node_modules/vue3-snapshot-serializer/index.js'] } });

✗ import serializer from 'vue3-snapshot-serializer'; // This is not how serializers are added to config

Snapshot serializers are typically configured in your `vitest.config.js` or `jest.config.js` via a file path, not imported directly in the config.

This quickstart demonstrates how to set up `vue3-snapshot-serializer` with Vitest, configure global snapshot settings to clean up output, and perform a basic component snapshot test.

/* vitest.setup.ts */ import { expect } from 'vitest'; import * as vue3SnapshotSerializer from 'vue3-snapshot-serializer'; // Add the serializer expect.addSnapshotSerializer(vue3SnapshotSerializer); // Configure global settings for cleaner snapshots global.vueSnapshots = { removeComments: true, // Remove HTML comments removeDataTest: true, // Remove 'data-test' attributes removeDataTestid: true, // Remove 'data-testid' attributes removeDataVId: true, // Remove Vue's data-v-xxx attributes from scoped styles sortAttributes: true, // Sort attributes alphabetically for consistent snapshots formatter: 'diffable', // Use the 'diffable' formatter for improved readability }; /* MyComponent.vue */ <template> <div class="container" data-test="my-container">  <p :style="{ color: dynamicColor }" data-testid="content">Hello {{ name }}!</p> <ChildComponent :value="{ a: 1, b: 'test' }" some-prop="static" /> </div> </template> <script setup lang="ts"> import { ref } from 'vue'; import ChildComponent from './ChildComponent.vue'; const name = ref('World'); const dynamicColor = ref('red'); </script> /* ChildComponent.vue */ <template> <span class="child">{{ value.b }}</span> </template> <script setup lang="ts"> defineProps({ value: Object, someProp: String, }); </script> /* MyComponent.test.ts */ import { mount } from '@vue/test-utils'; import { describe, it, expect } from 'vitest'; import MyComponent from './MyComponent.vue'; describe('MyComponent', () => { it('renders correctly', () => { const wrapper = mount(MyComponent); expect(wrapper.html()).toMatchSnapshot(); }); });

Debug

Known issues

breakingThe default value for `global.vueSnapshots.attributesNotToStringify` changed from `['style']` to `['class', 'style', 'value', 'type']` in v2.13.0, and `v-bind` camelCase props are now stringified. This can cause existing snapshots to differ and require updates.

fix

Review and update your snapshots (`vitest --updateSnapshot` or `jest --updateSnapshot`). If you prefer the old behavior for specific attributes, configure `global.vueSnapshots.attributesNotToStringify` explicitly in your setup file.

affects: >=2.13.0

breakingVersion 2.9.0 changed the default behavior for stringifying `style` attributes. Previously, object-based `style` attributes were stringified as objects; now they are converted to DOM-valid CSS strings by default.

fix

Update your snapshots. If you specifically need the object representation in your snapshots, set `global.vueSnapshots.attributesNotToStringify = [];` in your test setup file.

affects: >=2.9.0

gotchaThis library is exclusively for Vue 3 components. Attempting to use it with Vue 2 projects will lead to incorrect serialization or runtime errors due to fundamental differences in Vue's virtual DOM structure.

fix

For Vue 2 projects, use `jest-serializer-vue-tjw` (or similar Vue 2-compatible serializers) instead.

affects: >=2.0.0

gotchaAfter a `types.js` file restructuring in v2.13.0, there's a possibility of TypeScript-related issues. While tested, unexpected edge cases might exist.

fix

If you encounter TypeScript errors related to `vue3-snapshot-serializer` after upgrading, report the issue to the maintainer. A temporary workaround might involve explicitly casting types or adjusting your `tsconfig.json`.

affects: >=2.13.0

gotchaThe `global.vueSnapshots.regexToRemoveAttributes` feature (v2.11.0) and `global.vueSnapshots.renameScopedVBindStyles` feature (v2.12.0) can significantly alter snapshot output if enabled. Be aware of their effects when debugging snapshot failures.

fix

Understand the documentation for these advanced features before enabling them. Debug snapshot changes by toggling these settings or inspecting the differences carefully.

affects: >=2.11.0

Errors

Common errors & fixes

SnapshotMismatchError: Snapshots do not match

A recent update to the serializer or changes in Vue components altered the rendered output, or configuration defaults changed (e.g., attribute stringification, `attributesNotToStringify` default).

fix

Review the diff in your test runner output. If the change is intended, update your snapshots by running your test command with the `--updateSnapshot` flag (e.g., `vitest --updateSnapshot` or `jest --updateSnapshot`).

TypeError: Cannot read properties of undefined (reading 'addSnapshotSerializer')

The serializer is not being added correctly to the test runner's `expect` object, likely due to incorrect setup file configuration or not using a setup file at all.

fix

Ensure your `vitest.config.js` or `jest.config.js` correctly points to a setup file, and that setup file contains `expect.addSnapshotSerializer(vue3SnapshotSerializer);` before any tests run. For Vitest, this is typically `setupFiles: ['./vitest.setup.ts']`.

Unexpected token 'export' or 'import' in serializer module

Your test environment is configured for CommonJS modules but is trying to load an ESM module directly, or vice-versa, when configuring the serializer path in `snapshotSerializers`.

fix

When specifying the serializer path in your `jest.config.js` or `vitest.config.js`, ensure you point to the correct module type based on your test runner's configuration: `./node_modules/vue3-snapshot-serializer/index.js` for CommonJS or `./node_modules/vue3-snapshot-serializer/index.mjs` for ESM. For `expect.addSnapshotSerializer`, use `require('vue3-snapshot-serializer')` for CJS or `import * as serializer from 'vue3-snapshot-serializer'` for ESM.

Upgrade

Version history

2.13.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/tjw-lint/vue3-snapshot-serializer ↗

packagehttps://www.npmjs.com/package/vue3-snapshot-serializer ↗