Error handling is one of those parts of software development that don’t quite get the amount of attention it really deserves. However, building robust applications requires dealing with errors properly.

You can get by in NodeJS without properly handling errors but due to the asynchronous nature of NodeJS, improper handling or errors can cause you pain soon enough — especially when debugging applications.

Before we proceed, I would like to point out the type of errors we’ll be discussing how to utilize error classes.

Operational Errors

These are errors discovered during the run time of a program. Operational errors are not bugs and can occur from time to time mostly because of one or a combination of several external factors like a database server timing out or a user deciding to make an attempt on SQL injection by entering SQL queries in an input field.

Below are more examples of operational errors:

• Failed to connect to a database server;
• Invalid inputs by the user (server responds with a 400 response code);
• Request timeout;
• Resource not found (server responds with a 404 response code);
• Server returns with a 500 response.

It’s also worthy of note to briefly discuss the counterpart of Operational Errors.

Programmer Errors

These are bugs in the program which can be resolved by changing the code. These types of errors can not be handled because they occur as a result of the code being broken. Example of these errors are:

• Trying to read a property on an object that is not defined.

 const user = {
   firstName: 'Kelvin',
   lastName: 'Omereshone',
 }

 console.log(user.fullName) // throws 'undefined' because the property fullName is not defined

• Invoking or calling an asynchronous function without a callback.
• Passing a string where a number was expected.

This article is about Operational Error handling in NodeJS. Error handling in NodeJS is significantly different from error handling in other languages. This is due to the asynchronous nature of JavaScript and the openness of JavaScript with errors. Let me explain:

In JavaScript, instances of the error class is not the only thing you can throw. You can literally throw any data type this openness is not allowed by other languages.

For example, a JavaScript developer may decide to throw in a number instead of an error object instance, like so:

// bad
throw 'Whoops :)';

// good
throw new Error('Whoops :)')

You might not see the problem in throwing other data types, but doing so will result in a harder time debugging because you won’t get a stack trace and other properties that the Error object exposes which are needed for debugging.

Let’s look at some incorrect patterns in error handling, before taking a look at the Error class pattern and how it is a much better way for error handling in NodeJS.

Bad Error Handling Pattern #1: Wrong Use Of Callbacks

Real-world scenario: Your code depends on an external API requiring a callback to get the result you expect it to return.

Let’s take the below code snippet:

'use strict';

const fs = require('fs');

const write = function () {
    fs.mkdir('./writeFolder');
    fs.writeFile('./writeFolder/foobar.txt', 'Hello World');
}

write();

Until NodeJS 8 and above, the above code was legitimate, and developers would simply fire and forget commands. This means developers weren’t required to provide a callback to such function calls, and therefore could leave out error handling. What happens when the writeFolder hasn’t been created? The call to writeFile won’t be made and we wouldn’t know anything about it. This might also result in race condition because the first command might not have finished when the second command started again, you wouldn’t know.

Let’s start solving this problem by solving the race condition. We would do so by giving a callback to the first command mkdir to ensure the directory indeed exists before writing to it with the second command. So our code would look like the one below:

'use strict';

const fs = require('fs');

const write = function () {
    fs.mkdir('./writeFolder', () => {
        fs.writeFile('./writeFolder/foobar.txt', 'Hello World!');
    });
}

write();

Though we solved the race condition, we are not done quite yet. Our code is still problematic because even though we used a callback for the first command, we have no way of knowing if the folder writeFolder was created or not. If the folder wasn’t created, then the second call will fail again but still, we ignored the error yet again. We solve this by…

Error Handling With Callbacks

In order to handle error properly with callbacks, you must make sure you always use the error-first approach. What this means is that you should first check if there is an error returned from the function before going ahead to use whatever data(if any) was returned. Let’s see the wrong way of doing this:

'use strict';


// Wrong
const fs = require('fs');

const write = function (callback) {
    fs.mkdir('./writeFolder', (err, data) => {
        if (data) fs.writeFile('./writeFolder/foobar.txt', 'Hello World!');
        else callback(err)
    });
}

write(console.log);

The above pattern is wrong because sometimes the API you are calling might not return any value or might return a falsy value as a valid return value. This would make you end up in an error case even though you might apparently have a successful call of the function or API.

The above pattern is also bad because it’s usage would eat up your error(your errors won’t be called even though it might have happened). You will also have no idea of what is happening in your code as a result of this kind of error handling pattern. So the right way for the above code would be:

'use strict';

// Right
const fs = require('fs');

const write = function (callback) {
    fs.mkdir('./writeFolder', (err, data) => {
        if (err) return callback(err)
        fs.writeFile('./writeFolder/foobar.txt', 'Hello World!');
    });
}

write(console.log);

Wrong Error Handling Pattern #2: Wrong Use Of Promises

Real-world scenario: So you discovered Promises and you think they are way better than callbacks because of callback hell and you decided on promisifying some external API your code base depended upon. Or you are consuming a promise from an external API or a browser API like the fetch() function.

These days we don’t really use callbacks in our NodeJS codebases, we use promises. So let’s reimplement our example code with a promise:

'use strict';

const fs = require('fs').promises;

const write = function () {
    return fs.mkdir('./writeFolder').then(() => {
        fs.writeFile('./writeFolder/foobar.txt', 'Hello world!')
    }).catch((err) => {
        // catch all potential errors
        console.error(err)
    })
}

Let’s put the above code under a microscope — we can see that we are branching off the fs.mkdir promise into another promise chain(the call to fs.writeFile) without even handling that promise call. You might think a better way to do it would be:

'use strict';

const fs = require('fs').promises;

const write = function () {
    return fs.mkdir('./writeFolder').then(() => {
        fs.writeFile('./writeFolder/foobar.txt', 'Hello world!').then(() => {
            // do something
        }).catch((err) => {
            console.error(err);
        })
    }).catch((err) => {
        // catch all potential errors
        console.error(err)
    })
}

But the above would not scale. This is because if we have more promise chain to call, we would end up with something similar to the callback hell which promises were made to solve. This means our code will keep indenting to the right. We would have a promise hell on our hands.

Promisifying A Callback-Based API

Most times you would want to promisify a callback-based API on your own in order to better handle errors on that API. However, this is not really easy to do. Let’s take an example below to explain why.

function doesWillNotAlwaysSettle(arg) {
    return new Promise((resolve, reject) => {
       doATask(foo, (err) => {
           if (err) {
                return reject(err);
            }

            if (arg === true) {
                resolve('I am Done')
            }
        });
    });
}

From the above, if arg is not true and we don’t have an error from the call to the doATask function then this promise will just hang out which is a memory leak in your application.

Swallowed Sync Errors In Promises

Using the Promise constructor has several difficulties one of these difficulties is; as soon as it is either resolved or rejected it cannot get another state. This is because a promise can only get a single state — either it is pending or it is resolved/rejected. This means we can have dead zones in our promises. Let’s see this in code:

function deadZonePromise(arg) {
    return new Promise((resolve, reject) => {
        doATask(foo, (err) => {
            resolve('I’m all Done');
            throw new Error('I am never reached') // Dead Zone
        });
    });
}

From the above we see as soon as the promise is resolved, the next line is a dead zone and will never be reached. This means any following synchronous error handling perform in your promises will just be swallowed and will never be thrown.

Real-World Examples

The examples above help explain poor error handling patterns, let’s take a look at the sort of problems you might see in real-life.

Real World Example #1 — Transforming Error To String

Scenario: You decided the error returned from an API is not really good enough for you so you decided to add your own message to it.

'use strict';

function readTemplate() {
    return new Promise(() => {
      databaseGet('query', function(err, data) {
          if (err) {
           reject('Template not found. Error: ', + err);
          } else {
            resolve(data);
          }
        });
    });
}

readTemplate();

Let’s look at what is wrong with the above code. From the above we see the developer is trying to improve the error thrown by the databaseGet API by concatenating the returned error with the string “Template not found”. This approach has a lot of downsides because when the concatenation was done, the developer implicitly runs toString on the error object returned. This way he loses any extra information returned by the error(say goodbye to stack trace). So what the developer has right now is just a string that is not useful when debugging.

A better way is to keep the error as it is or wrap it in another error that you’ve created and attached the thrown error from the databaseGet call as a property to it.

Real-World Example #2: Completely Ignoring The Error

Scenario: Perhaps when a user is signing up in your application, if an error occur you want to just catch the error and show a custom message but you completely ignored the error that was caught without even logging it for debugging purposes.

router.get('/:id', function (req, res, next) {
    database.getData(req.params.userId)
    .then(function (data) {
        if (data.length) {
            res.status(200).json(data);
        } else {
            res.status(404).end();
        }
    })
    .catch(() => {
        log.error('db.rest/get: could not get data: ', req.params.userId);
        res.status(500).json({error: 'Internal server error'});
    })
});

From the above, we can see that the error is completely ignored and the code is sending 500 to the user if the call to the database failed. But in reality, the cause for the database failure might be malformed data sent by the user which is an error with the status code of 400.

In the above case, we would be ending up in a debugging horror because you as the developer wouldn’t know what went wrong. The user won’t be able to give a decent report because 500 internal server error is always thrown. You would end up wasting hours in finding the problem which will tantamount to wastage of your employer’s time and money.

Real-World Example #3: Not Accepting The Error Thrown From An API

Scenario: An error was thrown from an API you were using but you don’t accept that error instead you marshall and transform the error in ways that make it useless for debugging purposes.

Take the following code example below:

async function doThings(input) {
    try {
        validate(input);
        try {
            await db.create(input);
        } catch (error) {
            error.message = `Inner error: ${error.message}`

            if (error instanceof Klass) {
                error.isKlass = true;
            }

            throw error
        }
    } catch (error) {
        error.message = `Could not do things: ${error.message}`;
        await rollback(input);
        throw error;
    }
}

A lot is going on in the above code that would lead to debugging horror. Let’s take a look:

• Wrapping try/catch blocks: You can see from the above that we are wrapping try/catch block which is a very bad idea. We normally try to reduce the use of try/catch blocks to minify the surface where we would have to handle our error (think of it as DRY error handling);
• We are also manipulating the error message in the attempt to improve which is also not a good idea;
• We are checking if the error is an instance of type Klass and in this case, we are setting a boolean property of the error isKlass to truev(but if that check passes then the error is of the type Klass);
• We are also rolling back the database too early because, from the code structure, there is a high tendency that we might not have even hit the database when the error was thrown.

Below is a better way to write the above code:

async function doThings(input) {
    validate(input);

    try {
        await db.create(input);
    } catch (error) {
        try {
            await rollback();
        } catch (error) {
            logger.log('Rollback failed', error, 'input:', input);
        }
        throw error;
    }
}

Let’s analyze what we are doing right in the above snippet:

• We are using one try/catch block and only in the catch block are we using another try/catch block which is to serve as a guard in case something goes on with that rollback function and we are logging that;
• Finally, we are throwing our original received error meaning we don’t lose the message included in that error.

Testing

We mostly want to test our code(either manually or automatically). But most times we are only testing for the positive things. For a robust test, you must also test for errors and edge cases. This negligence is responsible for bugs finding their way into production which would cost more extra debugging time.

Tip: Always make sure to test not only the positive things(getting a status code of 200 from an endpoint) but also all the error cases and all the edge cases as well.

Real-World Example #4: Unhandled Rejections

If you’ve used promises before, you have probably run into unhandled rejections.

Here is a quick primer on unhandled rejections. Unhandled rejections are promise rejections that weren’t handled. This means that the promise was rejected but your code will continue running.

Let’s look at a common real-world example that leads to unhandled rejections..

'use strict';

async function foobar() {
    throw new Error('foobar');
}

async function baz() {
    throw new Error('baz')
}


(async function doThings() {
    const a = foobar();
    const b = baz();

    try {
        await a;
        await b;
    } catch (error) {
        // ignore all errors!
    }
})();

The above code at first look might seem not error-prone. But on a closer look, we begin to see a defect. Let me explain: What happens when a is rejected? That means await b is never reached and that means its an unhandled rejection. A possible solution is to use Promise.all on both promises. So the code would read like so:

'use strict';

async function foobar() {
    throw new Error('foobar');
}

async function baz() {
    throw new Error('baz')
}


(async function doThings() {
    const a = foobar();
    const b = baz();

    try {
        await Promise.all([a, b]);
    } catch (error) {
        // ignore all errors!
    }
})();

Here is another real-world scenario that would lead to an unhandled promise rejection error:

'use strict';

async function foobar() {
    throw new Error('foobar');
}

async function doThings() {
    try {
        return foobar()
    } catch {
        // ignoring errors again !
    }
}

doThings();

If you run the above code snippet, you will get an unhandled promise rejection, and here is why: Although it’s not obvious, we are returning a promise (foobar) before we are handling it with the try/catch. What we should do is await the promise we are handling with the try/catch so the code would read:

'use strict';

async function foobar() {
    throw new Error('foobar');
}

async function doThings() {
    try {
        return await foobar()
    } catch {
        // ignoring errors again !
    }
}

doThings();

Wrapping Up On The Negative Things

Now that you have seen wrong error handling patterns, and possible fixes, let’s now dive into Error class pattern and how it solves the problem of wrong error handling in NodeJS.

Error Classes

In this pattern, we would start our application with an ApplicationError class this way we know all errors in our applications that we explicitly throw are going to inherit from it. So we would start off with the following error classes:

• ApplicationError
  This is the ancestor of all other error classes i.e all other error classes inherits from it.
• DatabaseError
  Any error relating to Database operations will inherit from this class.
• UserFacingError
  Any error produced as a result of a user interacting with the application would be inherited from this class.

Here is how our error class file would look like:

'use strict';

// Here is the base error classes to extend from

class ApplicationError extends Error {
    get name() {
        return this.constructor.name;
    }
}

class DatabaseError extends ApplicationError { }

class UserFacingError extends ApplicationError { }

module.exports = {
    ApplicationError,
    DatabaseError,
    UserFacingError
}

This approach enables us to distinguish the errors thrown by our application. So now if we want to handle a bad request error (invalid user input) or a not found error (resource not found) we can inherit from the base class which is UserFacingError (as in the code below).

const { UserFacingError } = require('./baseErrors')

class BadRequestError extends UserFacingError {
    constructor(message, options = {}) {
        super(message);

        // You can attach relevant information to the error instance
        // (e.g.. the username)

        for (const [key, value] of Object.entries(options)) {
            this[key] = value;
        }
    }

    get statusCode() {
        return 400;
    }
}


class NotFoundError extends UserFacingError {
    constructor(message, options = {}) {
        super(message);

        // You can attach relevant information to the error instance
        // (e.g.. the username)

        for (const [key, value] of Object.entries(options)) {
            this[key] = value;
        }
    }
    get statusCode() {
        return 404
    }
}

module.exports = {
    BadRequestError,
    NotFoundError
}

One of the benefits of the error class approach is that if we throw one of these errors, for example, a NotFoundError, every developer reading this codebase would be able to understand what is going on at this point in time(if they read the code).

You would be able to pass in multiple properties specific to each error class as well during the instantiation of that error.

Another key benefit is that you can have properties that are always part of an error class, for example, if you receive a UserFacing error, you would know that a statusCode is always part of this error class now you can just directly use it in the code later on.

Tips On Utilizing Error Classes

• Make your own module(possibly a private one) for each error class that way you can simply import that in your application and use it everywhere.
• Throw only errors that you care about(errors that are instances of your error classes). This way you know your error classes are your only Source of Truth and it contains all information necessary to debug your application.
• Having an abstract error module is quite useful because now we know all necessary information concerning errors our applications can throw are in one place.
• Handle errors in layers. If you handle errors everywhere, you have an inconsistent approach to error handling which is hard to keep track of. By layers I mean like database, express/fastify/HTTP layers, and so on.

Let’s see how error classes looks in code. Here is an example in express:

const { DatabaseError } = require('./error')
const { NotFoundError } = require('./userFacingErrors')
const { UserFacingError } = require('./error')

// Express
app.get('/:id', async function (req, res, next) {
    let data

    try {
        data = await database.getData(req.params.userId)
    } catch (err) {
        return next(err);
    }

    if (!data.length) {
        return next(new NotFoundError('Dataset not found'));
    }

    res.status(200).json(data)
})

app.use(function (err, req, res, next) {
    if (err instanceof UserFacingError) {
        res.sendStatus(err.statusCode);

        // or

        res.status(err.statusCode).send(err.errorCode)
    } else {
        res.sendStatus(500)
    }

    // do your logic
    logger.error(err, 'Parameters: ', req.params, 'User data: ', req.user)
});

From the above, we are leveraging that Express exposes a global error handler which allows you handle all your errors in one place. You can see the call to next() in the places we are handling errors. This call would pass the errors to the handler which is defined in the app.use section. Because express does not support async/await we are using try/catch blocks.

So from the above code, to handle our errors we just need to check if the error that was thrown is a UserFacingError instance and automatically we know that there would be a statusCode in the error object and we send that to the user (you might want to have a specific error code as well which you can pass to the client) and that is pretty much it.

You would also notice that in this pattern (error class pattern) every other error that you did not explicitly throw is a 500 error because it is something unexpected that means you did not explicitly throw that error in your application. This way, we are able to distinguish the types of error going on in our applications.

Conclusion

Proper error handling in your application can make you sleep better at night and save debug time. Here are some takeaway key points to take from this article:

• Use error classes specifically set up for your application;
• Implement abstract error handlers;
• Always use async/await;
• Make errors expressive;
• User promisify if necessary;
• Return proper error statuses and codes;
• Make use of promise hooks.

Smashing Newsletter

Every week, we send out useful front-end & UX techniques. Subscribe and get the Smart Interface Design Checklists PDF delivered to your inbox.

Your (smashing) email Subscribe →

Front-end, design and UX. Sent 2× a month.
You can always unsubscribe with just one click.

(ra, yk, il)

For many people, the web is an essential part of their daily lives. They use it at work, home, and even on the road. Web accessibility means people with disabilities can use the web equally. So it’s crucial for developers and organizations building on the web to build inclusivity and accessibility into their applications.

In order to make the web more accessible, there are a couple of best practices and standards that you will have to implement in your applications, such as adhering to the following:

• Section 508;
• Assistive Technology Act;
• Americans with Disabilities Act(ADA);
• WCAG 2.0 (A & AA Guidelines);
• BBC Mobile Accessibility Guidelines;
• WAI-ARIA (Web Accessibility Initiative–Accessible Rich Internet Applications) practices.

Learning to implement these standards can seem like a daunting task when you factor in project deadlines and other constraints that you have to work with as a developer. In that light, let me introduce you to a UI design system that was built to help you make your web applications accessible.

Chakra UI

Chakra UI is a design system and UI framework created by Segun Adebayo. It was created with simplicity, modularity, composability, and accessibility in mind. Chakra UI gives you all the building blocks needed to create accessible front-end applications.

Note: While Chakra UI depends on CSS-in-JS under the hood, you don’t need to know it in order to use the library.

Though the framework was originally created for React, Jonathan Bakebwa spear-headed the porting to Vue. So Vuejs/NuxtJS developers can now utilize Chakra UI to create accessible web applications.

Features Of Chakra UI

Chakra UI was created with the following principles in mind:

• Style props
  Chakra UI makes it possible to style components or override their styles by using props. This reduces the need for stylesheet or inline styles. Chakra UI achieves this level of flexibility by using Styled Systems under the hood.
• Composition
  Components in Chakra UI have been broken down into smaller parts with minimal props to keep complexity low, and compose them together. This will ensure that the styles and functionality are flexible and extensible. For example, you can use the CBox and CPseudoBox components to create new components.
• Accessible
  Chakra UI components follow the WAI-ARIA guidelines specifications and have the right aria-* attributes. You can also find the accessibility report of each authored component in a file called accessibility.md. See the accessibility report for the CAccordion component.
• Themeable
  Chakra UI affords you the ability to easily reference values from your theme throughout your entire application, on any component.
• Dark mode support
  Most components in Chakra UI are dark mode compatible right out of the box.

How Chakra UI Supports Accessibility

One of the core principles behind the creation of Chakra UI is accessibility. With that in mind, all components in Chakra UI comes out of the box with support for accessibility by providing:

• Keyboard Navigation — useful for users with motor skills disabilities,
• Focus Management,
• aria-* attributes which are needed by screen readers,
• Focus trapping and restoration for modal dialogs.

Getting Started With Chakra UI And Nuxt

Note: To use Chakra UI with Vue.js see the Getting Started guide.

For our demo project, we will be building Chakra-ui explorer — an accessible single-page web application to search Chakra UI components.

• See live project on Netlify →

Getting Started With Chakra-ui Explorer

Assuming you already have NPM installed, create a new Nuxt application by running:

$ npx create-nuxt-app chakra-ui-explorer

Or if you prefer in yarn, then run:

$ yarn create nuxt-app chakra-ui-explorer

Follow the installation prompt to finish creating your Nuxt application.

Setting Up Chakra UI

Chakra UI uses Emotion for handling component styles. So to get started with Chakra UI, you will need to install Chakra UI alongside Emotion as a peer dependency. For this project, we will be using the official Nuxt modules for both Chakra UI and Emotion which will reduce the friction in getting started with Chakra UI. Let’s add them to our project by running the following command:

npm i @chakra-ui/nuxt @nuxtjs/emotion

Note: @nuxtjs/emotion allows your component styles to be generated and injected in the server build.

After installing both modules, you will need to register them in the nuxt.config.js file under the modules array option:

// nuxt.config.js
modules: ['@chakra-ui/nuxt', '@nuxtjs/emotion'],

To complete our setup process of Chakra UI, we need to touch our default layout component in layouts/ and add CThemeProvider, CColorModeProvider, and CReset components from Chakra UI.

It is recommended thatyou use the CReset component to ensure all components provided by Chakra UI work correctly.

The CThemeProvider component will make your theme available to every part of your application, while the CColorModeProvider component is responsible for handling our application’s color mode which can be in one of two states: light or dark. Finally, the CReset component will remove all browser default styles.

Let’s add the aforementioned components in layouts/default.vue. In our template section, let’s add this:

<!-- layouts/default.vue -->
<template>
  <div class="container">
    <c-theme-provider>
      <c-color-mode-provider>
        <c-box as="section">
          <c-reset />
          <nuxt />
        </c-box>
      </c-color-mode-provider>
    </c-theme-provider>
  </div>
</template>

Then in our script section, we will import and register the components like so:

<script>
import { CThemeProvider, CColorModeProvider, CReset, CBox } from '@chakra-ui/vue'

export default {
  name: 'DefaultLayout',
  components: {
    CThemeProvider,
    CColorModeProvider,
    CReset,
    CBox
  }
}
</script>

Your default.vue layout component should look like this:

<template>
   <div class="container">
    <c-theme-provider>
      <c-color-mode-provider>
        <c-box as="section">
          <c-reset />
          <nuxt />
        </c-box>
      </c-color-mode-provider>
    </c-theme-provider>
  </div>
</template>

<script>
import { CThemeProvider, CColorModeProvider, CReset, CBox } from '@chakra-ui/vue'

export default {
  name: 'DefaultLayout',
  components: {
    CThemeProvider,
    CColorModeProvider,
    CReset,
    CBox
  }
}
</script>

Note: Notice I am wrapping both <c-reset /> and <nuxt /> components in a c-box component.

Setting Your Application Theme

Chakra UI allows you the ability to set a theme for your application. By ‘theme’, I mean the setting of your application’s color palette, type scale, font stacks, breakpoints, border-radius values, and so on. Since colors and contrast are vital components of accessibility, it’s important to use colors that are easily perceived.

Out of the box Chakra UI ships with a default theme object that affords for most of your application needs in terms of colors, fonts, and so on. The default theme is set up with contrast in mind which allows for the easily toggling of color modes (more on this later).

Chakra UI, however, allows you to extend or completely replaced the default theme. This is possible by accepting a theme object based on the Styled System Theme Specification.

The values in the theme object are automatically available for use in your application. For example, the colors specified in theme.colors can be referenced by the color, borderColor, backgroundColor, fill, stroke, and style props in your components.

To personalize your application, you can override the default theme provided by Chakra UI or set new values in it. To do that, the Chakra UI Nuxt module exposes a chakra object which will take in an extendTheme property which takes an object. The object given to extendTheme will be recursively merged to the Chakra UI default theme object. Let’s add our brand color palette to Chakra so we can use it in our application.

Note: Chakra UI recommends adding color palette into the colors object of your theme using keys from 50 — 900. You can use web tools like coolors and palx to generate these palettes.

For our demo homepage, I will be using a brand color of lime. To make Chakra UI aware of this color, I’ll create a customeTheme object in a folder called chakra(you can call it whatever you want) in the root of my project’s directory. In this object, I will define our brand color palette.

Create a file called theme.js in the folder you created and then add the following snippet:

// ./chakra/theme.js

const customTheme = {
  colors: {
    brand: {
      50: '#f6fcee',
      100: '#e2f4c8',
      200: '#cbec9e',
      300: '#b2e26e',
      400: '#94d736',
      500: '#75c800',
      600: '#68b300',
      700: '#599900',
      800: '#477900',
      900: '#294700'
    }
  }
}

module.exports = customTheme

Now let’s merge our custom theme to Chakra UI. We do that in nuxt.config.js. First, we need our custom theme object:

import customTheme from './chakra/theme'

Next, we have to specify the chakra key provided by the Chakra UI Nuxt module and pass in customTheme to the extendTheme property:

chakra: {
  extendTheme: customTheme
},

Your nuxt.config.js file should look like this:

// nuxt.config.js
import customTheme from './chakra/theme'

export default {
  mode: 'spa',
  /*
   * Headers of the page
   */
  head: {
    title: process.env.npm_package_name || '',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      {
        hid: 'description',
        name: 'description',
        content: process.env.npm_package_description || ''
      }
    ],
    link: [{ rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }]
  },
  /*
   * Customize the progress-bar color
   */
  loading: { color: '#fff' },
  /*
   * Global CSS
   */
  css: [],
  /*
   * Plugins to load before mounting the App
   */
  plugins: [],
  /*
   * Nuxt.js dev-modules
   */
  buildModules: [
    // Doc: https://github.com/nuxt-community/eslint-module
    '@nuxtjs/eslint-module'
  ],
  /*
   * Nuxt.js modules
   */
  modules: [
    '@chakra-ui/nuxt',
    '@nuxtjs/emotion'
  ],

  chakra: {
    extendTheme: customTheme
  },
  /*
   * Build configuration
   */
  build: {
    /*
     * You can extend webpack config here
     */
    extend (config, ctx) {}
  }
}

When you run your application with npm run dev, your homepage should look like this:

Now that we have successfully installed Chakra UI and added our application’s custom theme, let’s begin building out Chakra-ui explorer.

Creating Our Main Navigation

We want our navigation to have our brand name, in this case, it will be Chakra-ui explorer, 2 navigation links: Documentation and Repo, and a button which is responsible for toggling our color mode. Let’s create a new component under the components directory called NavBar in which we’ll create our application’s main navigation using Chakra UI.

Let’s do this. Add the following snippet to NavBar.vue:

<template>
  <c-box
    as="nav"
    h="60px"
    px="4"
    d="flex"
    align-items="center"
    shadow="sm"
  >
    <c-link
      as="nuxt-link"
      to="/"
      color="brand.700"
      font-weight="bold"
      :_hover="{ color: 'brand.900' }"
    >
      Chakra-ui Explorer
    </c-link>

    <c-box
      as="ul"
      color="gray.500"
      d="flex"
      align-items="center"
      list-style-type="none"
      ml="auto"
    >
      <c-box as="li" mr="8">
        <c-link
          color="gray.500"
          :_hover="{ color: 'brand.400' }"
          is-external
          href="https://vue.chakra-ui.com"
        >
          Documentation
        </c-link>
      </c-box>
      <c-box as="li" mr="8">
        <c-link
          color="gray.500"
          :_hover="{ color: 'brand.400' }"
          is-external
          href="https://github.com/chakra-ui/chakra-ui-vue"
        >
          Repo
        </c-link>
      </c-box>
      <c-box as="li">
        <c-icon-button
          variant="ghost"
          variant-color="gray[900]"
          aria-label="Switch to dark mode"
          icon="moon"
        />
      </c-box>
    </c-box>
  </c-box>
</template>

<script>
import { CBox, CLink, CIconButton } from '@chakra-ui/vue'
export default {
  name: 'NavBar',
  components: {
    CBox,
    CLink,
    CIconButton
  }
}
</script>

Next, we need to import this component in our default layout component — default.vue and add it to our template so overall our default layout should look like this:

<template>
  <div class="container">
    <c-theme-provider>
      <c-color-mode-provider>
        <c-box as="section">
          <c-reset />
          <nav-bar />
          <nuxt />
        </c-box>
      </c-color-mode-provider>
    </c-theme-provider>
  </div>
</template>

<script>
import { CThemeProvider, CColorModeProvider, CReset, CBox } from '@chakra-ui/vue'
import NavBar from '@/components/NavBar'
export default {
  name: 'DefaultLayout',
  components: {
    CThemeProvider,
    CColorModeProvider,
    CReset,
    CBox,
    NavBar
  }
}
</script>

When you run your application now, you’ll get to see this:

You can see that the navigation is already accessible without even specifying it. This can only be seen when you hit the Tab key on your keyboard; Chakra UI handles focus management while you can focus on each link on the navigation menu.

The as Prop

From our NavBar.vue’s snippet above, you will notice the as prop. This is a feature available to Chakra UI components that allows you to pass an HTML tag or another component to be rendered as the base tag of the component along with all its styles and props. So when we did:

<c-box as="li">
      <c-icon-button
        variant="ghost"
        variant-color="gray[900]"
        aria-label="Switch to dark mode"
        icon="moon"
      />
</c-box>

we are asking Chakra UI to render an <li> element and place a button component inside it. You can also see us use that pattern here:

 <c-link 
     as="nuxt-link"
     to="/" 
     color="brand.700" 
     font-weight="bold" 
     :_hover="{ color : 'brand.900' }">
      ChakraMart
 </c-link>

In the above case, we are asking Chakra UI to render the Nuxt’s <nuxt-link /> component.

The as prop gives you the power to use the right(or wrong) element for the context of your markup. What this means, is you can leverage it to build your application template using semantic markups which will make your application more meaningful to screen readers. So instead of using a generic div element for the main content of your application, with the as prop you can render a main element telling screen readers that this is the main content of your application.

Note: Check out the documentation for all props exposed by Chakra UI components. Also, take a closer look at how the brand color in chakra/theme.js was specified. You can see from the snippet above that we’re using it as any of the colors that Chakra UI provides. Another thing to be aware of is the moon icon that we used for the CIconButton on our NavBar. The moon icon is one of the default icons that Chakra UI provides out of the box.

Color Mode

One of the features of Chakra UI is color mode support. And you can tell from the use of the moon icon in Chakra-ui explorer’s navigation, we plan on integrating dark mode. So instead of leaving it for last, let’s get it over with and wire it up right now. To do this, CColorModeProvider using Vue’s provide/inject, provides, $chakraColorMode and $toggleColorMode functions. $chakraColorMode returns the current color mode of your application while $toggleColorMode toggles the color mode from light to dark and vice versa. To use these two functions, we’ll need to inject them into the NavBar.vue component. Let’s do this below in the <script /> section:

<script>
<script>
import { CBox, CLink, CIconButton } from '@chakra-ui/vue'
export default {
  name: 'NavBar',
  inject: ['$chakraColorMode', '$toggleColorMode'],
  components: {
    CBox,
    CLink,
    CIconButton
  },
}
</script>

Let’s create a computed property to return the color mode:

...
 computed: {
    colorMode () {
      return this.$chakraColorMode()
    }
  }

Now that we have injected both functions in NavBar.vue let’s modify the toggle color mode button. We’ll start with the icon so that it shows a different icon depending on the color mode. Our CIconButton component now looks like this at this state:

<c-icon-button
  variant="ghost"
  variant-color="gray[900]"
  aria-label="Switch to dark mode"
  :icon="colorMode == 'light' ? 'moon' : 'sun'"
/>

Currently, we are using an aria-label attribute to tell screen-readers to Switch to dark mode. Let’s modify this to support both light and dark mode:

<c-icon-button
  variant="ghost"
  variant-color="gray[900]"
  :aria-label="`Switch to ${colorMode == 'light' ? 'dark : 'light'} mode`"
   :icon="colorMode == 'light' ? 'moon' : 'sun'"
/>

Lastly, we will add a click event handler on the button to toggle the color mode of our application using the $toggleColorMode function. Like so:

<c-icon-button
   variant="ghost"
   variant-color="gray[900]"
   :aria-label="`Switch to ${colorMode == 'light' ? 'dark' : 'light'} mode`"
   :icon="colorMode == 'light' ? 'moon' : 'sun'"
   @click="$toggleColorMode"
/>

To test if our color mode set up is working, I’ll add an interpolation of the color mode and a text next to the CIconButton toggling our color mode. Like so:

<c-box as="li">
  <c-icon-button
    variant="ghost"
    variant-color="gray[900]"
    :aria-label="`Switch to ${colorMode == 'light' ? 'dark' : 'light'} mode`"
    :icon="colorMode == 'light' ? 'moon' : 'sun'"
    @click="$toggleColorMode"
  />
  Current mode: {{ colorMode }}
</c-box>

Here is what our app currently looks like:

So we have done the heavy lifting in setting up color mode in Chakra UI. So now we can style our application based on the color mode. Let’s go to default.vue and use the color mode slot prop provided by CColorModeProvider to style our application. Let’s modify our template first in default.vue.

<template>
  <div class="container">
    <c-theme-provider>
      <c-color-mode-provider #default="{ colorMode }">
        <c-box
          v-bind="mainStyles[colorMode]"
          w="100vw"
          h="100vh"
          as="section"
        >
          <c-reset />
          <nav-bar />
          <nuxt />
        </c-box>
      </c-color-mode-provider>
    </c-theme-provider>
  </div>
</template>

We are destructuring colorMode from the slot props property provided by CColorModeProvider and then passing it as a dynamic key to a mainStyle object which we will create in a bit. The idea is to use a different set of styles based on the colorMode value. I am also using the width and height with the shorthand props — w and h respectively to set the width and height of our CBox component. Let’s define this mainStyles object in our script section:

<script>
import { CThemeProvider, CColorModeProvider, CReset, CBox } from '@chakra-ui/vue'
import NavBar from '@/components/NavBar'
export default {
  name: 'DefaultLayout',
  components: {
    CThemeProvider,
    CColorModeProvider,
    CReset,
    CBox,
    NavBar
  },
  data () {
    return {
      mainStyles: {
        dark: {
          bg: 'gray.900',
          color: 'whiteAlpha.900'
        },
        light: {
          bg: 'whiteAlpha.900',
          color: 'gray.900'
        }
      }
    }
  }
}
</script>

Chakra-ui explorer now has dark mode support!

Now we have our navigation bar and have successfully set up dark mode support for our application, let’s focus on index.vue in our pages/ directory where the meat of our application can be found. We’ll start off with adding a CBox component like so:

<c-box
  as="main"
  d="flex"
  direction="column"
  align-items="center"
  p="10" 
>
</c-box>

Then we’ll add the CInput component inside it. Our index.vue page component will then look like this:

<template>
  <c-box
    as="main"
    d="flex"
    align-items="center"
    direction="column"
    w="auto"
    p="16"
  >
    <c-input placeholder="Search components..." size="lg" mb="5" is-full-width />
  </c-box>
</template>

<script>
import { CBox, CInput } from '@chakra-ui/vue'
export default {
  components: {
    CBox,
    CInput
  }
}
</script>

Here is how our application looks like now:

You can see from the above screencast how the CInput element automatically knows when it’s in dark mode and adjust accordingly even though we didn’t explicitly set that. Also, the user can hit the tab key to focus on that CInput component.

Adding The Components’ List

So the idea of the Chakra-ui explorer (as stated earlier) is to show the user all of the available components in Chakra UI so that we can have a list of those components as well as the links that will take the user to the documentation of the component. To do this, I will create a folder called data at the root of our project’s directory then create a file called index.js. In index.js, I will export an array of objects which will contain the names of the components. Here is how the file should look like:

// ./data/index.js

export const components = [
  {
    name: 'Accordion'
  },
  {
    name: 'Alert'
  },
  {
    name: 'AlertDialog'
  },
  {
    name: 'AspectRatioBox'
  },
  {
    name: 'AspectRatioBox'
  },
  {
    name: 'Avatar'
  },
  {
    name: 'Badge'
  },
  {
    name: 'Box'
  },
  {
    name: 'Breadcrumb'
  },
  {
    name: 'Button'
  },
  {
    name: 'Checkbox'
  },
  {
    name: 'CircularProgress'
  },
  {
    name: 'CloseButton'
  },
  {
    name: 'Code'
  },
  {
    name: 'Collapse'
  },
  {
    name: 'ControlBox'
  },
  {
    name: 'Divider'
  },
  {
    name: 'Drawer'
  },
  {
    name: 'Editable'
  },
  {
    name: 'Flex'
  },
  {
    name: 'Grid'
  },
  {
    name: 'Heading'
  },
  {
    name: 'Icon'
  },
  {
    name: 'IconButton'
  },
  {
    name: 'IconButton'
  },
  {
    name: 'Input'
  },
  {
    name: 'Link'
  },
  {
    name: 'List'
  },
  {
    name: 'Menu'
  },
  {
    name: 'Modal'
  },
  {
    name: 'NumberInput'
  },
  {
    name: 'Popover'
  },
  {
    name: 'Progress'
  },
  {
    name: 'PseudoBox'
  },
  {
    name: 'Radio'
  },
  {
    name: 'SimpleGrid'
  },
  {
    name: 'Select'
  },
  {
    name: 'Slider'
  },
  {
    name: 'Spinner'
  },
  {
    name: 'Stat'
  },
  {
    name: 'Stack'
  },
  {
    name: 'Switch'
  },
  {
    name: 'Tabs'
  },
  {
    name: 'Tag'
  },
  {
    name: 'Text'
  },
  {
    name: 'Textarea'
  },
  {
    name: 'Toast'
  },
  {
    name: 'Tooltip'
  }
]

For our implementation to be complete, I will import the above array into pages/index.vue and iterate over it to display all the components. Also, we will give the user the ability to filter the components using the search box. Here is the complete implementation:

// pages/index.vue
<template>
  <c-box
    as="main"
    d="flex"
    align-items="space-between"
    flex-direction="column"
    w="auto"
    p="16"
  >
    <c-input v-model="search" placeholder="Search components..." size="lg" mb="10" is-full-width />
    <c-grid template-columns="repeat(4, 1fr)" gap="3" p="5">
      <c-box v-for="(chakraComponent, index) of filteredComponents" :key="index" h="10">
        {{ chakraComponent.name }}
  
      <c-badge>
          <c-link
            is-external
            :href="lowercase(`https://vue.chakra-ui.com/${chakraComponent.name}`)"
          >
            <c-icon name="info" size="18px" />
          </c-link>
        </c-badge>
      </c-box>
    </c-grid>
  </c-box>
</template>

<script>
import { CBox, CInput, CGrid, CLink, CBadge, CIcon } from '@chakra-ui/vue'
import { components as chakraComponents } from '../data'
export default {
  components: {
    CBox,
    CInput,
    CGrid,
    CBadge,
    CIcon,
    CLink
  },
  data () {
    return {
      search: ''
    }
  },
  computed: {
    filteredComponents () {
      return chakraComponents.filter((component) => {
        return this.lowercase(component.name).includes(this.lowercase(this.search))
      })
    }
  },
  methods: {
    lowercase (value) {
      return value.toLowerCase()
    }
  }
}
</script>

And now our application looks like this:

You can now see how dark mode is automatic for the component’s list as well as how the focus management is added for the links (by default) to aid accessibility.

Putting Chakra UI To The Test

Finally, let’s see how our app scores by running the Lighthouse accessibility test on it. Mind you, this test is based on the Axe user impact assessment. Below is a screencast of the test. You can also run the test yourself by following these steps.

From the screencast above you can see that our Chakra UI app has a score of 85 on the lighthouse accessibility test.

Conclusion

In this article, we have touched on the need for building accessible interfaces and we have also seen how to use Chakra UI to build accessible applications from the ground up by building an explorer (Chakra-ui explorer) for the Chakra UI components.

• See the live application on Netlify →
• Link to the repo →

(ra, yk, il)

One of my favorite quotes about software testing is from the Flutter documentation. It says:

“How can you ensure that your app continues to work as you add more features or change existing functionality? By writing tests.”

On that note, this last part of the Mirage JS Deep Dive series will focus on using Mirage to test your JavaScript front-end application.

Note: This article assumes a Cypress environment. Cypress is a testing framework for UI testing. You can, however, transfer the knowledge here to whatever UI testing environment or framework you use.

Read Previous Parts Of The Series:

• Part 1: Understanding Mirage JS Models And Associations
• Part 2: Understanding Factories, Fixtures And Serializers
• Part 3: Understanding Timing, Response And Passthrough

UI Tests Primer

UI or User Interface test is a form of acceptance testing done to verify the user flows of your front-end application. The emphasis of these kinds of software tests is on the end-user that is the actual person who will be interacting with your web application on a variety of devices ranging from desktops, laptops to mobile devices. These users would be interfacing or interacting with your application using input devices such as a keyboard, mouse, or touch screens. UI tests, therefore, are written to mimic the user interaction with your application as close as possible.

Let’s take an e-commerce website for example. A typical UI test scenario would be:

• The user can view the list of products when visiting the homepage.

Other UI test scenarios might be:

• The user can see the name of a product on the product’s detail page.
• The user can click on the “add to cart” button.
• The user can checkout.

You get the idea, right?

In making UI Tests, you will mostly be relying on your back-end states, i.e. did it return the products or an error? The role Mirage plays in this is to make those server states available for you to tweak as you need. So instead of making an actual request to your production server in your UI tests, you make the request to Mirage mock server.

For the remaining part of this article, we will be performing UI tests on a fictitious e-commerce web application UI. So let’s get started.

Our First UI Test

As earlier stated, this article assumes a Cypress environment. Cypress makes testing UI on the web fast and easy. You could simulate clicks and navigation and you can programmatically visit routes in your application. See the docs for more on Cypress.

So, assuming Cypress and Mirage are available to us, let’s start off by defining a proxy function for your API request. We can do so in the support/index.js file of our Cypress setup. Just paste the following code in:

// cypress/support/index.js
Cypress.on("window:before:load", (win) => {
  win.handleFromCypress = function (request) {
    return fetch(request.url, {
      method: request.method,
      headers: request.requestHeaders,
      body: request.requestBody,
    }).then((res) => {
      let content =
        res.headers.map["content-type"] === "application/json"
          ? res.json()
          : res.text()
      return new Promise((resolve) => {
        content.then((body) => resolve([res.status, res.headers, body]))
      })
    })
  }
})

Then, in your app bootstrapping file (main.js for Vue, index.js for React), we’ll use Mirage to proxy your app’s API requests to the handleFromCypress function only when Cypress is running. Here is the code for that:

import { Server, Response } from "miragejs"

if (window.Cypress) {
  new Server({
    environment: "test",
    routes() {
      let methods = ["get", "put", "patch", "post", "delete"]
      methods.forEach((method) => {
        this[method]("/*", async (schema, request) => {
          let [status, headers, body] = await window.handleFromCypress(request)
          return new Response(status, headers, body)
        })
      })
    },
  })
}

With that setup, anytime Cypress is running, your app knows to use Mirage as the mock server for all API requests.

Let’s continue writing some UI tests. We’ll begin by testing our homepage to see if it has 5 products displayed. To do this in Cypress, we need to create a homepage.test.js file in the tests folder in the root of your project directory. Next, we’ll tell Cypress to do the following:

• Visit the homepage i.e / route
• Then assert if it has li elements with the class of product and also checks if they are 5 in numbers.

Here is the code:

// homepage.test.js
it('shows the products', () => {
  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

You might have guessed that this test would fail because we don’t have a production server returning 5 products to our front-end application. So what do we do? We mock out the server in Mirage! If we bring in Mirage, it can intercept all network calls in our tests. Let’s do this below and start the Mirage server before each test in the beforeEach function and also shut it down in the afterEach function. The beforeEach and afterEach functions are both provided by Cypress and they were made available so you could run code before and after each test run in your test suite — hence the name. So let’s see the code for this:

// homepage.test.js
import { Server } from "miragejs"

let server

beforeEach(() => {
  server = new Server()
})

afterEach(() => {
  server.shutdown()
})

it("shows the products", function () {
  cy.visit("/")

  cy.get("li.product").should("have.length", 5)
})

Okay, we are getting somewhere; we have imported the Server from Mirage and we are starting it and shutting it down in beforeEach and afterEach functions respectively. Let’s go about mocking our product resource.

// homepage.test.js
import { Server, Model } from 'miragejs';

let server;

beforeEach(() => {
  server = new Server({
    models: {
      product: Model,
    },

    routes() {
      this.namespace = 'api';

      this.get('products', ({ products }, request) => {
        return products.all();
      });
    },
  });
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

Note: You can always take a peek at the previous parts of this series if you don’t understand the Mirage bits of the above code snippet.

• Part 1: Understanding Mirage JS Models And Associations
• Part 2: Understanding Factories, Fixtures And Serializers
• Part 3: Understanding Timing, Response And Passthrough

Okay, we have started fleshing out our Server instance by creating the product model and also by creating the route handler for the /api/products route. However, if we run our tests, it will fail because we don’t have any products in the Mirage database yet.

Let’s populate the Mirage database with some products. In order to do this, we could have used the create() method on our server instance, but creating 5 products by hand seems pretty tedious. There should be a better way.

Ah yes, there is. Let’s utilize factories (as explained in the second part of this series). We’ll need to create our product factory like so:

// homepage.test.js
import { Server, Model, Factory } from 'miragejs';

let server;

beforeEach(() => {
  server = new Server({
    models: {
      product: Model,
    },
     factories: {
      product: Factory.extend({
        name(i) {
            return `Product ${i}`
        }
      })
    },

    routes() {
      this.namespace = 'api';

      this.get('products', ({ products }, request) => {
        return products.all();
      });
    },
  });
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

Then, finally, we’ll use createList() to quickly create the 5 products that our test needs to pass.

Let’s do this:

// homepage.test.js
import { Server, Model, Factory } from 'miragejs';

let server;

beforeEach(() => {
  server = new Server({
    models: {
      product: Model,
    },
     factories: {
      product: Factory.extend({
        name(i) {
            return `Product ${i}`
        }
      })
    },

    routes() {
      this.namespace = 'api';

      this.get('products', ({ products }, request) => {
        return products.all();
      });
    },
  });
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  server.createList("product", 5)
  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

So when we run our test, it passes!

Note: After each test, Mirage’s server is shutdown and reset, so none of this state will leak across tests.

Avoiding Multiple Mirage Server

If you have been following along this series, you’d notice when we were using Mirage in development to intercept our network requests; we had a server.js file in the root of our app where we set up Mirage. In the spirit of DRY (Don’t Repeat Yourself), I think it would be good to utilize that server instance instead of having two separate instances of Mirage for both development and testing. To do this (in case you don’t have a server.js file already), just create one in your project src directory.

Note: Your structure will differ if you are using a JavaScript framework but the general idea is to setup up the server.js file in the src root of your project.

So with this new structure, we’ll export a function in server.js that is responsible for creating our Mirage server instance. Let’s do that:

// src/server.js

export function makeServer() { /* Mirage code goes here */}

Let’s complete the implementation of the makeServer function by removing the Mirage JS server we created in homepage.test.js and adding it to the makeServer function body:

import { Server, Model, Factory } from 'miragejs';

export function makeServer() {
  let server = new Server({
    models: {
      product: Model,
    },
    factories: {
      product: Factory.extend({
        name(i) {
          return `Product ${i}`;
        },
      }),
    },
    routes() {
      this.namespace = 'api';

      this.get('/products', ({ products }) => {
        return products.all();
      });
    },
    seeds(server) {
      server.createList('product', 5);
    },
  });
  return server;
}

Now all you have to do is import makeServer in your test. Using a single Mirage Server instance is cleaner; this way you don’t have to maintain two server instances for both development and test environments.

After importing the makeServer function, our test should now look like this:

import { makeServer } from '/path/to/server';

let server;

beforeEach(() => {
  server = makeServer();
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  server.createList('product', 5);

  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

So we now have a central Mirage server that serves us in both development and testing. You can also use the makeServer function to start Mirage in development (see first part of this series).

Your Mirage code should not find it’s way into production. Therefore, depending on your build setup, you would need to only start Mirage during development mode.

Note: Read my article on how to set up API Mocking with Mirage and Vue.js to see how I did that in Vue so you could replicate in whatever front-end framework you use.

Testing Environment

Mirage has two environments: development (default) and test. In development mode, the Mirage server will have a default response time of 400ms(which you can customize. See the third article of this series for that), logs all server responses to the console, and loads the development seeds.

However, in the test environment, we have:

• 0 delays to keep our tests fast
• Mirage suppresses all logs so as not to pollute your CI logs
• Mirage will also ignore the seeds() function so that your seed data can be used solely for development but won’t leak into your tests. This helps keep your tests deterministic.

Let’s update our makeServer so we can have the benefit of the test environment. To do that, we’ll make it accept an object with the environment option(we will default it to development and override it in our test). Our server.js should now look like this:

// src/server.js
import { Server, Model, Factory } from 'miragejs';

export function makeServer({ environment = 'development' } = {}) {
  let server = new Server({
    environment,

    models: {
      product: Model,
    },
    factories: {
      product: Factory.extend({
        name(i) {
          return `Product ${i}`;
        },
      }),
    },

    routes() {
      this.namespace = 'api';

      this.get('/products', ({ products }) => {
        return products.all();
      });
    },
    seeds(server) {
      server.createList('product', 5);
    },
  });
  return server;
}

Also note that we are passing the environment option to the Mirage server instance using the ES6 property shorthand. Now with this in place, let’s update our test to override the environment value to test. Our test now looks like this:

import { makeServer } from '/path/to/server';

let server;

beforeEach(() => {
  server = makeServer({ environment: 'test' });
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  server.createList('product', 5);

  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

AAA Testing

Mirage encourages a standard for testing called the triple-A or AAA testing approach. This stands for Arrange, Act and Assert. You could see this structure in our above test already:

it("shows all the products", function () {
  // ARRANGE
  server.createList("product", 5)

  // ACT
  cy.visit("/")

  // ASSERT
  cy.get("li.product").should("have.length", 5)
})

You might need to break this pattern but 9 times out of 10 it should work just fine for your tests.

Let’s Test Errors

So far, we’ve tested our homepage to see if it has 5 products, however, what if the server is down or something went wrong with fetching the products? We don’t need to wait for the server to be down to work on how our UI would look like in such a case. We can simply simulate that scenario with Mirage.

Let’s return a 500 (Server error) when the user is on the homepage. As we have seen in a previous article, to customize Mirage responses we make use of the Response class. Let’s import it and write our test.

homepage.test.js
import { Response } from "miragejs"

it('shows an error when fetching products fails', function() {
  server.get('/products', () => {
    return new Response(
      500,
      {},
      { error: "Can’t fetch products at this time" }
    );
  });

  cy.visit('/');

  cy.get('div.error').should('contain', "Can’t fetch products at this time");
});

What a world of flexibility! We just override the response Mirage would return in order to test how our UI would display if it failed fetching products. Our overall homepage.test.js file would now look like this:

// homepage.test.js
import { Response } from 'miragejs';
import { makeServer } from 'path/to/server';

let server;

beforeEach(() => {
  server = makeServer({ environment: 'test' });
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  server.createList('product', 5);

  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

it('shows an error when fetching products fails', function() {
  server.get('/products', () => {
    return new Response(
      500,
      {},
      { error: "Can’t fetch products at this time" }
    );
  });

  cy.visit('/');

  cy.get('div.error').should('contain', "Can’t fetch products at this time");
});

Note the modification we did to the /api/products handler only lives in our test. That means it works as we previously define when you are in development mode.

So when we run our tests, both should pass.

Note: I believe its worthy of noting that the elements we are querying for in Cypress should exist in your front-end UI. Cypress doesn’t create HTML elements for you.

Testing The Product Detail Page

Finally, let’s test the UI of the product detail page. So this is what we are testing for:

• User can see the product name on the product detail page

Let’s get to it. First, we create a new test to test this user flow.

Here is the test:

it("shows the product’s name on the detail route", function() {
  let product = this.server.create('product', {
    name: 'Korg Piano',
  });

  cy.visit(`/${product.id}`);

  cy.get('h1').should('contain', 'Korg Piano');
});

Your homepage.test.js should finally look like this.

// homepage.test.js
import { Response } from 'miragejs';
import { makeServer } from 'path/to/server;

let server;

beforeEach(() => {
  server = makeServer({ environment: 'test' });
});

afterEach(() => {
  server.shutdown();
});

it('shows the products', function() {
  console.log(server);
  server.createList('product', 5);

  cy.visit('/');

  cy.get('li.product').should('have.length', 5);
});

it('shows an error when fetching products fails', function() {
  server.get('/products', () => {
    return new Response(
      500,
      {},
      { error: "Can’t fetch products at this time" }
    );
  });

  cy.visit('/');

  cy.get('div.error').should('contain', "Can’t fetch products at this time");
});

it("shows the product’s name on the detail route", function() {
  let product = server.create('product', {
    name: 'Korg Piano',
  });

  cy.visit(`/${product.id}`);

  cy.get('h1').should('contain', 'Korg Piano');
});

When you run your tests, all three should pass.

Wrapping Up

It’s been fun showing you the inners of Mirage JS in this series. I hope you have been better equipped to start having a better front-end development experience by using Mirage to mock out your back-end server. I also hope you’ll use the knowledge from this article to write more acceptance/UI/end-to-end tests for your front-end applications.

• Part 1: Understanding Mirage JS Models And Associations
• Part 2: Understanding Factories, Fixtures And Serializers
• Part 3: Understanding Timing, Response And Passthrough
• Part 4: Using Mirage JS And Cypress For UI Testing

(ra, il)

In the era of SPA and the JAMstack, there has always been a separation of concern between the APIs and front-end development. Almost all JavaScript projects that can be found out in the wild interact with a web service or API and either use it for authentications or getting user-related data.

So, whenever you’re working on a project and the necessary API still hasn’t been implemented by the back-end team or you need to quickly test a feature, you have some of the following options:

• You could proxy to a locally running version of your actual backend which, in most cases as a front-end developer, you wouldn’t have.
• You could comment out actual request and replace with mock data. (This is okay but not so great as you would need to undo that to get to production and you might not be able to deal with network states and latency.)

What Is API Mocking?

API mocking is an imitation or a simulation of an actual API. It is mostly done in order to intercept requests that are supposed to be made to an actual backend API but this mocking exist on your frontend.

Why is API Mocking Important

API mocking is significantly important in a lot of ways:

1. It makes for a very good front-end development experience not to depend on production APIs before building out features.
2. You could share your entire frontend and it would work without depending on an actual backend API.

What Is Mirage JS?

Mirage JS was created 5 years ago and was pretty much used in the Ember community before Sam Selikoff officially announced its release on the 24th of January, 2020 on Twitter.

Mirage JS solves the pain point for testing backend APIs without depending on those APIs. It allows for seamless front-end development experience by mocking production APIs.

Mirage JS is an API mocking library for Vue.js, React, Angular and Ember frameworks

What Makes Mirage JS A Better Choice?

There have been other options for API mocking (such as Axios interceptors, Typicode’s JSON server, and so on) but what I think is pretty interesting about Mirage is that it doesn’t get in the way of your development process (as you would see when we set it up with Vue in a bit). It is lightweight and yet powerful.

It comes with battery included out of the box that allows you to replicate real production API consumption scenarios like simulating a slow network with its timing option.

Getting Started With Mirage JS And Vue.js

So now that you know what Mirage JS is and why it’s important to your front-end development workflow, let’s look at setting it up with the progressive web framework: Vue.js.

Creating A Green-Field (Clean Installation) Vue Project

Using the Vue CLI, create a fresh Vue.js project by going into the directory you want the project to be created in and running (in your terminal):

vue create miragejs-demo-vue 

The above command would set up a new Vue project which you can now cd into and run either yarn serve or npm run serve.

#Installing Mirage JS

Now let’s install Mirage JS as a development dependency in our Vue.js project by running the following command:

yarn add -D miragejs

Or if you are using NPM, run this:

npm install --save-dev miragejs

And that’s it! Mirage JS is now installed in our Vue.js project.

Let’s Mock Out Something

With Mirage JS installed, let’s see how we configure it to talk to Vue and mock out a basic todos (an API that returns a list of todos) API.

Define Your Server

To get started, we need to create a server.js file in the /src directory of our Vue.js project. After that, add the following:

import { Server, Model } from 'miragejs'

export function makeServer({ environment = "development" } = {}) {

let server = new Server({
  environment,

    models: {
      todo: Model,
    },

  seeds(server) {
  server.create("todo", { content: "Learn Mirage JS" })
  server.create("todo", { content: "Integrate With Vue.js" })
  },

  routes() {

    this.namespace = "api"

    this.get("/todos", schema => {
      return schema.todos.all()
    })
    
  },
  })

  return server
}

Code Explained

Firstly, the server.js file is how you set up Mirage JS to create a new instance of it’s mock (fake) server which will intercept all API calls you make in your app matching the routes that you define.

Now, I agree the above may be overwhelming at first, but let’s take a closer look at what’s going on here:

import { Server, Model } from 'miragejs'

From the above code snippet, we are importing Server and Model from miragejs.

• Server
  This is a class exposed by Mirage to helps us instantiate a new instance of a Mirage JS server to “serve” as our fake server.
• Model
  Another class exposed by Mirage to help in creating models(a model determines the structure of a Mirage JS database entry) powered by Mirage’s ORM.

export function makeServer({ environment = "development" } = {}) {}

The above basically export a function called makeServer from the src/server.js. You could also note we are passing in an environment parameter and setting Mirage’s environment mode to development (you would see us passing test environment later on in this article).

The Body Of makeServer

Now we are doing a couple of things in the makeServer body. Let’s take a look:

let server = new Server({})

We are instantiating a new instance of the Server class and passing it a configuration option. The content of the configuration options help set up mirage:

{
  environment,

  models: {
    todo: Model,
  },

  seeds(server) {
  server.create("todo", { content: "Learn Mirage JS" })
  server.create("todo", { content: "Integrate With Vue.js" })
  },

  routes() {

    this.namespace = "api"

    this.get("/todos", schema => {
      return schema.todos.all()
    })
  },
  
  }

Firstly we are passing the environment parameter we initialized in the function definition.

models: {
    todo: Model,
  },

The next option which is the models option takes an object of the different models we want Mirage to mock.

In the above, we simply want a todo model which we are instantiating from the Model class.

seeds(server) {
server.create("todo", { content: "Learn Mirage JS" })
server.create("todo", { content: "Integrate With Vue.js" })
},

The next option is the seeds method which takes in a parameter called server. The seeds method helps create seeds(seeds are initial data or an entry into Mirage’s database) for our models. In our case to create the seeds for the todo model we do:

server.create("todo", { content: "Learn Mirage JS" })
server.create("todo", { content: "Integrate With Vue.js" })

so the server has a create method which expects as the first argument a string which corresponds to the name of the model, then an object which will contain the properties or attributes of a particular seed.

routes() {

    this.namespace = "api"

    this.get("/todos", schema => {
      return schema.todos.all()
    })
  },

finally, we have the routes method which defines the various route(routes are our mock API endpoints) Mirage JS is going to mock. Let’s look at the body of the method:

this.namespace = "api"

this line sets up the namespace for all routes that means our todo route can now be accessed from /api/todos.

this.get("/todos", schema => {
  return schema.todos.all()
})

The above creates a get route and it’s handler using the this.get() method. The get() method expects the route i.e “/todos” and a handler function that takes in schema as an argument. The schema object is how you interact with Mirage’s ORM which is powered by Mirage JS in-memory database.

Finally:

return schema.todos.all()

We are returning a list of all our todos, using the schema object made possible by Mirage’s ORM.

src/main.js

So we are done setting up src/server.js but Vue doesn’t know about it(at least not yet). So let’s import it in our main.js file like so:

import { makeServer } from "./server"

Then we call the makeServer function like so:

if (process.env.NODE_ENV === "development") {
  makeServer()
}

The above if conditional is a guard to make sure mirage only runs in development.

Set up Complete!

Now we’ve set up Miragejs with Vue. Let’s see it in action. In our App.vue file, we would clear out the content and replace with the below snippet:

<template>
  <ul id="todos">
    <li v-for="todo in todos" v-bind:key="todo.id">{{ todo.content }}</li>
  </ul>
</template>

<script>
  export default {
    name: 'app',

    data() {
      return {
        todos: []
      }
    },

    created() {
      fetch("/api/todos")
        .then(res => res.json())
        .then(json => {
          this.todos = json.todos
        })
    }
  }
</script>

If you are familiar with Vue.js, the above would be nothing new but for the sake of being total, what we are doing is making an API request using fetch when our App.vue component is created, then we pass in the returned data to the todos array in our component state. Afterward, we are using a v-for to iterate the todos array and displaying the content property of each todo.

Where Is The Mirage JS Part?

If you notice, in our App.vue component, we didn’t do anything specific to Mirage, we are just making an API call as we would normally do. This feature of Mirage is really great for DX cause under the hood, Mirage would intercept any requests that match any of the routes defined in src/server.js while you are in development.

This is pretty handy cause no work would be needed in your part to switch to an actual production server when you are in a production environment provided the routes match your production API endpoints.

So restart your Vue dev server via yarn serve to test Mirage JS.

You should see a list of two todos. One thing you’d find pretty interesting is that we did not need to run a terminal command to start up Mirage because it removes that overhead by running as a part of your Vue.js application.

Mirage JS And Vue test-utils

If you are already using Vue Test-utils in your Vue application, you’d find it exciting to know that Mirage can easily work with it to mock network requests. Let’s see an example set up using our todos application.

We would be using Jest for our unit-testing. So if you are following along, you could pretty much use the Vue CLI to install the @vue/unit-jest plugin like so:

vue add @vue/unit-jest

The above will install @vue/cli-plugin-unit-jest and @vue/test-utils development dependencies while also creating a tests directory and a jest.config.js file. It will also add the following command in our package.json scripts section (pretty neat):

"test:unit": "vue-cli-service test:unit"

Let’s Test!

We would update our App.vue to look like this:

<!-- src/App.vue -->
<template>
  <div v-if="serverError" data-testid="server-error">
    {{ serverError }}
  </div>

  <div v-else-if="todos.length === 0" data-testid="no-todos">
    No todos!
  </div>

  <div v-else>
    <ul id="todos">
      <li
        v-for="todo in todos"
        v-bind:key="todo.id"
        :data-testid="'todo-' + todo.id"
      >
        {{ todo.content }}
      </li>
    </ul>
  </div>
</template>

<script>
  export default {
    name: "app",

    data() {
      return {
        todos: [],
        serverError: null,
      }
    },

    created() {
      fetch("/api/todos")
        .then(res => res.json())
        .then(json => {
          if (json.error) {
            this.serverError = json.error
          } else {
            this.todos = json.todos
          }
        })
    },
  }
</script>

Nothing really epic is going on in the above snippet; we are just structuring to allow for the network testing we would be implementing with our unit test.

Although Vue CLI has already added a /tests folder for us, I find it to be a much better experience when my tests are placed close to the components they are testing. So create a /__tests__ folder in src/ and create an App.spec.js file inside it. (This is also the recommended approach by Jest.)

// src/__tests__/App.spec.js
import { mount } from "@vue/test-utils"
import { makeServer } from "../server"
import App from "../App.vue"

let server

beforeEach(() => {
  server = makeServer({ environment: "test" })
})

afterEach(() => {
  server.shutdown()
})

So to set up our unit testing, we are importing the mount method from @vue/test-utils, importing the Miragejs server we created earlier and finally importing the App.vue component.

Next, we are using the beforeEach life cycle function to start the Mirage JS server while passing in the test environment. (Remember, we set by default the environment to be development.)

Lastly, we are shutting down the server using server.shutdown in the afterEach lifecycle method.

Our Tests

Now let’s flesh out our test (we would be adopting the quickstart section of the Mirage js docs. So your App.spec.js would finally look like this:

// src/__tests__/App.spec.js

import { mount } from "@vue/test-utils"
import { makeServer } from "./server"
import App from "./App.vue"

let server

beforeEach(() => {
  server = makeServer({ environment: "test" })
})

it("shows the todos from our server", async () => {
  server.create("todo", { id: 1, content: "Learn Mirage JS" })
  server.create("todo", { id: 2, content: "Integrate with Vue.js" })

  const wrapper = mount(App)

  // let’s wait for our vue component to finish loading data
  // we know it’s done when the data-testid enters the dom.
  await waitFor(wrapper, '[data-testid="todo-1"]')
  await waitFor(wrapper, '[data-testid="todo-2"]')

  expect(wrapper.find('[data-testid="todo-1"]').text()).toBe("Learn Mirage JS")
  expect(wrapper.find('[data-testid="todo-2"]').text()).toBe("Integrate with Vue.js")
})

it("shows a message if there are no todo", async () => {
  // Don’t create any todos

  const wrapper = mount(App)
  await waitFor(wrapper, '[data-testid="no-todos"]')

  expect(wrapper.find('[data-testid="no-todos"]').text()).toBe("No todos!")
})

// This helper method returns a promise that resolves
// once the selector enters the wrapper’s dom.
const waitFor = function(wrapper, selector) {
  return new Promise(resolve => {
    const timer = setInterval(() => {
      const todoEl = wrapper.findAll(selector)
      if (todoEl.length > 0) {
        clearInterval(timer)
        resolve()
      }
    }, 100)
  })
}

afterEach(() => {
  server.shutdown()
})

Note: We are using a helper here (as defined in the Mirage JS docs). It returns a promise that allows us to know when the elements we are testing are already in the DOM.

Now run yarn test:unit.

All your tests should pass at this point.

Testing Different Server State With Mirage JS

We could alter our Mirage JS server to test for different server states. Let’s see how.

// src/__tests__/App.spec.js
import { Response } from "miragejs"

First, we import the Response class from Mirage, then we create a new test scenario like so:

it("handles error responses from the server", async () => {
  // Override Mirage’s route handler for /todos, just for this test
  server.get("/todos", () => {
    return new Response(
      500,
      {},
      {
        error: "The database is taking a break.",
      }
    )
  })

  const wrapper = mount(App)

  await waitFor(wrapper, '[data-testid="server-error"]')

  expect(wrapper.find('[data-testid="server-error"]').text()).toBe(
    "The database is taking a break."
  )
})

Run your test and it all should pass.

Conclusion

This article aimed to introduce you to Mirage JS and show you how it makes for a better front-end development experience. We saw the problem Mirage JS created to address (building production-ready front-end without any actual backend API) and how to set it up with Vue.js.

Although this article scratched the surface of what Mirage JS can do, I believe it is enough to get you started.

• You could go through the docs as well as join the Mirage JS discord server.
• The supporting repo for this article is available on GitHub.

References

• The Mirage Docs
• Mirage Vue Quickstart

(dm, il)