DEPRECATED

jest-serializer-vue-tjw is now deprecated.

Upgrade to vue3-snapshot-serializer

If you are still on Vue 2, then you will not be able to use the new library (it has code unique to the Vue 3 Virtual DOM).

The new library has all the same features, and comes with several new features as well:

	jest-serializer-vue-tjw	vue3-snapshot-serializer
First release	2020-01-12	2024-09-06
Made by	TheJaredWilcurt	TheJaredWilcurt
Vue Support	Vue 2 and 3 (somewhat)	Vue 3
Test Runners	Jest and Vitest (mostly)	Vitest and Jest
Test Utils	Vue-Test-Utils	Vue-Test-Utils and @Testing-Library/Vue
Module type	CJS (require)	ESM (import)
Settings stored in	vue.config.js or package.json	The global or globalThis object
Per-test settings	Posisble, but very difficult	Very easy
Formatting	Limited options	Very detailed controls
Stubbing out elements	❌	✅ new feature
postProcessor	❌	✅ new feature
addInputValues	Experimental (can crash)	✅
stringifyObjects	Experimental (can crash)	✅
attributesToClear	✅	✅
clearInlineFunctions	✅	✅
removeClassTest	✅	✅
removeComments	✅	✅
removeDataTest	✅	✅
removeDataTestid	✅	✅
removeDataTestId	✅	✅
removeDataQa	✅	✅
removeDataCy	✅	✅
removeDataVId	✅	✅
removeIdTest	✅	✅
removeIstanbulComments	✅	Removed (problem no longer exists)
removeServerRendered	✅	✅
sortAttributes	✅	✅
sortClasses	❌	✅ new feature
verbose	✅	✅
debug	❌	✅ new feature

For new projects, you can just follow the "Getting Started" guide on the docs site of the new library.

For existing projects follow the migration notes below.

Migrating from jest-serializer-vue-tjw to vue3-snapshot-serializer

If you have a Vue 2 codebase you are transitioning to Vue 3, then jest-serializer-vue-tjw will still work with Vue 3. So stick with it until your conversion to Vue 3 is done. Once completely over to Vue 3 (or if you have a codebase that was always Vue 3), then you can can migrate to vue3-snapshot-serializer.

1. Remove the old library
   • npm uninstall jest-serializer-vue-tjw
   • Delete any old code you have related to the old library (search for jestSerializer and jest-serializer)
2. Add the new library
   • npm install --save-dev vue3-snapshot-serializer
3. In your Vitest or Jest config, replace the snapshot serializer:

   1 "snapshotSerializers": [
   2-  "<rootDir>/node_modules/jest-serializer-vue-tjw"
   3+  "./node_modules/vue3-snapshot-serializer/index.js"
   4 ]

4. The new library uses the "diffable" formatter by default, this will give you very different snapshots. So to make the transition smoother, we also offer the "classic" formatter, which is the same one used by jest-serializer-vue-tjw.
   • In your Vitest/Jest setup.js file add the following to your global beforeEach:

     1global.beforeEach(() => {
     2  // Set the default settings for each snapshot
     3  global.vueSnapshots = {
     4    formatter: 'classic',
     5    classicFormatting: {
     6      // Pass in js-beautify.html settings here.
     7      // The defaults for this match the defaults for jest-serializer-vue-tjw.
     8    }
     9  };
     10});

   • The API for classicFormatting is the same as the formatting options for jest-serializer-vue-tjw. Full details are documented here.
   • There may still be some minor tweaks when going to the new library, but this is as close as you'll get to replicating the snapshots.
5. Once migrated over, you can try removing the formatter and classicFormatting settings to use the new formatter which is much more customizable. This will require updating your snapshots again, expect major formatting changes to occur. Consult the new docs site for details on customzing snapshots.

   1global.beforeEach(() => {
   2  // Set the default settings for each snapshot
   3  global.vueSnapshots = {
   4    formatting: {}
   5  };
   6});

---

Old Documentation

Everything below this point is the original documentation for this library.

---

jest-serializer-vue-tjw

Jest Vue snapshot serializer

Logo made by Aurora Wooton (age 14)

---

Quotes:

"This looks fantastic! This might sell me on testing." - Views on Vue podcast (#99)

---

Sections:

• Features List
  • Better Snapshots Demo
• Usage/Installation/Migration Instructions
  • Expected breaking changes for v2 to v3 migration
  • Avoiding snpshot changes (not recommended)
• API
• FAQs & Testing Tips

Features list:

The following can all be adjusted in your vue.config.js settings or package.json.

1. Can optionally remove from snapshots (enabled by default):
   • data-server-rendered="true"
   • data-test="whatever"
   • data-testid="whatever"
   • data-test-id="whatever"
   • data-v-1234abcd=""
2. Can optionally remove from snapshots (disabled by default):
   • All html comments <!-- whatever -->
   • data-qa="whatever"
   • id="testWhatever"
   • class="test-whatever"
3. Can clear out inline functions from snapshots, or keep them but remove Istanbul's auto-inserted comments.
4. Has an experimental feature to display JSON data stored in HTML attributes instead of href="[object Object]"
5. Has much better snapshot defaults.
6. Lets you control your snapshot formatting with an API.

What do you mean by "much better snapshot defaults"?

This is the before and after of using the default formatting options from v2, and the default formatting options in v3. You can now customize the formatting as well in v3 (See API).

Usage and Migrating from v2 to v3

1. First you will need to install this new dependency:
   • npm install --save-dev jest-serializer-vue-tjw
   • If you have jest-serializer-vue in your dependencies or devDependencies it can be removed.
2. Next you will need to change your Jest config settings. Make sure to replace the reference to the previous (non-TJW) version with the new version:

   1"snapshotSerializers": [
   2  "<rootDir>/node_modules/jest-serializer-vue-tjw"
   3]

3. Run your test command with -- -u at the end so it will update any existing snapshots, for example:
   • npm run test:unit -- -u
4. Then just use .toMatchSnapshot('optional snapshot name'); in your tests:

Example:

1import { shallowMount } from '@vue/test-utils';
2import MyComponent from './MyComponent.vue';
3
4describe('MyComponent.vue', () => {
5  describe('Created', () => {
6    test('Renders correctly with default props', () => {
7      const wrapper = shallowMount(MyComponent);
8
9      expect(wrapper)
10        .toMatchSnapshot();
11    });
12  });
13});

Breaking changes to expect in your snapshots during migration

1. General formatting will be improved to aid in readability and better diffs.
2. Test tokens will be removed. These are used to target elements in your tests.
   • data-test="whatever"
   • data-testid="whatever"
   • data-test-id="whatever"
3. All data-v-whatever="" will be removed. These are attributes added by Vue to help scope styles. Removing them from your snapshots makes updating scoped dependencies easier.
4. Any empty HTML attributes will be trimmed to remove the empty assignment. So <div class=""></div> becomes <div class></div>.
5. Some optionally self-closing tags, will now become self-closing. So <svg><path></path></svg> becomes <svg><path /></svg>.

Example: These are the kind of diffs you can expect to see when migrating from v2 to v3.

1 <div>
2-  <h1 data-test="pageTitle" data-test-id="pageTitle" data-testid="pageTitle">
3+  <h1>
4     The above specific data-attrubutes are removed by default.
5   </h1>
6   <div>
7-    <span class="active" data-v-b3d95ac7="">
8+    <span class="active">
9       These data-v ID's are removed too by default.
10     </span>
11     <!---->
12     <!-- There's an option you can turn on to remove all HTML comments too -->
13     <!-- It's turned off by default, since they usually represent a v-if="false" -->
14     <!-- and maybe you want to know about that. If not, set removeComments: true -->
15   </div>
16
17   <div>
18-    <h3 class="inline-block">Default formatting is improved</h3> <span><i class="fa fa-spinner"></i> <span class="sr-only">Loading...</span></span> <a><button type="button class="primary"><i class="fa fa-plus"></i>
19+    <h3 class="inline-block">Default formatting is improved</h3>
20+    <span>
21+      <i class="fa fa-spinner"></i>
22+      <span class="sr-only">Loading...</span>
23+    </span>
24+    <a>
25+      <button class="primary" type="button>
26+        <i class="fa fa-plus"></i>
27         The formatting here is completely customizable (see API).
28-    </button></a>
29+      </button>
30+    </a>
31-    <svg style="">
32+    <svg style>
33-      <path d="M 10,150 L 70,10 L 130,150 z"></path>
34+      <path d="M 10,150 L 70,10 L 130,150 z" />
35     </svg>
36   </div>
37 </div>

Avoiding breaking changes (not recommended)

Though all default settings are designed to be the best choice for most people, if you want to opt out of these (or opt-in to other changes, like removing HTML comments from snapshots) you can via a settings object in your Vue config. Note, some changes cannot currently be avoided (self-closing enforcement and empty attribute trimming).

1. Edit your vue.config.js in the root of your project (or create it, if you do not have one).
2. The following are the jest-serializer-vue v2.0.2 settings:

1// vue.config.js
2module.exports = {
3  pluginOptions: {
4    jestSerializer: {
5      clearInlineFunctions: false,
6      // All available options: https://github.com/beautify-web/js-beautify/blob/master/js/src/html/options.js
7      formatting: {
8        unformatted: ['code', 'pre', 'em', 'strong', 'span'],
9        indent_inner_html: true,
10        indent_char: ' ',
11        indent_size: 2,
12        sep: '\n'
13      },
14      removeClassTest: false,
15      removeComments: false,
16      removeDataTest: false,
17      removeDataTestid: false,
18      removeDataTestId: false,
19      removeDataQa: false,
20      removeDataCy: false,
21      removeDataVId: false,
22      removeIdTest: false,
23      removeIstanbulComments: false,
24      removeServerRendered: true,
25      sortAttributes: false,
26      stringifyObjects: false
27    }
28  }
29};

API

ALL SETTINGS ARE OPTIONAL. The defaults are below. If you like them, you don't need to add anything to your Vue config.

In your vue.config.js file:

1module.exports = {
2  pluginOptions: {
3    jestSerializer: {
4      attributesToClear: [],
5      clearInlineFunctions: false,
6      // All available formatting options: https://github.com/beautify-web/js-beautify/blob/master/js/src/html/options.js
7      formatting: {
8        indent_char: ' ',
9        indent_inner_html: true,
10        indent_size: 2,
11        inline: [],
12        sep: '\n',
13        unformatted: ['code', 'pre']
14      },
15      removeClassTest: false,
16      removeComments: false,
17      removeDataTest: true,
18      removeDataTestid: true,
19      removeDataTestId: true,
20      removeDataQa: false,
21      removeDataCy: false,
22      removeDataVId: true,
23      removeIdTest: false,
24      removeIstanbulComments: true,
25      removeServerRendered: true,
26      sortAttributes: true,
27      verbose: true,
28      // Experimental features:
29      addInputValues: false,
30      stringifyObjects: false
31    }
32  }
33};

Alternatively, you can place your settings in the package.json. If a jestSerializer object exists here, we skip looking for a vue.config.js file (useful for those with complex configs, Nuxt users, or those not using Vue-CLI).

In your package.json file:

1{
2  "name": "your_app",
3  "scripts": {},
4  "devDependencies": {},
5
6  "jestSerializer": {
7    "attributesToClear": [],
8    "clearInlineFunctions": false,
9    "//": "All available formatting options: https://github.com/beautify-web/js-beautify/blob/master/js/src/html/options.js",
10    "formatting": {
11      "indent_char": " ",
12      "indent_inner_html": true,
13      "indent_size": 2,
14      "inline": [],
15      "sep": "\n",
16      "unformatted": ["code", "pre"]
17    },
18    "removeClassTest": false,
19    "removeComments": false,
20    "removeDataTest": true,
21    "removeDataTestid": true,
22    "removeDataTestId": true,
23    "removeDataQa": false,
24    "removeDataCy": false,
25    "removeDataVId": true,
26    "removeIdTest": false,
27    "removeIstanbulComments": true,
28    "removeServerRendered": true,
29    "sortAttributes": true,
30    "verbose": true,
31    "// ": "Experimental features:",
32    "addInputValues": false,
33    "stringifyObjects": false
34  }
35}

Setting	Default	Description
attributesToClear	[]	Takes an array of attribute strings, like ['title', 'id'], to remove the values from these attributes. <input title id class="stuff">.
clearInlineFunctions	false	Replaces <div title="function () { return true; }"> or this <div title="(x) => !x"> with this placeholder <div title="[function]">.
formatting	See above example	These options format the snapshot. See all available options here.
removeClassTest	false	Removes all CSS classes that start with "test", class="test-whatever". Warning: Don't use this approach. Use data-test instead. It is better suited for this because it doesn't conflate CSS and test tokens.
removeComments	false	Removes all HTML comments from your snapshots. This is false by default, as sometimes these comments can infer important information about how your DOM was rendered. However, this is mostly just personal preference.
removeDataTest	true	Removes data-test="whatever" from your snapshots if true. To also remove these from your production builds, see here.
removeDataTestid	true	Removes data-testid="whatever" from your snapshots if true.
removeDataTestId	true	Removes data-test-id="whatever" from your snapshots if true.
removeDataQa	false	Removes data-qa="whatever" from your snapshots if true. data-qa is usually used by non-dev QA members. If they change in your snapshot, that indicates it may break someone else's E2E tests. So most using data-qa prefer they be left in by default.
removeDataCy	false	Removes data-cy="whatever" from your snapshots if true. data-cy is used by Cypress end-to-end tests. If they change in your snapshot, that indicates it may break an E2E tests. So most using data-cy prefer they be left in by default.
removeDataVId	true	Removes data-v-1234abcd="" from your snapshots. Important if a 3rd-party component uses scoped styles, to prevent ID changes from breaking your mount based tests when updating a dependency.
removeIdTest	false	Removes id="test-whatever" or id="testWhatever"from snapshots. Warning: You should never use ID's for test tokens, as they can also be used by JS and CSS, making them more brittle. Use data-test-id instead.
removeIstanbulComments	true	Removes /* istanbul ignore next */ cov_1lmjj6lxv1.f[3]++; comments from snapshots when functions are inside HTML attributes. See v3.16.0 release notes for more details.
removeServerRendered	true	Removes data-server-rendered="true" from your snapshots if true.
sortAttributes	true	Sorts the attributes inside HTML elements in the snapshot. This helps make snapshot diffs easier to read.
verbose	true	Logs to the console errors or other messages if true. Strongly recommended if using experimental features.
addInputValues	false	EXPERIMENTAL Displays the value of form fields. <input> becomes <input value="whatever"> in your snapshots. Requires you pass in wrapper, not wrapper.html(). On deeply nested components, it may exceed callstack.
stringifyObjects	false	EXPERIMENTAL Replaces title="[object Object]" with title="{a:'asdf'}" in your snapshots, allowing you to see the data in the snapshot. Requires you to pass in wrapper, not wrapper.html(). This is still a work in progress. On deeply nested components, it may exceed callstack.

FAQs & tips

What is the best approach for targeting elements in a test? - Use data-test when targeting multiple elements, or data-test-id (or data-testid if you don't like the extra hyphen) when targeting a unique element.

1test('Click link', () => {
2  const wrapper = shallowMount(LinkList);
3  const linkList = wrapper.find('[data-test-id="linkList"]');
4  const domLink = linkList.findAll('[data-test="link"]').at(0);
5
6  domLink.trigger('click');
7
8  expect(specialFunction)
9    .toHaveBeenCalledWith('https://passed-in-url.com');
10});
11

I have some code that I don't want formatted. How do I "opt out" of the settings for one test? - You can skip the snapshots and just do a string comparison directly, without a snapshot. This is useful when the actual whitespace in the DOM is important and needs to be captured properly without formatting being applied.

1test('Spacing around links is accurate', () => {
2  const wrapper = shallowMount(YourComponent);
3  const section = wrapper.find('[data-test-id="specificSection"]');
4
5  expect(section.html())
6    .toEqual(`<div data-test-id="specificSection">
7  <a href="#">link</a><a href="#">link</a>     <a href="#">link</a>
8  <a href="#">link</a>  <a href="#">link</a>
9</div>`);
10});

How do I override the settings for just one test? - This is a little complicated, but doable. The following is a basic example. You can refer to the test setup/helpers file in this repo for a more complex example.

1describe('YourComponent.vue', () => {
2  beforeEach(() => {
3    jest.resetModules();
4  });
5
6  test('Overriding snapshot settings for one test', () => {
7    jest.doMock('../../../vue.config.js', function () {
8      return {
9        pluginOptions: {
10          jestSerializer: {
11            removeComments: true,
12            stringifyObjects: true
13          }
14        }
15      };
16    });
17
18    const wrapper = shallowMount(YourComponent);
19    const section = wrapper.find('[data-test-id="specificSection"]');
20
21    expect(section)
22      .toMatchSnapshot();
23  })
24});

How do I opt out of stringifyObjects or addInputValues for one test? - This is actually much easier. These experimetnal features can only be done on a Vue VNode. So if you do .html() prior to sending it, it will always skip these transforms. This allows you to use these experimental features more easily, while opting out of the more troublesome tests.

1test('Assuming stringifyObjects is enabled', () => {
2  const wrapper = shallowMount(YourComponent);
3
4  expect(wrapper)
5    .toMatchSnapshot('Stringify objects and add input values');
6
7  expect(wrapper.html())
8    .toMatchSnapshot('Opt out of stringify objects and adding input values');
9});

Using with Vitest

Vitest actually uses the same snapshot library under the hood as Jest, so this library will work with it as well.

1. npm install --save-dev jest-serializer-vue-tjw
2. In your /vite.config.js file point to a setup file:

   1import { defineConfig } from 'vite';
   2
   3export default defineConfig({
   4  test: {
   5    setupFiles: [
   6      './tests/unit/setup.js'
   7    ]
   8  }
   9});

3. In your /tests/unit/setup.js file:

   1import vueSnapshotSerializer from './serializer.js';
   2
   3expect.addSnapshotSerializer(vueSnapshotSerializer);

4. In your /tests/unit/serializer.js file:

   1const jestSerializerVueTJW = require('jest-serializer-vue-tjw');
   2
   3const helpers = {
   4  isHtmlString: function (received) {
   5    return (
   6      typeof(received) === 'string' &&
   7      (
   8        received.startsWith('<') ||
   9        received.startsWith('"<')
   10      )
   11    );
   12  },
   13  isVueWrapper: function (received) {
   14    return (
   15      typeof(received) === 'object' &&
   16      typeof(received.html) === 'function'
   17    );
   18  }
   19};
   20
   21module.exports = {
   22  test: function (received) {
   23    return helpers.isHtmlString(received) || helpers.isVueWrapper(received);
   24  },
   25  print: function (received) {
   26    // force to a string
   27    received = received?.html && received?.html() || received;
   28    return jestSerializerVueTJW.print(received);
   29  }
   30};

5. Any customizing of settings for this library should be placed in your /package.json, like so:

   1{
   2  "jestSerializer": {
   3    "sortAttributes": true,
   4    "verbose": true
   5  }
   6}