docs: shallow and stubs

src/guide/stubs-shallow-mount.md

@@ -1,3 +1,200 @@
 # Stubs and Shallow Mount
 
-Mostly `mount({ shallow: true })` and `global.stubs`.
+Vue Test Utils provides some features for *stubbing* components. A *stub* is where you replace an existing implementation of a custom component with a dummy component that doesn't do anything at all, which can simplify an otherwise complex test. Let's see an example.
+
+## Mocking with `global.stubs`
+
+A common example is when you would like to test something in a component that appers very high in the component hierarchy.
+
+In this example, we have an `<App>` that renders a message, as well as a `FetchDataFromApi` component that makes an API call.
+
+```js
+const FetchDataFromApi = {
+  name: 'FetchDataFromApi',
+  template: `
+    <div>{{ result }}</div>
+  `,
+  async mounted() {
+    const res = await axios.get('/api/info')
+    this.result = res.data
+  },
+  data() {
+    return {
+      result: ''
+    }
+  }
+}
+
+const App = {
+  components: {
+    FetchDataFromApi
+  },
+  template: `
+    <div>
+      <h1>Welcome to Vue.js 3</h1>
+      <fetch-data-from-api />
+    </div>
+  `
+}
+```
+
+ We do not want to make the API call in this particular test, we just want to assert the message is rendered. In this case, we could use the `stubs`, which appears in the `global` mounting option.
+
+```js {12}
+test('stubs', () => {
+  const wrapper = mount(App, {
+    global: {
+      stubs: {
+        FetchDataFromApi: {
+          template: '<span />'
+        }
+      }
+    }
+  })
+
+  console.log(wrapper.html()) // <div><h1>Welcome to Vue.js 3</h1><span></span></div>
+  expect(wrapper.html()).toContain('Welcome to Vue.js 3')
+})
+```
+
+Notice that the template is showing `<span></span>` where `<fetch-data-from-api />` was? We replaced it with a stub - in this case, we provided our own implementation by passing in a `template`.
+
+You can also get a default stub, instead of providing your own:
+
+```js {9}
+test('stubs', () => {
+  const wrapper = mount(App, {
+    global: {
+      stubs: {
+        FetchDataFromApi: true
+      }
+    }
+  })
+  console.log(wrapper.html()) // <div><h1>Welcome to Vue.js 3</h1><fetch-data-from-api-stub></fetch-data-from-api-stub></div>
+  expect(wrapper.html()).toContain('Welcome to Vue.js 3')
+})
+```
+
+This will stub out *all* the `<FetchDataFromApi />` components in the entire render tree, regardless of what level they appear at. That's why it is in the `global` mounting option.
+
+## `shallow: true` or `shallowMount`
+
+Sometimes you might want to stub out *all* the custom components. For example you might have a component like this:
+
+```js
+const ComplexComponent = {
+  components: { ComplexA, ComplexB, ComplexC },
+  template: `
+    <div>
+      <h1>Welcome to Vue.js 3</h1>
+      <ComplexA />
+      <ComplexB />
+      <ComplexC />
+    </div>
+  `
+}
+```
+
+Imagine each of the `<Complex>` does something complicated, and you are only interested in testing that the `<h1>` is rendering the correct greeting. You could do something like:
+
+```js
+const wrapper = mount(ComplexComponent, {
+  global: {
+    stubs: {
+      ComplexA: true,
+      ComplexB: true,
+      ComplexC: true,
+    }
+  }
+})
+```
+
+But that's a lot of boilerplate. VTU has a `shallow` mounting option that will automatically stub out all the child components:
+
+```js {5}
+test('shallow', () => {
+  const wrapper = shallow(ComplexComponent, {
+    shallow: true
+  })
+  console.log(wrapper.html()) // <div><h1>Welcome to Vue.js 3</h1><complex-a-stub></complex-a-stub><complex-b-stub></complex-b-stub><complex-c-stub></complex-c-stub></div>
+})
+```
+
+> TIP: If you used VTU V1, you may remember this as `shallowMount`. That method is still available, too - it's the same as writing `shallow: true`.
+
+## Default Slots and `shallow`
+
+Since `shallow` stubs out all the render function of any custom components, any `<slot>` components are not rendered when using `shallow`. While this is not a problem in most cases, there are some scenarios where this isn't ideal. Maybe you have a custom button component in your app:
+
+```js
+const CustomButton = {
+  template: `
+    <button>
+      <slot />
+    </button>
+  `
+}
+```
+
+And you might use it like this:
+
+```js
+const App = {
+  props: ['authenticated'],
+  components: { CustomButton },
+  template: `
+    <div>
+      <h1>Welcome!</h1>
+      <custom-button>
+        <div v-if="authenticated">
+          Log out
+        </div>
+        <div v-else>
+          Log in
+        </div>
+      </custom-button>
+    </div>
+  `
+}
+```
+
+If you are using `shallow`, the `<slot />` will not be rendered, since the render function in `<custom-button />` is stubbed out. That means you won't be able to verify the correct text is rendered! For this use case, you can use `config.renderDefaultStub`, which will render the default `<slot />`, even when using `shallow`:
+
+```js {1,4,8}
+import { config, mount } from '@vue/test-utils'
+
+beforeAll(() => {
+  config.renderStubDefaultSlot = true
+})
+
+afterAll(() => {
+  config.renderStubDefaultSlot = false
+})
+
+test('shallow with stubs', () => {
+  const wrapper = mount(AnotherApp, {
+    props: {
+      authenticated: true
+    },
+    shallow: true
+  })
+
+  expect(wrapper.html()).toContain('Log out')
+})
+```
+
+Since this behavior is global, not on a `mount` by `mount` basis, you need to remember to enable/disable it before and after each test.
+
+If you prefer this behavior, you can enable this globally by importing `config` in your test setup file, and setting `renderStubDefaultSlot` to `true`. Unfortunately, due to technical limitations, this behavior is not extended to slots other than the default slot.
+
+## `mount`, `shallow` and `stubs`: which one and when?
+
+Tests that use `mount` will render the entire component hierarchy, which is closer to what the user will experiene in a real browser. Tests using `shallow` are focused on a specific component. As a rule of thumb, the more your tests resemble the way your software is used, the more confidence they can give you. `shallow` can be useful for testing a specific component in complete isolation. If you just have one or two components that are not relevant to your tests, consider using `mount` in combination with `stubs` instead of `shallow`. The more you stub, the less production-like your test becomes.
+
+Keep in mind that whether you are doing a full mount or a shallow render, good tests focus on inputs (`props` and user interaction, such as with `trigger`) and outputs (in the case of a component, the DOM elements that are rendered), not implementation details. So regardless of which mounting method you choose, keep these guidelines in mind.
+
+## Conclusion
+
+- use `global.stubs` to replace a component with a dummy one that does nothing to simplify your tests
+- use `shallow: true` (or `shallowMount`) to stub out all custom components
+- use `config.stubRenderDefaultSlot` to render the default `<slot>` for a stubbed component