From 39d86ad5abe71bac8d76c5b82f11f30225cf8673 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Renato=20de=20Le=C3=A3o?= <renatodeleao@gmail.com>
Date: Fri, 23 Dec 2022 19:36:35 +0000
Subject: [PATCH] docs: add section about test runners upgrade to migration
 guide (#1923)

Context: https://github.com/vuejs/vue-test-utils/issues/1975#issuecomment-13595554
As discussed, there a couple of issues that the community faced while upgrading
to vue@3 @vue/test-utils@^2 but that are not directly related with them.

In a effort to make migrations more smooth, a new section  was added
to the migration docs that lists some common problems with underlying
test runners, that might happen simply because of the fact that
users took the opportunity to upgrade their test stacks dependecies
as well.

It starts with a few issues with jest, one reported in the
legacy test-utils repo and other one that i've personally faced.

https://github.com/vuejs/vue-test-utils/issues/1975
---
 docs/migration/index.md | 45 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/migration/index.md b/docs/migration/index.md
index a3f72ef86..5dc47c3a2 100644
--- a/docs/migration/index.md
+++ b/docs/migration/index.md
@@ -232,3 +232,48 @@ wrapper.findAll('[data-test="token"]').at(0);
 ```js
 wrapper.findAll('[data-test="token"]')[0];
 ```
+
+## Test runners upgrade notes
+
+> Vue Test Utils is framework agnostic - you can use it with whichever test runner you like.
+
+This statement is at the core of `@vue/test-utils`. But we do relate to the fact that migrating code bases and corresponding test suites to `vue@3` can be, in some scenarios, a pretty big effort. 
+
+This section tries to compile some common gotchas spotted by our community while doing their migrations and also updating their underlying test running stack to more modern versions. These are unrelated to `@vue/test-utils`, but we hope it can help you out completing this important migration step.
+
+### `@vue/vue3-jest` + `jest@^28`
+
+If you've decided to take the opportunity and upgrade your test runner tools to a more modern version, have these in mind.
+
+#### `ReferenceError: Vue is not defined` [vue-jest#479](https://github.com/vuejs/vue-jest/issues/479)
+
+When `jest-environment-jsdom` package is used, it defaults to load libraries from `package.json` [`browser` entry](https://jestjs.io/docs/configuration#testenvironmentoptions-object). You can override it to use `node` imports instead and fix this error:
+
+```js
+// jest.config.js
+module.exports = {
+  testEnvironmentOptions: {
+    customExportConditions: ["node", "node-addons"],
+  }
+}
+```
+<br/>
+
+#### Snapshots now include my comment nodes
+
+If you use snapshot testing and comment nodes are leaking into your snapshots, note that `comments` are now always [preserved](https://vuejs.org/api/application.html#app-config-compileroptions-comments) and only removed in production. You can override this behaviour by tweaking `app.config.compilerOptions` to remove them from snapshots as well: 
+  - via `vue-jest` [config](https://github.com/vuejs/vue-jest#compiler-options-in-vue-3).
+    ```js
+    // jest.config.js
+    module.exports = {
+      globals: {
+        'vue-jest': {
+          compilerOptions: {
+            comments: false
+          }
+        }
+      }
+    }
+    ```
+ - Via `@vue/test-utils` [`mountingOptions.global.config`](https://test-utils.vuejs.org/api/#global) either globally or on per-test basis.
+ 
\ No newline at end of file