Improve docs

README.md

@@ -97,14 +97,14 @@ module.exports = {
 Setting              | Default           | Description
 :--                  | :--               | :--
 pretty               | See above example | These options are passed into `pretty` to format the snapshot. To use `pretty`'s defaults pass in `true`. [See all available options here](https://github.com/beautify-web/js-beautify/blob/master/js/src/html/options.js).
-removeClassTest      | `false`           | Removes all CSS classes that start with "test", `class="test-whatever"`. Don't use this. Use `data-test` instead. It is better suited for this because it doesn't conflate CSS and test tokens.
+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 be 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](https://forum.vuejs.org/t/how-to-remove-attributes-from-tags-inside-vue-components/24138).
 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.
 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. 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` instead.
+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.
 removeServerRendered | `true`            | Removes `data-server-rendered="true"` from your snapshots if true.
 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 componets, it may exceed callstack.
 
@@ -177,3 +177,80 @@ Though all default settings are designed to be the best choice for most people,
 
 1. Edit your `vue.config.js` in the root of your project (or create it, if you do not have one).
    * See the **API** section in these docs for details about customizing your preferences.
+
+
+## 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.
+
+```js
+test('Click link', () => {
+  const wrapper = shallowMount(LinkList);
+  const linkList = wrapper.find('[data-test-id="linkList"]');
+  const domLink = linkList.findAll('[data-test="link"]').at(0);
+
+  domLink.trigger('click');
+
+  expect(specialFunction)
+    .toHaveBeenCalledWith('https://passed-in-url.com');
+});
+
+```
+
+**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 `pretty` being applied.
+
+```js
+test('Manually testing to skip the snapshot serializer', () => {
+  const wrapper = shallowMount(YourComponent);
+  const section = wrapper.find('[data-test-id="specificSection"]');
+
+  expect(section.html())
+    .toEqual(`<div data-test-id="specificSection">
+  <a href="#">link</a><a href="#">link</a>     <a href="#">link</a>
+  <a href="#">link</a>  <a href="#">link</a>
+</div>`);
+});
+```
+
+**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.
+
+```js
+describe('YourComponent.vue', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  test('Overriding snapshot settings for one test', () => {
+    jest.doMock('../../../vue.config.js', function () {
+      return {
+        pluginOptions: {
+          jestSerializer: {
+            removeComments: true,
+            stringifyObjects: true
+          }
+        }
+      };
+    });
+
+    const wrapper = shallowMount(YourComponent);
+    const section = wrapper.find('[data-test-id="specificSection"]');
+
+    expect(section)
+      .toMatchSnapshot();
+  })
+});
+```
+
+**How do I opt out of stringifyObjects for one test?** - This is actually much easier. Stringify objects can only be done on a Vue VNode. So if you do `.html()` prior to sending it, it will always skip the `stringifyObjects` code. This allows you to use this experimental feature more easily, while opting out of the more troublesome tests.
+
+```js
+test('Assuming stringifyObjects is enabled', () => {
+  const wrapper = shallowMount(YourComponent);
+
+  expect(wrapper)
+    .toMatchSnapshot('Stringify objects');
+
+  expect(wrapper.html())
+    .toMatchSnapshot('Opt out of stringify objects');
+});
+```

index.js

@@ -114,10 +114,17 @@ function removeTestTokens (html, options) {
         }
       });
 
+      // If a element has 3 or more classes that need removed,
+      // then removing them in the above loop would mess up the index
+      // as we are looping, skipping classes. There is a test in place
+      // for that edge case. That's why we build a temp list of
+      // classes to remove and then loop over it.
       classesToRemove.forEach(function (className) {
         element.classList.remove(className);
       });
 
+      // Only remove the empty class attributes on elements that had test-classes.
+      // There is a test case for this.
       if (!element.classList.length && classesToRemove.length) {
         element.removeAttribute('class');
       }