{"id":12634,"library":"vue3-snapshot-serializer","title":"Vue 3 Snapshot Serializer","description":"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.","status":"active","version":"2.13.2","language":"javascript","source_language":"en","source_url":"https://github.com/tjw-lint/vue3-snapshot-serializer","tags":["javascript","vue","vue3","vitest","jest","serializer","snapshots","unit","testing"],"install":[{"cmd":"npm install vue3-snapshot-serializer","lang":"bash","label":"npm"},{"cmd":"yarn add vue3-snapshot-serializer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue3-snapshot-serializer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM setups (e.g., Vitest's `setupFiles`), import the entire module. For CommonJS (e.g., older Jest configs), `require` is used.","wrong":"const serializer = require('vue3-snapshot-serializer');","symbol":"serializer","correct":"import * as serializer from 'vue3-snapshot-serializer';"},{"note":"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.","symbol":"global.vueSnapshots","correct":"global.vueSnapshots = { removeComments: true, sortAttributes: true };"},{"note":"Snapshot serializers are typically configured in your `vitest.config.js` or `jest.config.js` via a file path, not imported directly in the config.","wrong":"import serializer from 'vue3-snapshot-serializer'; // This is not how serializers are added to config","symbol":"snapshotSerializers","correct":"// vitest.config.js or jest.config.js\nexport default defineConfig({\n  test: {\n    snapshotSerializers: ['./node_modules/vue3-snapshot-serializer/index.js']\n  }\n});"}],"quickstart":{"code":"/* vitest.setup.ts */\nimport { expect } from 'vitest';\nimport * as vue3SnapshotSerializer from 'vue3-snapshot-serializer';\n\n// Add the serializer\nexpect.addSnapshotSerializer(vue3SnapshotSerializer);\n\n// Configure global settings for cleaner snapshots\nglobal.vueSnapshots = {\n  removeComments: true, // Remove HTML comments\n  removeDataTest: true, // Remove 'data-test' attributes\n  removeDataTestid: true, // Remove 'data-testid' attributes\n  removeDataVId: true, // Remove Vue's data-v-xxx attributes from scoped styles\n  sortAttributes: true, // Sort attributes alphabetically for consistent snapshots\n  formatter: 'diffable', // Use the 'diffable' formatter for improved readability\n};\n\n/* MyComponent.vue */\n<template>\n  <div class=\"container\" data-test=\"my-container\">\n    <!-- My comment -->\n    <p :style=\"{ color: dynamicColor }\" data-testid=\"content\">Hello {{ name }}!</p>\n    <ChildComponent :value=\"{ a: 1, b: 'test' }\" some-prop=\"static\" />\n  </div>\n</template>\n\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport ChildComponent from './ChildComponent.vue';\n\nconst name = ref('World');\nconst dynamicColor = ref('red');\n</script>\n\n/* ChildComponent.vue */\n<template>\n  <span class=\"child\">{{ value.b }}</span>\n</template>\n\n<script setup lang=\"ts\">\ndefineProps({\n  value: Object,\n  someProp: String,\n});\n</script>\n\n/* MyComponent.test.ts */\nimport { mount } from '@vue/test-utils';\nimport { describe, it, expect } from 'vitest';\nimport MyComponent from './MyComponent.vue';\n\ndescribe('MyComponent', () => {\n  it('renders correctly', () => {\n    const wrapper = mount(MyComponent);\n    expect(wrapper.html()).toMatchSnapshot();\n  });\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=2.13.0"},{"fix":"Update your snapshots. If you specifically need the object representation in your snapshots, set `global.vueSnapshots.attributesNotToStringify = [];` in your test setup file.","message":"Version 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.","severity":"breaking","affected_versions":">=2.9.0"},{"fix":"For Vue 2 projects, use `jest-serializer-vue-tjw` (or similar Vue 2-compatible serializers) instead.","message":"This 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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`.","message":"After a `types.js` file restructuring in v2.13.0, there's a possibility of TypeScript-related issues. While tested, unexpected edge cases might exist.","severity":"gotcha","affected_versions":">=2.13.0"},{"fix":"Understand the documentation for these advanced features before enabling them. Debug snapshot changes by toggling these settings or inspecting the differences carefully.","message":"The `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.","severity":"gotcha","affected_versions":">=2.11.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"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).","error":"SnapshotMismatchError: Snapshots do not match"},{"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']`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'addSnapshotSerializer')"},{"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.","cause":"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`.","error":"Unexpected token 'export' or 'import' in serializer module"}],"ecosystem":"npm"}