DEV Community: Emarsys Craftlab

React Testing Crash Course

Gábor Soós — Wed, 13 May 2020 14:39:33 +0000

You have nearly finished your project, and only one feature is left. You implement the last one, but bugs appear in different parts of the system. You fix them, but another one pops up. You start playing a whack-a-mole game, and after multiple turns, you feel messed up. But there is a solution, a life-saver that can make the project shine again: write tests for the future and already existing features. This guarantees that working features stay bug-free.

In this tutorial, I’ll show you how to write unit, integration and end-to-end tests for React applications.

For more test examples, you can take a look at my React TodoMVC or React Hooks TodoMVC implementation.

1. Types

Tests have three types: unit, integration and end-to-end. These test types are often visualized as a pyramid.

The pyramid indicates that tests on the lower levels are cheaper to write, faster to run and easier to maintain. Why don’t we write only unit tests then? Because tests on the upper end give us more confidence about the system and they check if the components play well together.

To summarize the difference between the types of tests: unit tests only work with a single unit (class, function) of code in isolation, integration tests check if multiple units work together as expected (component hierarchy, component + store), while end-to-end tests observe the application from the outside world (browser).

2. Test runner

For new projects, the easiest way to add testing to your project is through the Create React App tool. When generating the project (npx create-react-app myapp), you don't need to enable testing. Unit/integration tests can be written in the src directory with *.spec.js or *.test.js suffix. Create React App uses the Jest testing framework to run these files. Jest isn't just a test runner, it also includes an assertion library in contrary to Mocha.

3. Single unit

So far, so good, but we haven’t written any tests yet. Let’s write our first unit test!

describe('toUpperCase', () => {
  it('should convert string to upper case', () => {
    // Arrange
    const toUpperCase = info => info.toUpperCase();

    // Act
    const result = toUpperCase('Click to modify');

    // Assert
    expect(result).toEqual('CLICK TO MODIFY');
  });
});

The above is an example verifies if the toUpperCase function converts the given string to upper case.

The first task (arrange) is to get the target (here a function) into a testable state. It can mean importing the function, instantiating an object, and setting its parameters. The second task is to execute that function/method (act). After the function has returned the result, we make assertions for the outcome.

Jest gives us two functions: describe and it. With the describe function we can organize our test cases around units: a unit can be a class, a function, component, etc. The it function stands for writing the actual test-case.

Jest has a built-in assertion library and with it, we can set expectations on the outcome. Jest has many different built-in assertions. These assertions, however, do not cover all use-cases. Those missing assertions can be imported with Jest's plugin system, adding new types of assertions to the library (like Jest Extended and Jest DOM).

Most of the time, you will be writing unit tests for the business logic that resides outside of the component hierarchy, for example, state management or backend API handling.

4. Component display

The next step is to write an integration test for a component. Why is it an integration test? Because we no longer test only the Javascript code, but rather the interaction between the DOM as well as the corresponding component logic.

In the component examples, I'll use Hooks, but if you write components with the old syntax it won't affect the tests, they're the same.

import React, { useState } from 'react';

export function Footer() {
  const [info, setInfo] = useState('Click to modify');
  const modify = () => setInfo('Modified by click');

  return (
    <div>
      <p className="info" data-testid="info">{info}</p>
      <button onClick={modify} data-testid="button">Modify</button>
    </div>
  );
}

The first component we test is one that displays its state and modifies the state if we click the button.

import React from 'react';
import { render } from '@testing-library/react';
import { Footer } from './Footer.js';

describe('Footer', () => {
  it('should render component', () => {
    const { getByTestId } = render(<Footer />);

    const element = getByTestId('info');

    expect(element).toHaveTextContent('Click to modify');
    expect(element).toContainHTML('<p class="info" data-testid="info">Click to modify</p>');
    expect(element).toHaveClass('info');
    expect(element).toBeInstanceOf(HTMLParagraphElement);
  });
});

To render a component in a test, we can use the recommended React Testing Library's render method. The render function needs a valid JSX element to render. The return argument is an object containing selectors for the rendered HTML. In the example, we use the getByTestId method that retrieves an HTML element by its data-testid attribute. It has many more getter and query methods, you can find them in the documentation.

In the assertions, we can use the methods from the Jest Dom plugin, which extends Jests default assertion collection making HTML testing easier. The HTML assertion methods all expect an HTML node as input and access its native properties.

5. Component interactions

We have tested what can we see in the DOM, but we haven’t made any interactions with the component yet. We can interact with a component through the DOM and observe the changes through its content. We can trigger a click event on the button and observe the displayed text.

import { render, fireEvent } from '@testing-library/react';

it('should modify the text after clicking the button', () => {
  const { getByTestId } = render(<Footer />);

  const button = getByTestId('button');
  fireEvent.click(button);
  const info = getByTestId('info');

  expect(info).toHaveTextContent('Modified by click');
});

We need a DOM element where the event can be triggered. The getters returned from the render method returns that element. The fireEvent object can trigger the desired events trough its methods on the element. We can check the result of the event by observing the text content as before.

6. Parent-child interactions

We have examined a component separately, but a real-world application consists of multiple parts. Parent components talk to their children through props, and children talk to their parents through function props.

Let’s modify the component that it receives the display text through props and notifies the parent component about the modification through a function prop.

import React from 'react';

export function Footer({ info, onModify }) {
  const modify = () => onModify('Modified by click');

  return (
    <div>
      <p className="info" data-testid="info">{info}</p>
      <button onClick={modify} data-testid="button">Modify</button>
    </div>
  );
}

In the test, we have to provide the props as input and check if the component calls the onModify function prop.

it('should handle interactions', () => {
  const info = 'Click to modify';
  let callArgument = null;
  const onModify = arg => callArgument = arg;
  const { getByTestId } = render(<Footer info={info} onModify={onModify} />);

  const button = getByTestId('button');
  fireEvent.click(button);

  expect(callArgument).toEqual('Modified by click');
});

We pass down the info prop and the onModify function prop through JSX to the component. When we trigger the click event on the button, the onModify method is called and it modifies the callArgument variable with its argument. The assertion at the end checks the callArgument whether it was modified by the child components function prop.

7. Store integration

In the previous examples, the state was always inside the component. In complex applications, we need to access and mutate the same state in different locations. Redux, a state management library that can be easily connected to React, can help you organize state management in one place and ensure it mutates predictably.

import { createStore } from 'redux';

function info(state, action) {
  switch (action.type) {
    case 'MODIFY':
      return action.payload;
    default:
      return state;
  }
}

const onModify = info => ({ type: 'MODIFY', payload: info });
const store = createStore(info, 'Click to modify');

The store has a single state, which is the same as what we have seen on the component. We can modify the state with the onModify action that passes the input parameter to the reducer and mutates the state.

Let's construct the store and write an integration test. This way, we can check if the methods play together instead of throwing errors.

it('should modify state', () => {
  store.dispatch(onModify('Modified by click'));

  expect(store.getState()).toEqual('Modified by click');
});

We can alter the store through the dispatch method. The parameter to the method should be an action with the type property and payload. We can always check the current state through the getState method.

When using the store with a component, we have to pass the store instance as a provider to the render function.

const { getByTestId } = render(
  <Provider store={store}>
    <Header />
  </Provider>
);

8. Routing

The simplest way of showing how to test routing inside a React app is to create a component that displays the current route.

import React from 'react';
import { withRouter } from 'react-router';
import { Route, Switch } from 'react-router-dom';

const Footer = withRouter(({ location }) => (
  <div data-testid="location-display">{location.pathname}</div>
));

const App = () => {
  return (
    <div>
      <Switch>
        <Route component={Footer} />
      </Switch>
    </div>
  )
};

The Footer component is wrapped with the withRouter method, which adds additional props to the component. We need another component (App) that wraps the Footer and defines the routes. In the test, we can assert the content of the Footer element.

import { Router } from 'react-router-dom';
import { createMemoryHistory } from 'history';
import { render } from '@testing-library/react';

describe('Routing', () => {
  it('should display route', () => {
    const history = createMemoryHistory();
    history.push('/modify');

    const { getByTestId } = render(
      <Router history={history}>
        <App/>
      </Router>
    );

    expect(getByTestId('location-display')).toHaveTextContent('/modify');
  });
});

We have added our component as a catch-them-all route by not defining a path on the Route element. Inside the test it is not advised to modify the browsers History API, instead, we can create an in-memory implementation and pass it with the history prop at the Router component.

9. HTTP requests

Initial state mutation often comes after an HTTP request. While it is tempting to let that request reach its destination in a test, it would also make the test brittle and dependant on the outside world. To avoid this, we can change the request’s implementation at runtime, which is called mocking. We will use Jest's built-in mocking capabilities for it.

const onModify = async ({ commit }, info) => {
  const response = await axios.post('https://example.com/api', { info });
  commit('modify', { info: response.body });
};

We have a function: the input parameter is first sent through a POST request, and then the result is passed to the commit method. The code becomes asynchronous and gets Axios as an external dependency. The external dependency will be the one we have to change (mock) before running the test.

it('should set info coming from endpoint', async () => {
  const commit = jest.fn();
  jest.spyOn(axios, 'post').mockImplementation(() => ({
    body: 'Modified by post'
  }));

  await onModify({ commit }, 'Modified by click');

  expect(commit).toHaveBeenCalledWith('modify', { info: 'Modified by post' });
});

We are creating a fake implementation for the commit method with jest.fn and change the original implementation of axios.post. These fake implementations capture the arguments passed to them and can respond with whatever we tell them to return (mockImplementation). The commit method returns with an empty value because we haven't specified one. axios.post will return with a Promise that resolves to an object with the body property.

The test function becomes asynchronous by adding the async modifier in front of it: Jest can detect and wait for the asynchronous function to complete. Inside the function, we wait for the onModify method to complete with await and then make an assertion wether the fake commit method was called with the parameter returned from the post call.

10. The browser

From a code perspective, we have touched every aspect of the application. There is a question we still can’t answer: can the application run in the browser? End-to-end tests written with Cypress can answer this question.

Create React App doesn't have a built-in E2E testing solution, we have to orchestrate it manually: start the application and run the Cypress tests in the browser, and then shut down the application. It means installing Cypress for running the tests and start-server-and-test library to start the server. If you want to run the Cypress tests in headless mode, you have to add the --headless flag to the command.

describe('New todo', () => {
  it('it should change info', () => {
    cy.visit('/');

    cy.contains('.info', 'Click to modify');

    cy.get('button').click();

    cy.contains('.info', 'Modified by click');
  });
});

The organization of the tests is the same as with unit tests: describe stands for grouping, it stands for running the tests. We have a global variable, cy, which represents the Cypress runner. We can command the runner synchronously about what to do in the browser.

After visiting the main page (visit), we can access the displayed HTML through CSS selectors. We can assert the contents of an element with contains. Interactions work the same way: first, select the element (get) and then make the interaction (click). At the end of the test, we check if the content has changed or not.

Summary

We have reached the end of testing use-cases. I hope you enjoyed the examples and they clarified many things around testing. I wanted to lower the barrier of starting to write tests for a React application. We have gone from a basic unit test for a function to an end-to-end test running in a real browser.

Through our journey, we have created integration tests for the building blocks of a React application (components, store, router) and scratched the surface of implementation mocking. With these techniques, your existing and future projects can stay bug-free.

The missing Docker Cheatsheet

Gábor Soós — Tue, 18 Feb 2020 15:43:37 +0000

Docker is becoming increasingly popular among software developers as a container platform. Containers package software in a format that can run isolated on a host operating system. Bundled with only essential libraries and settings, Docker renders lightweight, efficient, self-contained systems that run identically wherever deployed. In this cheat sheet, we'll take a use-case oriented approach: building the image, starting it, and in the end, stopping it and cleaning up after ourselves.

Creating your container

To follow along with the commands, I've borrowed an application with its Dockerfile from my repository representing an ideal Node.js Docker workflow.

# Dockerfile.short
FROM node:12-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

EXPOSE 3000

CMD npm start

The application is an Express web server that responds to incoming HTTP requests.

const express = require('express');
const port = process.env.PORT || 3000;
const app = express();

app.get('/', (req, res) => res.send('Hello World!'));

app.listen(port, () => console.log(`App listening on port ${port}!`));

We'll build and run this file with the upcoming commands.

docker build -f <docker filename> -t <image name> <build context>

Pulls the base image, builds the image inside Dockerfile.short, and names it as express. We can use this name when running the image. The name can contain a tag (express:1): by default, it gets the latest tag. Specifying the name of the Dockerfile is only necessary when it defers from Dockerfile. The dot at the end tells that the build context is the current directory.

docker build -f Dockerfile.short -t express .

Sending build context to Docker daemon  180.7kB
Step 1/7 : FROM node:12-alpine
12-alpine: Pulling from library/node
c9b1b535fdd9: Pull complete 
750cdd924064: Pull complete 
2078ab7cf9df: Pull complete 
02f523899354: Pull complete 
Digest: sha256:e280e51eaa6e626e4df58a5c1f141e453807c30596179330992c55a0bf4114ca
Status: Downloaded newer image for node:12-alpine
 ---> afd897e3184b
Step 2/7 : WORKDIR /app
 ---> Running in c8f379e36c32
Removing intermediate container c8f379e36c32
 ---> a11ced1bd480
Step 3/7 : COPY package*.json ./
 ---> e811deacf584
Step 4/7 : RUN npm ci --only=production
 ---> Running in 401bdc088d44
added 50 packages in 1.395s
Removing intermediate container 401bdc088d44
 ---> 644c8661eff7
Step 5/7 : COPY . .
 ---> 270057bb701a
Step 6/7 : EXPOSE 3000
 ---> Running in cd9d70daad58
Removing intermediate container cd9d70daad58
 ---> 4c6eb54071d1
Step 7/7 : CMD npm start
 ---> Running in fc2a7b3e7e11
Removing intermediate container fc2a7b3e7e11
 ---> d85b87f880e3
Successfully built d85b87f880e3
Successfully tagged express:latest

docker images

Shows all the runnable images on the host machine. We'll see our application with the name express.

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
express             latest              d85b87f880e3        3 minutes ago       87.6MB
node                12-alpine           afd897e3184b        3 days ago          85.2MB

docker run -p <host port>:<container port> <image name>

Runs the built image and connects the containers port with the host machines port (-p 3000:3000). The result is the application is available on http://localhost:3000. If we don't want to block the terminal, we can run the image in detached mode -d. If we're going to have live-reload on file changes, for example, with Nodemon, we can attach the local folder as a volume -v $(pwd):/app.

docker run -p 3000:3000 -v $(pwd):/app express

docker ps -a

Lists the running containers. After docker run, we'll see the application here.

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
ec40c8347a43        express             "docker-entrypoint.s…"   6 seconds ago       Up 5 seconds        0.0.0.0:3000->3000/tcp   hardcore_vaughan

The -a flag shows all the containers, not just the running ones.

docker logs -f -t <image id>

Shows the standard output with timestamps from the running container.

docker logs -f -t ec40c8347a43

2020-02-10T18:22:07.672710300Z
2020-02-10T18:22:07.672788300Z > node-docker-workflow@1.0.0 start /app
2020-02-10T18:22:07.672825700Z > node src/index.js
2020-02-10T18:22:07.672850600Z
2020-02-10T18:22:07.917358100Z App listening on port 3000!

The -f flag tells the command to listen for new logs. If all the records are too much, you can restrict it to only some lines --tail 100.

Publishing the image

Our application is running fine on our local computer, but we can't deploy it anywhere. For deployment, we have to publish it to a repository. For demonstration purposes, we'll use the default DockerHub repository.

docker login

Logs in to the repository, by default to Dockerhub. We need a Dockerhub account before this to work. You can do the registration here.

Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
Username: blacksonic
Password: 
Login Succeeded

docker tag <source image name>:<target tag name> <target image name>:<target tag name>

Names the image with a tag that we will use when uploading the image.

docker tag express:latest blacksonic/express:latest

We have to prefix the image name before uploading it to Dockerhub (blacksonic is my username).

docker push <image name>:<tag name>

Uploads the image to the repository. You can see the uploaded image now on the site https://hub.docker.com/r/blacksonic/express.

docker push blacksonic/express:latest

The push refers to repository [docker.io/blacksonic/express]
d93ac2ab321f: Pushed 
5216338b40a7: Pushed 
latest: digest: sha256:8b418f814535e24906fcb412f8e564ced393e4976586d710bbff60b5fdb2d11c size: 1993

Cleaning it up

We've started and pushed our container successfully. It's time to clean up after ourselves.

docker stop <container id>

Stops the running container. The container won't be deleted.

docker stop ec40c8347a43

docker rm <container id>

Deletes the container, you won't be able to start it again.

docker rm ec40c8347a43

docker rmi <image id>

Deletes the image: you'll have to build it again to start it as a container.

docker rmi d85b87f880e3

docker stop $(docker ps -a -q)

Stops all processes from running containers. After this, docker ps -a will return empty results.

docker rm $(docker ps -a -q)

Removes all the containers.

docker rmi $(docker images -q)

Removes all the images. After this, docker images will return empty results.

docker image prune --all

Removes all unused images. Unused means no running containers exist based on the image.

Summary

Encountering containerization can be hard for the first time, but can be simplified by knowing the right commands which can tell what's happening. With an example configuration, you can try them, and you realize that developing with containers can be as easy as doing it on your local machine.

A simple Node.js Docker workflow

Gábor Soós — Tue, 28 Jan 2020 15:25:52 +0000

Docker is a great tool that helps developers build, deploy, and run applications more efficiently in a standardized way. We can develop in the same environment as the app running in production. You can speed up the debugging or even the prevention of upcoming bugs by having the same setup locally. In the previous post, I've written about a simplified way to use Docker for frontend development, and now I'll show the same for Node.js projects.

The application

As an example, I've put together a basic application and tried to keep it as simple as it can be. If you like experimenting on your own, you can clone the repository and start making modifications and see how it does.

// src/index.js
'use strict';
const express = require('express');
const port = process.env.PORT || 3000;
const app = express();

app.get('/', (req, res) => res.send('Hello World!'));

app.listen(port, () => console.log(`App listening on port ${port}!`));

The application consists of a single file that spins up a web server and responds to requests. I've used the well-known Express web framework to respond to requests and made the port configurable through an environment variable. We need it to be configurable because this port can alter from the one used in development.

Development

For development, we would like to have

the same environment as in production
set up the environment easily
see file changes automatically in the browser
use code completion in the editor

To accomplish all the requirements, we will be using Docker with Docker Compose to create an identical container for both development and production and the Nodemon package to restart the application on file changes.

We can restart on file changes by changing the startup script from node src/index.js to nodemon --watch src src/index.js. It does the same as before with the addition of restarting it whenever a file changes inside the src folder.

Let's get to the more exciting part where we spin up the container locally.

# docker-compose.yml
version: "3"

services:
  server:
    image: node:12
    working_dir: /app
    volumes:
      - ./:/app
    ports:
      - 3000:3000
    environment:
      - PORT=3000
    command: sh -c "npm install && npm run dev"

The first thing you may notice is that the Docker Compose configuration file doesn't contain a custom Docker image. In most cases, we don't need it, but if it's necessary, we can always add it with the build property. In our setup, we'll use the Node base image.

Instead of copying the files in a Dockerfile, I've chosen the two-way synchronization of files with volumes. It's more resource-hungry than copying the files, but the fact that installed NPM packages appear on the host machine that makes code-completion available promotes it as a no-brainer.

We shouldn't take things for granted: we set the configurable environment variables. In our case, the port is configurable, where the server listens for incoming calls. Setting it in the config makes it more readable as it is next to the ports definition: the place where we declare which internal container ports we would like to see as exposed on the host machine.

The last step is to start the application with the command property. We always run the npm install command, which can affect startup performance a bit, but also ensures that the dependencies are still up-to-date when the container is running. You can remove it from the command, but this way, you have to manually run it before starting the container or when the contents of the package.json file changes.

Production

We can happily develop the application with the previous setup, but we also have to create a deployable container to production. At this point, it's not possible to further postpone the creation of a custom docker image. Let's see how it can be an optimal one.

# Dockerfile
FROM node:12 AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:12-alpine
WORKDIR /app
COPY --from=base /app .
COPY . .

EXPOSE 3000

CMD npm start

The file starts with declaring the starting image, which is called 'base'. Naming it is not necessary, but clarifies a lot when using Dockers multi-stage build.

We have to copy only the package files as they are necessary for installing the same versions used for development. The command npm install is changed to npm ci --only=production. It has two main differences. npm ci installs the same versions defined in the lock file and doesn't try to update them as npm install does. The second one is the --only=production flag that skips the installation of devDependencies, which we don't need in production.

We've saved much precious space from the image by skipping devDependencies, but the image is still significant (circa 500 MB). Node has a much smaller image called alpine, which only contains packages necessary packages: and fewer packages mean less disk space, memory, better speed, and security. Package installs sometimes require the standard image, but with Docker multi-stage builds, we can switch to the smaller image after the package install and copy the packages from the previous step. This way, we get the best of both worlds: small image size and the ability to install anything.

If we look at the size of the image with docker images, we can see that it has shrunk under 100 MB. The image is ready; we can deploy it to production.

Summary

At first, I didn't feel why I should complicate my everyday life with another technology necessary for development. Others had to show me that with synchronized folders with volumes I won't be able to tell the difference between developing on my local machine. After this and the fact that I can test against the same infrastructure on my local computer, they have convinced me to use Docker daily. I hope the above workflow helps others also to get to love Docker for its benefits.

Frontend Development with Docker simplified

Gábor Soós — Thu, 16 Jan 2020 15:14:01 +0000

Docker is a great tool that helps developers build, deploy, and run applications more efficiently in a standardized way. For frontend applications, we only need the Docker image for local development, because we deploy it to a static hosting provider. In this case, can we live without a custom Docker image? Can we have the same development experience that we had without Docker? Yes, it is easier than you think.

Requirements

Assume an application where we only have to press start, and everything is running. This setup can be any application generated by the React, Vue, Angular CLI. For demonstration purposes, I'll use my Vue Todo application.

During development, we will be doing the following steps:

install dependencies with npm install
start the application with npm start
modify a file and check the changes in the browser
use code-completion of modules in the editor
add a new dependency to package.json and install it

Custom Docker file

If you search the web for frontend development with Docker, you can find many articles using a custom Docker image. Let's have a look at and see how it works.

The Docker file starts with defining the base image (Node.js 12.x) on what we will build upon (FROM) and setting the working directory to the /app folder (WORKDIR). Every command starting with RUN or CMD will have this folder as the default working directory.

The next step is to copy the source files (COPY) and install the dependencies. We copy the package.json separately from the rest of the files. Why? Because Docker caches every step of the Dockerfile when building the image multiple times. When don't modify anything and build the image again, it won't do anything as the steps are cached. If we change a Javascript file, Docker will run the commands from COPY . /app. When we modify the package.json file, Docker will rerun the commands from COPY package.json /app.

By default, applications running inside the container on a specific port are not available on the host machine. We have to make the port available (EXPOSE). Only after this can we type the URL in our browser (http://localhost:8900) and see the result.

To run this image, we have to build it and run the created container.

# Build the image: docker build -t <image-name> <relative-path-to-dockerfile>
docker build -t client .
# Run the image: docker container run -p <host port:container port> <image-name>  
docker container run -p 8900:8900 client

Disadvantages

The above Docker image works but has multiple drawbacks:

Files generated inside the container are not visible from the host machine, only inside the container. It means that we won't see the node_modules folder on our host machine, and because of this, we lose code-completion in the editor. We can't commit the generated package.lock.json to source control because it is not available on the host machine also.
We have to stop, build, and rerun the container on dependency and file changes. We lose the ability of live-reload.

Meet Docker Compose

Docker can build single images and run the built containers. Docker Compose steps a bit further as it can build and run multiple images at the same time. In this tutorial, we won't be using the numerous build capability; we'll use it only to overcome the disadvantages of the previous example.

While we can use the previous Dockerfile to run with Docker Compose, we will use it in a way to skip the writing of a custom image.

Instead of defining the image with a sequence of commands, Docker Compose uses the YAML config file format. Under the services key, the image for the Vue application is named client. It is the equivalent to the naming in the docker build -t <image-name> command. The description starts the same way here: defining the base image (image) and setting the working directory (working_dir).

The key difference comes from the volumes property. By using it, the local folder is synchronized with the container. If we execute the npm install command in the container, the node_modules folder will appear on the host machine also: we get the code completion and the lock file.

The application starts in the container also (command: sh -c "npm install && npm start"), exposing the port to the host machine is necessary for browser access (ports).

To run this setup, we have to build it and run the built container.

# Build the image and start the container
docker-compose up

If you look at the two solutions they are nearly identical. There is a great correlation between the commands in the Dockerfile and the configuration fields in the docker-compose.yml config file. The only difference is how they handle mounted files and this is what solves our synchronization issue.

Summary

When doing local development it is important to have a fast feedback loop and code completion. If we go with the pure Docker solution we lose both. We have to ask for the help of Docker big brother Docker Compose to help us with its folder synchronization. By migrating our setup to Docker Compose we get back the speed and code completion. I hope this trick helps you and saves a ton of development time.

Special thanks to iben for helping me with the setup.

Vue Testing Crash Course

Gábor Soós — Tue, 17 Dec 2019 16:04:38 +0000

In this tutorial, I'll show you how to write unit, integration and end-to-end tests for Vue applications.

For more test examples, you can take a look at my Vue TodoApp implementation.

1. Types

Tests have three types: unit, integration and end-to-end. These test types are often visualized as a pyramid.

The pyramid indicates that tests on the lower levels are cheaper to write, faster to run and easier to maintain. Why don't we write only unit tests then? Because tests on the upper end give us more confidence about the system and they check if the components play well together.

2. Test runner

For new projects, the easiest way to add testing to your project is through the Vue CLI. When generating the project (vue create myapp), you have to manually select Unit Testing and E2E Testing.

When the installation is finished, multiple additional dependencies will appear in your package.json file:

@vue/cli-plugin-unit-mocha: plugin for unit/integration tests with Mocha
@vue/test-utils: helper library for unit/integration testing
chai: assertion library Chai

From now on, unit/integration tests can be written in the tests/unit directory with *.spec.js suffix. The directory of the tests is not hardwired; you can modify it with a command-line argument:

vue-cli-service test:unit --recursive 'src/**/*.spec.js'

The recursive parameter tells the test runner to search for the test files based on the following glob pattern.

3. Single unit

So far, so good, but we haven't written any tests yet. Let's write our first unit test!

describe('toUpperCase', () => {
  it('should convert string to upper case', () => {
    // Arrange
    const toUpperCase = info => info.toUpperCase();

    // Act
    const result = toUpperCase('Click to modify');

    // Assert
    expect(result).to.eql('CLICK TO MODIFY');
  });
});

This verifies if the toUpperCase function converts the given string to upper case.

The first thing to do (arrange) is to get the target (here a function) into a testable state. It can mean importing the function, instantiating an object, and setting its parameters. The second thing is to execute that function/method (act). Finally, after the function has returned the result, we make assertions for the outcome.

Mocha gives us two functions describe and it. With the describe function we can organize our test cases around units: a unit can be a class, a function, component, etc. Mocha doesn't have a built-in assertion library, that's why we have to use Chai: it can set expectations on the outcome. Chai has many different built-in assertions. These assertions, however, do not cover all use-cases. Those missing assertions can be imported with Chai's plugin system, adding new types of assertions to the library.

Most of the time, you will be writing unit tests for the business logic that resides outside of the component hierarchy, for example, state management or backend API handling.

4. Component display

// src/components/Footer.vue
<template>
  <p class="info">{{ info }}</p>
  <button @click="modify">Modify</button>
</template>
<script>
  export default {
    data: () => ({ info: 'Click to modify' }),
    methods: {
      modify() {
        this.info = 'Modified by click';
      }
    }
  };
</script>

The first component we test is one that displays its state and modifies the state if we click the button.

// test/unit/components/Footer.spec.js
import { expect } from 'chai';
import { shallowMount } from '@vue/test-utils';
import Footer from '@/components/Footer.vue';

describe('Footer', () => {
  it('should render component', () => {
    const wrapper = shallowMount(Footer);

    const text = wrapper.find('.info').text();
    const html = wrapper.find('.info').html();
    const classes = wrapper.find('.info').classes();
    const element = wrapper.find('.info').element;

    expect(text).to.eql('Click to modify');
    expect(html).to.eql('<p class="info">Click to modify</p>');
    expect(classes).to.eql(['info']);
    expect(element).to.be.an.instanceOf(HTMLParagraphElement);
  });
});

To render a component in a test, we have to use shallowMount or mount from Vue Test Utils. Both methods render the component, but shallowMount doesn't render its child components (child elements will be empty elements). When including the component under test, we can reference it relatively ../../../src/components/Footer.vue or use the provided alias @. The @ sign at the start of the path references the source folder src.

We can search in the rendered DOM with the find selector and retrieve its HTML, text, classes or native DOM element. If we are searching for a non-existing fragment, the exists method can tell if it exists. It is enough to write one of the assertions; they stand there only to show the different possibilities.

5. Component interactions

We have tested what can we see in the DOM, but we haven't made any interactions with the component. We can interact with a component through the component instance or the DOM.

it('should modify the text after calling modify', () => {
  const wrapper = shallowMount(Footer);

  wrapper.vm.modify();

  expect(wrapper.vm.info).to.eql('Modified by click');
});

The above example shows how to do it with the component instance. We can access the component instance with the vm property. Functions under methods and properties on the data object (state) are available on the instance. In this case, we don't touch the DOM.

The other way is to interact with the component through the DOM. We can trigger a click event on the button and observe the displayed text.

it('should modify the text after clicking the button', () => {
  const wrapper = shallowMount(Footer);

  wrapper.find('button').trigger('click');
  const text = wrapper.find('.info').text();

  expect(text).to.eql('Modified by click');
});

We trigger the click event on the button, and it results in the same outcome as we have called the modify method on the instance.

6. Parent-child interactions

Let's modify the component that it receives the display text through props and notifies the parent component about the modification through an emitted event.

export default {
  props: ['info'],
  methods: {
    modify() {
      this.$emit('modify', 'Modified by click');
    }
  }
};

In the test, we have to provide the props as input and listen to the emitted events.

it('should handle interactions', () => {
  const wrapper = shallowMount(Footer, {
    propsData: { info: 'Click to modify' }
  });

  wrapper.vm.modify();

  expect(wrapper.vm.info).to.eql('Click to modify');
  expect(wrapper.emitted().modify).to.eql([
    ['Modified by click']
  ]);
});

The method shallowMount and mount has a second optional parameter, where we can set the input props with propsData. The emitted events become available from the emitted methods result. The name of the event will be the object key, and each event will be an entry in the array.

7. Store integration

In the previous examples, the state was always inside the component. In complex applications, we need to access and mutate the same state in different locations. Vuex, the state management library for Vue, can help you organize state management in one place and ensure it mutates predictably.

const store = {
  state: {
    info: 'Click to modify'
  },
  actions: {
    onModify: ({ commit }, info) => commit('modify', { info })
  },
  mutations: {
    modify: (state, { info }) => state.info = info
  }
};
const vuexStore = new Vuex.Store(store);

The store has a single state property, which is the same what we have seen on the component. We can modify the state with the onModify action that passes the input parameter to the modify mutation and mutates the state.

We can start by writing unit tests separately for each function in the store.

it('should modify state', () => {
  const state = {};

  store.mutations.modify(state, { info: 'Modified by click' });

  expect(state.info).to.eql('Modified by click');
});

Or we can construct the store and write an integration test. This way, we can check if the methods play together instead of throwing errors.

import Vuex from 'vuex';
import { createLocalVue } from '@vue/test-utils';

it('should modify state', () => {
  const localVue = createLocalVue();
  localVue.use(Vuex);
  const vuexStore = new Vuex.Store(store);

  vuexStore.dispatch('onModify', 'Modified by click');

  expect(vuexStore.state.info).to.eql('Modified by click');
});

First, we have to create a local instance of Vue. Why is it needed? The use statement is necessary on the Vue instance for the store. If we don't call the use method, it will throw an error. By creating a local copy of Vue, we also avoid polluting the global object.

We can alter the store through the dispatch method. The first parameter tells which action to call; the second parameter is passed to the action as a parameter. We can always check the current state through the state property.

When using the store with a component, we have to pass the local Vue instance and the store instance to the mount function.

const wrapper = shallowMount(Footer, { localVue, store: vuexStore });

8. Routing

The setup for testing routing is a bit similar to testing the store. You have to create a local copy of the Vue instance, an instance of the router, use the router as a plugin and then create the component.

<div class="route">{{ $router.path }}</div>

The above line in the component's template will display the current route. In the test, we can assert the content of this element.

import VueRouter from 'vue-router';
import { createLocalVue } from '@vue/test-utils';

it('should display route', () => {
  const localVue = createLocalVue();
  localVue.use(VueRouter);
  const router = new VueRouter({
    routes: [
      { path: '*', component: Footer }
    ]
  });

  const wrapper = shallowMount(Footer, { localVue, router });
  router.push('/modify');
  const text = wrapper.find('.route').text();

  expect(text).to.eql('/modify');
});

We have added our component as a catch-them-all route with the * path. When we have the router instance, we have to programmatically navigate the application with the router's push method.

Creating all the routes can be a time-consuming task. We can speed up the orchestration with a fake router implementation and pass it as a mock.

it('should display route', () => {
  const wrapper = shallowMount(Footer, {
    mocks: {
      $router: {
        path: '/modify'
      }
    }
  });
  const text = wrapper.find('.route').text();

  expect(text).to.eql('/modify');
});

We can use this mocking technique also for the store by declaring the $store property on mocks.

it('should display route', () => {
  const wrapper = shallowMount(Footer, {
    mocks: {
      $router: {
        path: '/modify'
      },
      $store: {
        dispatch: sinon.stub(),
        commit: sinon.stub(),
        state: {}
      }
    }
  });
  const text = wrapper.find('.route').text();
  expect(text).to.eql('/modify');
});

9. HTTP requests

const store = {
  actions: {
    async onModify({ commit }, info) {
      const response = await axios.post('https://example.com/api', { info });
      commit('modify', { info: response.body });
    }
  }
};

We have modified the store implementation: the input parameter is first sent through a POST request, and then the result is passed to the mutation. The code becomes asynchronous and gets an external dependency. The external dependency will be the one we have to change (mock) before running the test.

import chai from 'chai';
import sinon from 'sinon';
import sinonChai from 'sinon-chai';
chai.use(sinonChai);

it('should set info coming from endpoint', async () => {
  const commit = sinon.stub();
  sinon.stub(axios, 'post').resolves({
    body: 'Modified by post'
  });

  await store.actions.onModify({ commit }, 'Modified by click');

  expect(commit).to.have.been.calledWith('modify', { info: 'Modified by post' });
});

We are creating a fake implementation for the commit method and change the original implementation of axios.post. These fake implementations capture the arguments passed to them and can respond with whatever we tell them to return. The commit method returns with an empty value because we haven't specified one. axios.post will return with a Promise that resolves to an object with the body property.

We have to add Sinon as a plugin to Chai to be able to make assertions for the call signatures. The plugin extends Chai with the to.have.been.called property and to.have.been.calledWith method.

The test function becomes asynchronous: Mocha can detect and wait for the asynchronous function to complete if we return a Promise. Inside the function, we wait for the onModify method to complete and then make an assertion wether the fake commit method was called with the parameter returned from the post call.

10. The browser

The Vue CLI takes care of the orchestration: starts the application and runs the Cypress tests in the browser, and then shuts down the application. If you want to run the Cypress tests in headless mode, you have to add the --headless flag to the command.

describe('New todo', () => {
  it('it should change info', () => {
    cy.visit('/');

    cy.contains('.info', 'Click to modify');

    cy.get('button').click();

    cy.contains('.info', 'Modified by click');
  });
});

After visiting the main page (visit), we can access the displayed HTML through CSS selectors. We can assert the contents of an element with contains. Interactions work the same way: first, select the element (get) and then make the interaction (click). At the end of the test, we check if the content has changed or not.

Summary

We have reached the end of testing use-cases. I hope you enjoyed the examples and they clarified many things around testing. I wanted to lower the barrier of starting to write tests for a Vue application. We have gone from a basic unit test for a function to an end-to-end test running in a real browser.

Through our journey, we have created integration tests for the building blocks of a Vue application (components, store, router) and scratched the surface of implementation mocking. With these techniques, your existing and future projects can stay bug-free.

Header image by Louis Reed on Unsplash