Merge pull request #43 from afontcu/master

Improve onboarding by adding explanations

Author: afontcu

package-lock.json

@@ -31,7 +31,7 @@
   "author": "Daniel Cook",
   "license": "MIT",
   "dependencies": {
-    "@testing-library/dom": "^5.0.1",
+    "@testing-library/dom": "^5.2.0",
     "@vue/test-utils": "^1.0.0-beta.29",
     "vue": "^2.6.10",
     "vue-template-compiler": "^2.6.10"

package.json

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`makes an API call and displays the greeting when load-greeting is clicked 1`] = `
+<div><button>
+    Fetch
+  </button> <span>
+    hello there
+  </span></div>
+`;

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

@@ -0,0 +1,27 @@
+import axiosMock from 'axios'
+import { render, fireEvent } from '@testing-library/vue'
+import Component from './components/Fetch.vue'
+import 'jest-dom/extend-expect'
+
+test('makes an API call and displays the greeting when load-greeting is clicked', async () => {
+  axiosMock.get.mockImplementationOnce(() =>
+    Promise.resolve({
+      data: { greeting: 'hello there' }
+    })
+  )
+
+  const { html, getByText } = render(Component, { props: { url: '/greeting' } })
+
+  // Act
+  await fireEvent.click(getByText('Fetch'))
+
+  expect(axiosMock.get).toHaveBeenCalledTimes(1)
+  expect(axiosMock.get).toHaveBeenCalledWith('/greeting')
+  getByText('hello there')
+
+  // You can render component snapshots by using html(). However, bear in mind
+  // 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()
+})

tests/__tests__/__snapshots__/fetch.js.snap

@@ -1,25 +1,13 @@
 <template>
-  <button :class="typeClass" @click="handleClick">{{ text }}</button>
+  <button @click="handleClick">{{ text }}</button>
 </template>
 
 <script>
 export default {
   props: {
     text: {
       type: String,
-      default: ''
-    },
-    type: {
-      validator: value => ['primary', 'secondary'].includes(value),
-      default: 'primary'
-    }
-  },
-  computed: {
-    typeClass: function() {
-      if (this.type) {
-        return `button button--${this.type}`
-      }
-      return 'button'
+      required: true
     }
   },
   methods: {

tests/__tests__/axios-mock.js

@@ -1,10 +1,8 @@
 <template>
-  <div>
-    <div v-if="loading">Loading...</div>
-    <div v-else data-testid="message">
-      Loaded this message: {{ data.returnedMessage }}
-    </div>
-  </div>
+  <p v-if="loading">Loading...</p>
+  <p v-else data-testid="message">
+    Loaded this message: {{ data.returnedMessage }}
+  </p>
 </template>
 
 <script>
@@ -13,6 +11,7 @@ const fetchAMessage = () =>
     // we are using random timeout here to fireEvent a real-time example
     // of an async operation calling a callback at a non-deterministic time
     const randomTimeout = Math.floor(Math.random() * 100)
+
     setTimeout(() => {
       resolve({ returnedMessage: 'Hello World' })
     }, randomTimeout)

tests/__tests__/components/Button.vue

@@ -1,9 +1,9 @@
 <template>
   <div>
-    <button data-testid="load-greeting" @click="fetch">
+    <button @click="fetch">
       Fetch
     </button>
-    <span v-if="data" data-testid="greeting-text">
+    <span v-if="data">
       {{ data.greeting }}
     </span>
   </div>

tests/__tests__/components/EndToEnd.vue renamed to tests/__tests__/components/Disappearance.vue

@@ -40,7 +40,6 @@
         v-model="recommend"
         type="checkbox"
         name="recommend"
-        data-testid="recommend-checkbox"
       />
 
       <button :disabled="submitDisabled" type="submit">

tests/__tests__/components/Fetch.vue

@@ -1,7 +1,7 @@
 <template>
   <div>
     <span data-testid="elapsed">{{ lapse }}ms</span>
-    <button data-testid="start-stop-button" @click="handleRunClick">
+    <button @click="handleRunClick">
       {{ running ? 'Stop' : 'Start' }}
     </button>
   </div>

tests/__tests__/components/Form.vue

@@ -10,7 +10,7 @@
       aria-labelledby="username-label"
     />
 
-    <span v-show="errors.has('username')" data-testid="username-errors">{{
+    <span v-if="errors.has('username')" data-testid="username-errors">{{
       errors.first('username')
     }}</span>
 

tests/__tests__/components/StopWatch.vue

@@ -0,0 +1,28 @@
+import { render, waitForElementToBeRemoved } from '@testing-library/vue'
+import Disappearance from './components/Disappearance'
+import 'jest-dom/extend-expect'
+
+test('it waits for the data to be loaded', async () => {
+  const { getByText, queryByText, queryByTestId } = render(Disappearance)
+
+  // Assert initial state
+  getByText('Loading...')
+  expect(queryByText(/Loaded this message/)).not.toBeInTheDocument()
+
+  // Line reads as follows "Wait until element with test '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.
+
+  // After 'Loading...' element is gone, we can assert that fetched data is
+  // rendered.
+  expect(queryByTestId('message')).toHaveTextContent(/Hello World/)
+
+  // Read more about async utilities:
+  // https://testing-library.com/docs/dom-testing-library/api-async
+})

tests/__tests__/components/Validate.vue

@@ -14,7 +14,7 @@ test('Review form submits', async () => {
   const {
     getByLabelText,
     getByText,
-    getByTestId,
+    getByRole,
     getByDisplayValue,
     getByPlaceholderText,
     emitted
@@ -44,7 +44,8 @@ test('Review form submits', async () => {
   const genreSelect = getByDisplayValue('Comedy')
   await fireEvent.update(genreSelect, fakeReview.genre)
 
-  const recommendInput = getByTestId('recommend-checkbox')
+  // Get the Input element by its implicit ARIA role.
+  const recommendInput = getByRole('checkbox')
   await fireEvent.update(recommendInput, fakeReview.recommend)
 
   // NOTE: in jsdom, it's not possible to trigger a form submission

tests/__tests__/components/queries/AltText.vue

@@ -1,22 +1,29 @@
 import { render, cleanup, fireEvent } from '@testing-library/vue'
-import SimpleButton from './components/Button'
+import Button from './components/Button'
+import 'jest-dom/extend-expect'
 
 afterEach(cleanup)
 
 test('renders button with text', () => {
-  const buttonText = "Click me; I'm sick"
-  const { getByText } = render(SimpleButton, {
-    props: { text: buttonText }
+  const text = "Click me; I'm sick"
+
+  // Set the prop value by using the second argument of `render()`
+  const { getByRole } = render(Button, {
+    props: { text }
   })
 
-  getByText(buttonText)
+  expect(getByRole('button')).toHaveTextContent(text)
 })
 
-test('click event is emitted when button is clicked', () => {
+test('click event is emitted when button is clicked', async () => {
   const text = 'Click me'
-  const { getByText, emitted } = render(SimpleButton, {
+
+  const { getByRole, emitted } = render(Button, {
     props: { text }
   })
-  fireEvent.click(getByText(text))
+
+  // Send a click event to the element with a 'button' role
+  await fireEvent.click(getByRole('button'))
+
   expect(emitted().click).toHaveLength(1)
 })

tests/__tests__/components/queries/Attribute.vue

@@ -10,10 +10,13 @@ test('unmounts a component', async () => {
   const { unmount, isUnmounted, getByText } = render(StopWatch)
   await fireEvent.click(getByText('Start'))
 
+  // Destroys a Vue component instance.
   unmount()
+
   expect(isUnmounted()).toBe(true)
 
   await wait()
+
   expect(console.error).not.toHaveBeenCalled()
 })
 
@@ -23,11 +26,21 @@ test('updates component state', async () => {
   const startButton = getByText('Start')
   const elapsedTime = getByTestId('elapsed')
 
+  // Assert initial state.
   expect(elapsedTime).toHaveTextContent('0ms')
+  getByText('Start')
 
   await fireEvent.click(startButton)
+
+  getByText('Stop')
+
+  // Wait for one tick of the event loop.
   await wait()
+
+  // Stop the timer.
   await fireEvent.click(startButton)
 
+  // We can't assert a specific amount of time. Instead, we assert that the
+  // content has changed.
   expect(elapsedTime).not.toHaveTextContent('0ms')
 })

tests/__tests__/components/queries/Empty.vue

@@ -0,0 +1,19 @@
+import NumberDisplay from './components/NumberDisplay.vue'
+import { render } from '@testing-library/vue'
+import 'jest-dom/extend-expect'
+
+test('calling render with the same component but different props does not remount', async () => {
+  const { getByTestId, updateProps } = render(NumberDisplay, {
+    props: { number: 1 }
+  })
+
+  expect(getByTestId('number-display')).toHaveTextContent('1')
+
+  await updateProps({ number: 2 })
+
+  expect(getByTestId('number-display')).toHaveTextContent('2')
+
+  // Assert that, even after updating props, the component hasn't remounted,
+  // meaning we are testing the same component instance we rendered initially.
+  expect(getByTestId('instance-id')).toHaveTextContent('1')
+})

tests/__tests__/components/queries/GetByAltText.vue

@@ -5,14 +5,24 @@ import { render, fireEvent } from '@testing-library/vue'
 import Validate from './components/Validate'
 
 test('can validate using plugin', async () => {
-  const { getByPlaceholderText, queryByTestId } = render(Validate, {}, vue =>
-    vue.use(VeeValidate, { events: 'blur' })
+  // The third argument of `render` is a callback function that receives the
+  // Vue instance as a parameter. This way, we can register plugins such as
+  // VeeValidate.
+  const { getByPlaceholderText, queryByTestId, getByTestId } = render(
+    Validate,
+    {},
+    vue => vue.use(VeeValidate, { events: 'blur' })
   )
 
+  // Assert error messages are not in the DOM when rendering the component.
+  expect(queryByTestId('username-errors')).toBeNull()
+
   const usernameInput = getByPlaceholderText('Username...')
   await fireEvent.touch(usernameInput)
 
-  expect(queryByTestId('username-errors')).toHaveTextContent(
+  // After "touching" the input (focusing and blurring), validation error
+  // should appear.
+  expect(getByTestId('username-errors')).toHaveTextContent(
     'The username field is required.'
   )
 })

tests/__tests__/components/queries/JestHelpers.vue

@@ -15,16 +15,20 @@ const routes = [
 afterEach(cleanup)
 
 test('full app rendering/navigating', async () => {
+  // Notice how we pass a `routes` object to our render function.
   const { queryByTestId } = render(App, { routes })
 
-  // normally I'd use a data-testid, but just wanted to show this is also possible
   expect(queryByTestId('location-display')).toHaveTextContent('/')
+
   await fireEvent.click(queryByTestId('about-link'))
 
   expect(queryByTestId('location-display')).toHaveTextContent('/about')
 })
 
 test('setting initial route', () => {
+  // The callback function receives three parameters: the Vue instance where
+  // the component is mounted, the store instance (if any) and the router
+  // object.
   const { queryByTestId } = render(App, { routes }, (vue, store, router) => {
     router.push('/about')
   })