DEV Community: Gábor Soós

Add testing to Vite

Gábor Soós — Tue, 23 Feb 2021 17:28:05 +0000

Vite is the brand new development server created by Evan You. It's framework agnostic and incredibly fast thanks to native ES Modules instead of bundling. Vite has a starter template for Vue applications. The template has the tooling for development and production deployment; only one is missing: testing. This tutorial shows you how to add unit and end-to-end testing to a newly generated Vue 3 Vite project.

Project setup

Let's start by creating a Vite project from scratch.



npm init @vitejs/app my-vite-app --template vue-ts

The above command creates a Vue 3 Typescript application into the my-vite-app folder. The folder structure will look like this.

We have a HelloWorld component in the src/components/HelloWorld.vue file that displays the header on the page "Hello Vue 3 + TypeScript + Vite". This component receives the header text a prop input named msg. We'll write a test against this component whether it displays the same message as what we give as input.

Unit test

As mentioned in the headline, the Vite template doesn't include any test runner; we have to choose one. The Jest test runner is a good choice if we want a simple and fast setup as it gives us everything that we need: a test runner that executes the tests, an assertion library with which we can assert for the outcome and a DOM implementation where Vue components can be mounted.

Here is our first unit test placed next to the HelloWorld.vue component file.



// src/components/HelloWorld.spec.ts
import { mount } from '@vue/test-utils'
import HelloWorld from './HelloWorld.vue'

describe('HelloWorld', () => {
  it('should display header text', () => {
    const msg = 'Hello Vue 3'
    const wrapper = mount(HelloWorld, { props: { msg } })

    expect(wrapper.find('h1').text()).toEqual(msg)
  })
})

The test uses the Vue Test Utils library, the official unit test helper library. With its help, we can mount a single component to the DOM and fill the input parameters, like its props.

We feed the "Hello Vue 3" text to the component and check the outcome through the components wrapper object. If the header element has the same text as the input, the test passes. But how do we run this test?

I've mentioned Jest and Vue Test Utils, but we haven't installed any packages.



npm install jest @types/jest ts-jest vue-jest@next @vue/test-utils@next --save-dev

By default, Jest doesn't understand Vue and Typescript files, so we need to transpile them before and pass the transpilation step as configuration (jest.config.js). We need the next version for multiple packages because they are the only ones that support Vue 3.



// jest.config.js
module.exports = {
  moduleFileExtensions: [
    'js',
    'ts',
    'json',
    'vue'
  ],
  transform: {
    '^.+\\.ts$': 'ts-jest',
    '^.+\\.vue$': 'vue-jest'
  }
}

We are two little steps away from running and seeing passing tests. First, we have to add the type definition of Jest to the config.



// tsconfig.json
{
  "compilerOptions": {
    ...
    "types": ["vite/client", "@types/jest"],
    ...
  },
  ...
}

Finally, add the script to package.json, and after that, we can run the tests with npm test.



// package.json
{
  ...
  "scripts": {
    ...
    "test": "jest src"
  },
  ...
}

And here it is the result of our first unit test, beautiful green, and passing.

E2E test

While unit tests are good for checking smaller bits of code, end-to-end tests are really good at checking the application as a whole in the browser. Vue CLI comes with built-in support for Cypress, an end-to-end test runner. We'll also use Cypress for this purpose.



// e2e/main.spec.ts
describe('Main', () => {
  it('should display header text', () => {
    cy.visit('/')
    cy.contains('h1', 'Hello Vue 3 + TypeScript + Vite')
  })
})

Cypress provides a global object cy that can interact with the browser. It can visit certain pages (visit) and check the content of elements defined by a selector (contains). In the above test, we navigate to the main page and check for the correct header text.

It's time to install the necessary packages to run the test.



npm install cypress start-server-and-test --save-dev

Next to Cypress, we've installed a utility library called start-server-and-test. This utility library can start the development server, wait until it responds to the given URL, and then runs the Cypress tests. In the end, it stops all running processes during the cleanup phase.

Cypress doesn't know where the test files are located and the base URL of the application, we have to tell it with a configuration file.



// cypress.json
{
  "baseUrl": "http://localhost:3000",
  "integrationFolder": "e2e",
  "pluginsFile": false,
  "supportFile": false,
  "video": false
}

Manually declared types within our Typescript configuration needs manual work again: add Cypress types to the list.



// tsconfig.json
{
  "compilerOptions": {
    ...
    "types": ["vite/client", "@types/jest", "cypress"],
    ...
  },
  ...
}

One piece is left to create the script command in package.json to run the tests. We use the start-server-and-test package with three command-line arguments:

dev: the npm script name which runs the development server
http-get://localhost:3000: the URL where the development server is available
cypress: the npm script name which runs the end-to-end tests



// package.json
{
  ...
  "scripts": {
    ...
    "test:e2e": "start-server-and-test dev http-get://localhost:3000 cypress",
    "cypress": "cypress run"
  },
  ...
}

If we run the above script, we get passing shiny green end-to-end test results.

Summary

Vite is a great development server, but its templates lack testing solutions. We have to add them manually. Jest and Cypress offer straightforward scenarios to fill in this gap. We can also swap them to similar libraries like Mocha, Jasmine, and Puppeteer. After this article, I hope the lack of out-of-the-box testing with Vite doesn't hold back anyone from using it.

If you don't want to set up everything manually, you can use my Vue 3 Playground as a starter.

Cover photo by Liam Shaw

Write Vue like you write React

Gábor Soós — Mon, 01 Feb 2021 16:50:46 +0000

With the Vue 3 Composition API, you can write functional components. It's possible also with React, but React has different templating: JSX. What happens if we write Vue functional components with JSX templates? Are they similar to React functional components?

Let's look at how both frameworks functional components work and how similar/different they're through. The component we'll use for this purpose is a counter, which counts clicks on a button. Additionally it receives a limit parameter: when this limit is reached the component notifies its parent.

We'll create the React component first and then look at the Vue equivalent.

React

import { useState, useEffect } from 'react';

export const Counter = ({ limit, onLimit }) => {
  const [count, setCount] = useState(0);
  const handler = () => setCount(count + 1);

  useEffect(
    () => (count >= limit) ? onLimit() : null,
    [count]
  );

  return <button type="button" onClick={handler}>
    Count: {count}
  </button>;
};

React requires a plain Javascript function that returns a JSX template to create a component. This function reruns whenever the component's state changes. You can create such state with the useState method. State variables are plain Javascript constructs that persist value between reruns. Every other variable is lost between state changes. You can test it with a console.log statement at the top of the function.

The component has a limit and a method which can be used to notify the parent component. We want to check the current value whenever it is incremented. The useEffect function serves as a checker and runs the callback whenever the dependencies in the second argument change.

In a nutshell: React component is a plain function with plain Javascript state values that reruns on every state change and returns JSX.

Vue

import { defineComponent, ref, watchEffect } from 'vue';

export const Counter = defineComponent({
  props: ['limit', 'onLimit'],
  setup(props) {
    const count = ref(0);
    const handler = () => count.value++;

    watchEffect(
      () => (count.value >= props.limit) ? props.onLimit() : null
    );

    return () => <button type="button" onClick={handler}>
      Count: {count.value}
    </button>;
  }
});

The plain function equivalent in Vue is the setup method within the component object. The setup method also receives props as an input parameter, but instead of JSX, it returns a function that returns JSX. You may wonder why.

The reason is because the setup function only runs once and only the returned function runs on state change. If the setup function only runs once, how can Vue detect changes? The trick lies in Vue's reactivity system. The ref function wraps the original value inside a Javascript Proxy object. Every modification runs through this proxy which notifies Vue to rerender that component. If we modify the original value directly that change will be ignored by the framework.

The limit and notifier function come as a function parameter, but in Vue we haven't used destructuring. The reason is that props is also a Proxy object and if we destructure it, we lose its reactivity (if it changes, nothing would happen). To check value changes, we have to use the useEffect function. In contrary to React, we don't have to define the watched dependencies, Vue does it automatically as it knows about which state variables (Proxies) we use inside the callback.

For Vue developers using a function instead of an event to notify the parent might be unusual. Some say it's an anti-pattern in Vue, but to make it as close to React as possible I've chosen this way.

Summary

Both framework can create a component with a single function. The Vue functional component is a function with state values wrapped inside Proxies that only runs once and only the returned function reruns and returns JSX. The React functional component is a function with state values as plain Javascript constructs that reruns on every state change and returns JSX directly.

The difference lies in the way how each framework solves the problem of reactivity: React is the stateless reference comparing solution, Vue is the stateful Proxy based solution.

It was an interesting and fun experiment to try to write the same component in different frameworks with similar approach as identically as possible. I hope you find it also interesting. You can also give it a try in my Vue 3 Vite playground.

Svelte Testing Crash Course

Gábor Soós — Wed, 23 Sep 2020 17:14:38 +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 Svelte applications.

For more test examples, you can take a look at my Svelte 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, if you create it from the Svelte starter repository you have to manually add testing to the project. For a test-runner, I would choose Jest because Jest isn’t just a test runner, but contrary to Mocha, it also includes an assertion library.

After installing the necessary packages for testing (npm install jest babel-jest svelte-jester) you have to configure Jest to be able to process Svelte components.

// jest.config.js
module.exports = {
  transform: {
    '^.+\\.js$': 'babel-jest',
    '^.+\\.svelte$': 'svelte-jester'
  }
};

From now on unit/integration tests can be written in the src directory with *.spec.js or *.test.js suffix.

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.

<script>
  let info = 'Click to modify';
  const modify = () => info = 'Modified by click';
</script>

<div>
  <p class="info" data-testid="info">{info}</p>
  <button on:click={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 { render } from '@testing-library/svelte';
import Footer from './Footer.svelte';

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 Svelte Testing Library’s render method. The render function needs a Svelte component 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/svelte';

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

  const button = getByTestId('button');
  await 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 events.

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

<script>
  import { createEventDispatcher } from 'svelte';

  export let info;
  const dispatch = createEventDispatcher();
  const modify = () => dispatch('modify', 'Modified by click');
</script>

<div>
  <p class="info" data-testid="info">{info}</p>
  <button on:click={modify} data-testid="button">Modify</button>
</div>

In the test, we have to provide the props as input and check if the component emits the modify event.

it('should handle interactions', async () => {
  let info = 'Click to modify';
  const { getByTestId, component } = render(Footer, { info });

  component.$on('modify', event => info = event.detail);

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

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

We pass down the info prop and listen to the modify event with the $on method on the component. When we trigger the click event on the button, the callback on the $on method is called and updates the info variable. The assertion at the end checks the info variable whether it was modified by the component's event.

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. Svelte has a built-in store implementation that can help you organize state management in one place and ensure it mutates predictably.

import { writable } from 'svelte/store';

export const createStore = () => {
  const state = writable('Click to modify');

  return {
    state,
    onModify(value) {
      state.update(() => value);
    }
  };
};

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 method that passes the input parameter to the states update method.

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', () => {
  const { store, onModify } = createStore();
  let info;
  store.subscribe(value => info = value);

  onModify('Modified by click');

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

We can alter the store through the returned method or directly calling update on it. What we can't do is to directly access the state, instead, we have to subscribe to changes.

8. Routing

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

<script>
  import { Router, Route } from 'svelte-routing';
  import Footer from './component-display.svelte';
</script>

<Router>
  <Route path="/"><Footer /></Route>
</Router>

We are using the svelte-routing library. The routes are defined within the component's template with the Route component.

import { render } from '@testing-library/svelte';
import Routing from './routing.svelte';

describe('Routing', () => {
  it('should render routing', () => {
    const { getByTestId } = render(Routing);

    const element = getByTestId('info');

    expect(element).toHaveTextContent('Click to modify');
  });
});

Testing doesn't differ from testing a basic component. However, the test framework setup needs some adjustment because libraries in Svelte are often published to NPM without transpilation. It means that components are in svelte files and Jest doesn't transform files within node_modules by default.

module.exports = {
  transform: {
    '^.+\\.js$': 'babel-jest',
    '^.+\\.svelte$': 'svelte-jester'
  },
  transformIgnorePatterns: [
    "node_modules/(?!(svelte-routing|svelte-spa-router)/)"
  ]
};

The jest.config.js file needs the transformIgnorePatterns property. By default, the regular expression here tells Jest to ignore everything in node_modules for transpilation. With the modified pattern, we can make an exception with our routing library and the tests pass green.

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.

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

We have a function: the input parameter is first sent through a POST request, and then the result is passed to the update 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'
  }));

  const { store, onModify } = createStore();
  let info;
  store.subscribe(value => info = value);
  await onModify('Modified by click');

  expect(info).toEqual('Modified by post');
});

We are creating a fake implementation 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). 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 whether the store is updated 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.

The Svelte template repository 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 (cypress run --headless).

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 Svelte 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 Svelte application (components, store) and scratched the surface of implementation mocking. With these techniques, your existing and future projects can stay bug-free.

You Might Not Need Vuex with Vue 3

Gábor Soós — Mon, 13 Jul 2020 14:59:05 +0000

Vuex is an awesome state management library. It's simple and integrates well with Vue. Why would anyone leave Vuex? The reason can be that the upcoming Vue 3 release exposes the underlying reactivity system and introduces new ways of how you can structure your application. The new reactivity system is so powerful that it can be used for centralized state management.

Do You need a shared state?

There are circumstances when data flow between multiple components becomes so hard that you need centralized state management. These circumstances include:

Multiple components that use the same data
Multiple roots with data access
Deep nesting of components

If none of the above cases are true, the answer is easy, whether you need it or not. You don't need it.

But what about if you have one of these cases? The straightforward answer would be to use Vuex. It's a battle-tested solution and does a decent job.

But what if you don't want to add another dependency or find the setup overly complicated? The new Vue 3 version, together with the Composition API can solve these problems with its built-in methods.

The new solution

A shared state must fit two criteria:

reactivity: when the state changes, the components using them should update also
availability: the state can be accessed in any of the components

Reactivity

Vue 3 exposes its reactivity system through numerous functions. You can create a reactive variable with the reactive function (an alternative would be the ref function).



import { reactive } from 'vue';

export const state = reactive({ counter: 0 });

The object returned from the reactive function is a Proxy object that can track changes on its properties. When used in a component's template, the component re-renders itself whenever the reactive value changes.



<template>
  <div>{{ state.counter }}</div>
  <button type="button" @click="state.counter++">Increment</button>
</template>

<script>
  import { reactive } from 'vue';

  export default {
    setup() {
      const state = reactive({ counter: 0 });
      return { state };
    }
  };
</script>

Availability

The above example is excellent for a single component, but other components can't access the state. To overcome this, you can make any value available inside a Vue 3 application with the provide and inject methods.



import { reactive, provide, inject } from 'vue';

export const stateSymbol = Symbol('state');
export const createState = () => reactive({ counter: 0 });

export const useState = () => inject(stateSymbol);
export const provideState = () => provide(
  stateSymbol, 
  createState()
);

When you pass a Symbol as key and a value to the provide method, that value will be available for any child component through the inject method. The key is using the same Symbol name when providing and retrieving the value.

This way, if you provide the value on the uppermost component, it'll be available in all the components. Alternatively, you can also call provide on the main application instance.



import { createApp, reactive } from 'vue';
import App from './App.vue';
import { stateSymbol, createState } from './store';

const app = createApp(App);
app.provide(stateSymbol, createState());
app.mount('#app');



<script>
  import { useState } from './state';

  export default {
    setup() {
      return { state: useState() };
    }
  };
</script>

Making it robust

The above solution works but has a drawback: you don't know who modifies what. The state can be changed directly, and there is no restriction.

You can make your state protected by wrapping it with the readonly function. It covers the passed variable in a Proxy object that prevents any modification (emits a warning when you try it). The mutations can be handled by separate functions that have access to the writable store.



import { reactive, readonly } from 'vue';

export const createStore = () => {
  const state = reactive({ counter: 0 });
  const increment = () => state.counter++;

  return { increment, state: readonly(state) };
}

The outside world will have access only to a readonly state, and only the exported functions can modify the writable state.

By protecting the state from unwanted modifications, the new solution is relatively close to Vuex.

Summary

By using the reactivity system and the dependency injection mechanism of Vue 3, we've gone from a local state to centralized state management that can replace Vuex in smaller applications.

We have a state object that is readonly and is reactive to changes in templates. The state can only be modified through specific methods like actions/mutations in Vuex. You can define additional getters with the computed function.

Vuex has more features like module handling, but sometimes we don't need that.

If You want to have a look at Vue 3 and try out this state management approach, take a look at my Vue 3 playground.

sonicoder86 / vue-3-playground

Vue 3 Playground packed with all the new features

The Vue 3 upgrade guide

Gábor Soós — Mon, 18 May 2020 15:40:19 +0000

The release of Vue 3 is just around the corner. We can expect a faster, smaller, more maintainable version with a lot of new exciting features. Mostly these are additions and improvements over the existing API.

Nothing is stopping you from starting your new applications with Vue 3. In this article, I'll show you how to get ahead of the curve and start experimenting with the new API by upgrading your application. If you are interested in an upgraded application, take a look at my TodoMVC application written with the Composition API or the playground that includes every new feature.

sonicoder86 / todomvc-vue-composition-api

TodoMVC built with Vue 3 Composition Api and Vuex

sonicoder86 / vue-3-playground

Vue 3 Playground packed with all the new features

Using the CLI

I highly recommend using the official CLI for Vue projects. Besides development and deployment tooling, it simplifies the upgrade to a one-line command:
vue add vue-next.

The Vue Next plugin not only upgrades and installs the new dependencies but modifies the code to be compatible with version three.

Dependencies

Installing the plugin upgrades the packages vue, vuex, vue-router, eslint-plugin-vue and @vue/test-utils to the next major version. Also, a new package named @vue/compiler-sfc appears among the development dependencies. What is it good for? It compiles the new Vue single file components into runnable Javascript code.

Code modifications

Let's look at what has changed in the code. The first thing you notice is that the main Vue package no longer has a default export.

The named export createApp creates a new Vue application as it did with the constructor in Vue 2. The plugin setup moves to the application instance with the use method instead of the constructor's parameter. The $mount method loses its dollar sign but behaves the same way.

As you have seen with the application, plugins adopt the factory pattern: no more constructor with the new keyword. Instead of calling new Vuex.Store, the createStore factory method is needed. Passing the store's default export as a plugin is no longer possible.

The router plugin follows the same pattern: new VueRouter becomes a call to createRouter, and the global plugin setup must be left. In the new version, you always have to define the type of history. You can choose from createWebHashHistory, createMemoryHistory and createWebHistory.

And basically, this is it, the application can be started and runs on the new Vue version. Everything with a single bash command. Anything else should work with the old syntax, as the old APIs are still intact.

Size matters

If you check the output size of the build command, you can notice a slight drop: 43.75 KiB -> 40.57 KiB. It's the result of leaving the default Vue instance in favor of named exports. Build tools like Webpack and Rollup can do tree-shaking (removing unused code) on named exports, but not on default exports.

Without the CLI

Without the CLI, you have to upgrade vue-loader or rollup-plugin-vue to the next major version and add the @vue/compiler-sfc package. No more magic here, you have to do everything manually. You have to do code modifications also manually, and there is no tool here that searches the codebase and updates the syntax.

Online playground

If you don't want to modify your project but interested in trying out the new version, just try this online playground.

Summary

We've reached the end of the modifications that you have to do during the upgrade process. These modifications are done automatically by the Vue CLI. All you have to do now is to start experimenting with all the new features that Vue 3 offers: the new reactivity system, Composition API, Fragments, Teleport and Suspense.

React Testing Crash Course

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

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.

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 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

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.

5. Component interactions

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');
});

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 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

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

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');
  });
});

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.

How to learn Svelte on a weekend

Gábor Soós — Mon, 04 May 2020 15:54:29 +0000

I've been working with Vue and Angular for years, and recently I've tried React. I was surprised how easy it was to learn React compared to the previous ones. The straightforward answer would be that React is easier to learn, but I didn't feel that I had to learn fewer things. I thought maybe the way I've learned it made such a big difference. I needed another framework to validate my assumptions. The chosen was Svelte, the newest and smallest of them. I've gathered my thoughts on how to go through the building blocks with the same application. To my greatest surprise, it took me only two days to finish learning Svelte and building the application.

Instead of reading the documentation from start to finish or taking a long video course, I've decided to learn Svelte by building a basic but quite powerful application if appropriately implemented, the well-known TodoMVC application. Some of you may say that the TodoMVC is too simple for learning a framework: it can be right if you use a minimal toolset, but not right if you break it down to multiple components with state management and testing.

Learning a framework can be a time-consuming task. What worked for me to speed it up enormously is to break down the process into consumable chapters. Starting with the basic building blocks to more complex ones and reading the necessary parts from the official documentation was the right path. This way, it didn't feel overwhelming, and I always had a little success.

I'll walk you through the building blocks in the same order I've learned them. You can extend this list with extra items, but I think the ones I mention are necessary to understand how the framework works. You can check the final application in my Github repository. If you want to speed it up with one of the other big frameworks check out my other repositories and follow along the building blocks mentioned below (Vue, Vue Composition API, Angular, React, React Hooks)

Component

Components are the building blocks of Svelte applications. We'll start with them and later add state management. If you use the official template it'll give you a simple component out of the box.

Creation

Let's create a static component from scratch. Docs

<script>console.log('runs once');</script>
<style>.main { display: inline; }</style>
<div class="main">Hello World</div>

Components reside in .svelte files, using a superset of HTML. The file contains three parts:

the script tag contains JavaScript that runs once when a component instance is created
the style tag contains CSS scoped to the component
all other regular HTML tags are considered to be part of the component's template

Display and bind

Now we have to make it dynamic by adding state and including it in the template. Docs

<script>
  let firstName = 'Chris';
  const countries = ['Canada'];
  let isVisible = true;
</script>
<style>.main { display: inline; }</style>
<div class:main={isVisible}>
  <h1>{firstName}</h1>
  <input name="first_name" value={firstName} />
  {#if isVisible}
    <ul>
      {#each countries as country }
        <li>{country.toUpperCase()}</li>
      {/each}
    </ul>
  {/if}
</div>

Every locally declared block-scoped variable is available inside the component's template and can be displayed or assigned to an attribute with curly braces. Conditional statements and loops have a special syntax starting with {#. Expressions inside curly braces are treated as Javascript expressions.

Modify with interactions

The previous component was dynamic but didn't receive any input from the user. Adding event handlers is a way to make the component interactive. Docs

<script>
  let firstName = 'Chris';
  const modifyName = event => (firstName = event.target.value);
</script>
<div>
  <h1>{firstName}</h1>
  <input name="first_name" value={firstName} on:input={modifyName} />
</div>

Locally declared variables become reactive by default. Reactivity means if we modify its value, it reacts to changes. Functions declared in the script tag can be used for event handling.

Parent-child interactions

If we don't intend to put everything into one big component, we'll have to break it down into multiple ones. The components will have a parent-child relationship and communicate through props and events. Docs

<script>
  import { createEventDispatcher } from 'svelte';
  const dispatch = createEventDispatcher();

  export let name;
  const modifyName = event => dispatch('modify', event.target.value);
</script>
<div>
  <h1>{name}</h1>
  <input name="first_name" value={name} on:input={modifyName} />
</div>

The child component notifies the parent component by triggering an event with the function returned from createEventDispatcher. Declaring and exporting a variable enables the parent component to pass down property with the same name. This variable is reactive also: if the parent modifies the value of the property, it makes the variable change its value in the child component.

<script>
  import NameInput from './name-input.svelte';

  let firstName = 'Chris';
  const modifyFirstName = event => firstName = event.detail;
</script>
<div>
  <NameInput name={firstName} on:modify={modifyFirstName} />
</div>

The parent component first has to import the child component and reference it with a camel-cased name inside its template. Props are passed down as attributes, and custom events are bound as native event listeners.

Lifecycle

Sometimes actions are needed at certain points of the lifecycle of the component like at mounting, updating, etc.

<script>
  import { onMount } from 'svelte';

  let firstName = 'Chris';
  onMount(() => console.log('mounted'));
</script>
<h1>{firstName}</h1>

Callbacks passed as an argument to the methods starting with on are executed every time that lifecycle event happens.

State management

When multiple components use the same data and passing down props through multiple layers becomes tedious, a state management library can help solve the problem.

Store creation

Svelte has a built-in store implementation, no need to import an external library. Docs

import { writable, derived } from 'svelte/store';

export const name = writable('Chris');
export const upperCaseName = derived(name, current => current.toUpperCase());

We can create a store with the writable method. Modified values from the state can be created with the derived getter. Whenever the original value changes, it calls the callback inside the derived function.

<script>
  import { name, upperCaseName } from './store';

  const modifyName = event => name.set(event.target.value);
</script>
<div>
  <h1>{$upperCaseName}</h1>
  <input name="first_name" value={$name} on:input={modifyName} />
</div>

Store values display differ from locally declared variables in the $ prefix. Behind the scenes, Svelte calls the stores subscribe which runs on every value change.

Global access

It's important to access the store everywhere in the application. Directly referencing the store is a quick solution but introduces tight coupling between the store and the components. Let's look at how to access the store everywhere with loose coupling. Docs

<script>
  import { setContext } from 'svelte';
  import { name, upperCaseName } from './store';
  import NameInput from './name-input.svelte';

  setContext('name', name);
  setContext('upperCaseName', upperCaseName);
</script>
<div>
  <NameInput />
</div>

The setContext method creates a context variable that is only accessible inside the component and its children.

<script>
  import { getContext } from 'svelte';

  const name = getContext('name');
  const upperCaseName = getContext('upperCaseName');

  const modifyName = event => name.set(event.target.value);
</script>
<div>
  <h1>{$upperCaseName}</h1>
  <input name="first_name" value={$name} on:input={modifyName} />
</div>

The context variable (in our case the store) is accessible through the getContext method.

Testing

What else can guarantee the application is running as intended if not tests? Svelte has no recommended way of testing, we have to choose our own tools.

Unit

Unit tests are the ones we write for a unit in isolation (component, class, etc.). We can use the Jest testing framework for running the tests. Docs

<script>
  let firstName = 'Chris';
  const modifyName = event => (firstName = event.target.value);
</script>
<div>
  <h1 data-testid="display">{firstName}</h1>
  <input data-testid="input" value={firstName} on:input={modifyName} />
</div>

We're reusing the component introduced earlier.

import { render } from '@testing-library/svelte';
import NameInput from './name-input.svelte';

describe('CopyRight', () => {
  it('should render component', () => {
    const { getByTestId } = render(NameInput);

    const inputElement = getByTestId('input');
    inputElement.value = 'Alexa';
    fireEvent.input(inputElement);

    expect(getByTestId('display')).toHaveTextContent('Alexa');
  });
});

Test-cases are organized with the describe block and run by the it block. The Svelte Testing library aims to simplify everyday tasks connected to component testing.

End-to-End

End-to-end tests observe the application as a black-box, typically they are run in the browser. We can use the Cypress testing framework for this task. Docs

describe('Display Name', () => {
  it('it should change name', () => {
    cy.visit('/');

    cy.contains('h1', 'Chris');

    cy.get('input').type('Alexa');

    cy.contains('h1', 'Alexa');
  });
});

The organization of the test-cases is the same with describe and it blocks. The difference is that we give commands with the global cy object.

Additional areas

The topics we've touched are enough for an entry-level application, but more complex ones need other areas like routing (docs), request handling (docs), and animations. My goal was to get an overall understanding of the framework, and I knowingly excluded them as they weren't necessary for it.

Summary

Learning frameworks can be challenging, but if we identify what is necessary to understand it, we can dramatically reduce the learning time. Creating a list out of what we have to learn makes it consumable and measurable. Not to mention, we always have a little success on the road. I hope it makes you try out a new framework that you have been thinking of.

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

Autocomplete Dropdown using native HTML

Gábor Soós — Mon, 25 Nov 2019 19:22:32 +0000

You have probably seen dropdowns with autocomplete ability in jQuery, React, Vue, etc. Most of us would assume it is only possible with the help of Javascript. But is it possible without Javascript? Yes, it is! I came across an HTML element that is supported by browsers and does the same.

The secret element is the datalist element. If we attach a datalist to an already existing input element we get a native dropdown with autocomplete! Booom, and it just works 🚀

Plus it is supported by all modern browsers.

<input list="europe-countries" placeholder="Start typing...">
<datalist id="europe-countries">
  <option>Russia</option>
  <option>Germany</option>
  <option>United Kingdom</option>
  ...
</datalist>

The input starts behaving like a select and when we start typing it searches inside the options of the datalist.

Let's see it in action!

Incredible 🦄