docs: improve wording and structure (#91)

* Fix broken links

* Improve wording

* Fix TOC placement

* Consistency is key

Author: afontcu

README.md

@@ -1,6 +1,8 @@
 <div align="center">
 <h1>Vue Testing Library</h1>
 
+<br />
+
 <a href="https://www.joypixels.com/emoji/1F98E">
   <img
     height="80"
@@ -16,7 +18,7 @@
 
 <br />
 
-[**Read the Docs**][docs] | [Edit the docs][docs-edit]
+[**Read the docs**][docs] | [Edit the docs][docs-edit]
 
 <br />
 
@@ -36,6 +38,9 @@
 
 <h2>Table of Contents</h2>
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
 - [Installation](#installation)
 - [A simple example](#a-simple-example)
   - [More examples](#more-examples)
@@ -44,9 +49,11 @@
 - [License](#license)
 - [Contributors](#contributors)
 
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Installation
 
-This module is distributed via npm and should be installed as one of your
+This module is distributed via `npm` and should be installed as one of your
 project's `devDependencies`:
 
 ```
@@ -57,7 +64,7 @@ This library has `peerDependencies` listings for `Vue` and
 `vue-template-compiler`.
 
 You may also be interested in installing `jest-dom` so you can use
-[the custom Jest matchers](https://github.com/gnapse/jest-dom#readme).
+[the custom Jest matchers](https://github.com/testing-library/jest-dom#readme).
 
 ## A simple example
 
@@ -90,7 +97,7 @@ import {render, fireEvent} from '@testing-library/vue'
 import TestComponent from './TestComponent.vue'
 
 test('increments value on click', async () => {
-  // The render method returns a collection of utilities to query your component.
+  // The render method returns a collection of utilities to query the component.
   const {getByText} = render(TestComponent)
 
   // getByText returns the first matching node for the provided text, and
@@ -100,7 +107,7 @@ test('increments value on click', async () => {
   // `button` is the actual DOM element.
   const button = getByText('increment')
 
-  // Dispatch a native click event.
+  // Dispatch a couple of native click events.
   await fireEvent.click(button)
   await fireEvent.click(button)
 
@@ -124,12 +131,12 @@ Feel free to contribute with more examples!
 
 ## Docs
 
-[**Read the Docs**][docs] | [Edit the docs][docs-edit]
+[**Read the docs**][docs] | [Edit the docs][docs-edit]
 
 ## Typings
 
 The TypeScript type definitions are in the
-[DefinitelyTyped repo](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__vue)
+[DefinitelyTyped repo][types]
 and bundled with Vue Testing Library.
 
 ## License
@@ -166,13 +173,14 @@ and bundled with Vue Testing Library.
 [npm]: https://badge.fury.io/js/%40testing-library%2Fvue
 [license-badge]: https://img.shields.io/github/license/testing-library/vue-testing-library.svg
 [license]: https://github.com/testing-library/vue-testing-library/blob/master/LICENSE
+[types]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__vue
 
 [docs]: https://testing-library.com/vue
 [docs-edit]: https://github.com/testing-library/testing-library-docs
 
-[test-directory]: https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__
-[vuex-example]: https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__/vuex.js
-[vue-router-example]: https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__/vue-router.js
-[vee-validate-example]: https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__/validate-plugin.js
+[test-directory]: https://github.com/testing-library/vue-testing-library/blob/master/src/__tests__
+[vuex-example]: https://github.com/testing-library/vue-testing-library/blob/master/src/__tests__/vuex.js
+[vue-router-example]: https://github.com/testing-library/vue-testing-library/blob/master/src/__tests__/vue-router.js
+[vee-validate-example]: https://github.com/testing-library/vue-testing-library/blob/master/src/__tests__/validate-plugin.js
 [vue-i18n-example]: https://github.com/testing-library/vue-testing-library/blob/master/tests/__tests__/vueI18n.js
 <!-- prettier-ignore-end -->

src/__tests__/__snapshots__/axios-mock.js.snap

@@ -5,8 +5,8 @@ beforeAll(async () => {
   render = vtl.render
 })
 
-// This one verifies that if VTL_SKIP_AUTO_CLEANUP is set
-// then we DON'T auto-wire up the afterEach for folks
+// This test verifies that if VTL_SKIP_AUTO_CLEANUP is set then we DON'T
+// auto-wire up the afterEach cleanup for folks.
 test('first test render a vue component', () => {
   render({
     template: `<h1>Hello World</h1>`,

src/__tests__/auto-cleanup-skip.js

@@ -1,9 +1,8 @@
 import {render} from '@testing-library/vue'
 import '@testing-library/jest-dom/extend-expect'
 
-// This just verifies that by importing VTL in an
-// environment which supports afterEach (like jest)
-// we'll get automatic cleanup between tests.
+// This just verifies that by importing VTL in an environment which supports
+// afterEach (like jest) we'll get automatic cleanup between tests.
 test('render the first component', () => {
   render({
     template: `<h1>Hello World</h1>`,

src/__tests__/auto-cleanup.js

@@ -1,9 +1,9 @@
+import '@testing-library/jest-dom/extend-expect'
 import axiosMock from 'axios'
 import {render, fireEvent} from '@testing-library/vue'
 import Component from './components/Fetch.vue'
-import '@testing-library/jest-dom/extend-expect'
 
-test('makes an API call and displays the greeting when load-greeting is clicked', async () => {
+test('mocks an API call when load-greeting is clicked', async () => {
   axiosMock.get.mockImplementationOnce(() =>
     Promise.resolve({
       data: {greeting: 'hello there'},
@@ -12,7 +12,6 @@ test('makes an API call and displays the greeting when load-greeting is clicked'
 
   const {html, getByText} = render(Component, {props: {url: '/greeting'}})
 
-  // Act
   await fireEvent.click(getByText('Fetch'))
 
   expect(axiosMock.get).toHaveBeenCalledTimes(1)
@@ -23,5 +22,11 @@ test('makes an API call and displays the greeting when load-greeting is clicked'
   // that Snapshot Testing should not be treated as a replacement for regular
   // tests.
   // More about the topic: https://twitter.com/searls/status/919594505938112512
-  expect(html()).toMatchSnapshot()
+  expect(html()).toMatchInlineSnapshot(`
+    <div><button>
+        Fetch
+      </button> <span>
+        hello there
+      </span></div>
+  `)
 })

src/__tests__/axios-mock.js

@@ -0,0 +1,19 @@
+<template>
+  <div>
+    <h2>{{ $t('Hello') }}</h2>
+    <button @click="switchLocale('en')">English</button>
+    <button @click="switchLocale('ja')">Japanese</button>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'VueI18n',
+
+  methods: {
+    switchLocale(locale) {
+      this.$i18n.locale = locale
+    },
+  },
+}
+</script>

src/__tests__/components/Translations.vue

@@ -34,7 +34,7 @@ test('debug pretty prints the provided parameter', () => {
     expect.stringContaining('Lorem ipsum dolor sit amet'),
   )
 
-  // Notice the 'not' particle
+  // Notice the 'not' particle.
   expect(console.log).not.toHaveBeenCalledWith(
     expect.stringContaining('Hello World'),
   )

src/__tests__/debug.js

@@ -9,15 +9,16 @@ test('waits for the data to be loaded', async () => {
   getByText('Loading...')
   expect(queryByText(/Loaded this message/)).not.toBeInTheDocument()
 
-  // Line reads as follows: "Wait until element with text 'Loading...' is gone."
+  // Following line reads as follows:
+  // "Wait until element with text 'Loading...' is gone."
   await waitForElementToBeRemoved(() => queryByText('Loading...'))
   // It is equivalent to:
   //
   // await wait(() => {
   //   expect(queryByText('Loading...')).not.toBeInTheDocument()
   // })
   //
-  // `wait()` waits until the callback function passes or times out.
+  // because `wait()` waits until the callback function passes or times out.
 
   // After 'Loading...' is gone, we can assert that fetched data is rendered.
   expect(queryByTestId('message')).toHaveTextContent(/Hello World/)

src/__tests__/disappearance.js

@@ -24,7 +24,7 @@ test('Review form submits', async () => {
 
   const submitButton = getByText('Submit')
 
-  // Initially the submit button should be disabled
+  // Initially the submit button should be disabled.
   expect(submitButton).toBeDisabled()
 
   const titleInput = getByLabelText(/title of the movie/i)
@@ -33,7 +33,7 @@ test('Review form submits', async () => {
   const reviewTextarea = getByPlaceholderText('Write an awesome review')
   await fireEvent.update(reviewTextarea, fakeReview.review)
 
-  // Rating Radio buttons
+  // Rating Radio buttons.
   const initiallySelectedInput = getByLabelText('Awful')
   const ratingSelect = getByLabelText('Wonderful')
 
@@ -45,23 +45,20 @@ test('Review form submits', async () => {
   expect(ratingSelect.checked).toBe(true)
   expect(initiallySelectedInput.checked).toBe(false)
 
-  // Get the Input element by its implicit ARIA role
+  // Get the Input element by its implicit ARIA role.
   const recommendInput = getByRole('checkbox')
 
   expect(recommendInput.checked).toBe(false)
   await fireEvent.update(recommendInput)
   expect(recommendInput.checked).toBe(true)
 
-  // NOTE: in jsdom, it's not possible to trigger a form submission
-  // by clicking on the submit button. This is really unfortunate.
-  // So the next best thing is to fireEvent a submit on the form itself
-  // then ensure that there's a submit button
+  // Make sure the submit button is enabled.
   expect(submitButton).toBeEnabled()
   expect(submitButton).toHaveAttribute('type', 'submit')
 
   await fireEvent.click(submitButton)
 
-  // Assert event has been emitted
+  // Assert the right event has been emitted.
   expect(emitted()).toHaveProperty('submit')
   expect(emitted().submit[0][0]).toMatchObject(fakeReview)
 })

src/__tests__/form.js

@@ -8,13 +8,13 @@ const Functional = {
   },
 }
 
-test('renders functional comp', () => {
+test('renders functional component', () => {
   const {getByText} = render(Functional)
 
   getByText('Hi!')
 })
 
-test('renders functional SFC comp', () => {
+test('renders functional SFC component', () => {
   const {getByText} = render(FunctionalSFC)
 
   getByText('Hi!')