DEV Community: Jerico Pingul

Mocking local dev and tests with msw + @mswjs/data

Jerico Pingul — Sat, 22 Jan 2022 23:35:03 +0000

Background

Recently, I found myself needing to mock CRUD operations from an API. At that time, the API was being developed by another engineer. We agreed on the API specs which allowed me to progress on building the UI.

During development, the mocked APIs are useful to build to mock the actual API implementation.

During testing, it is also valuable to be able to test the actual user interactions. There are amazing blog posts by Kent C. Dodds (author of @testing-library/react) on avoiding testing implementation details and mocking the actual API over mocking fetch.

In this article, we will go though the approach I went to building this mock server using msw by building a simple pet dog CRUD application, that has the following features:

List all dogs
Create a dog
Update a dog
Delete a dog

Additionally, data can be stored in-memory database provided by a standalone data library msw/datajs. This provides the capabilities of describing our data, persisting them in-memory and read/write operations. We will explore writing REST API handlers backed by the data library methods.

Setup

In this article, l will be building a simple CRUD React application. To help quickly bootstrap my application I will be using the vitejs react-ts template and Chakra UI components. To help simplify and abstract our data-fetching and manage server state, react-query will be used.

For this demo, we will need to install the msw libraries and a mock generator faker. At the time of writing, the latest version of faker has “endgamed”. For this post, we’ll use version 5.5.3, which still works.

yarn add msw @mswjs/data
yarn add faker@5.5.3

Data model

Models are blueprint of data and entities are instances of models. Each model requires a primary key that is a unique ID in a traditional database.

Here, we define our dog model. Each property in the model definition has an initializer that seeds a value and infers the type. Each model must have a primary key that is a unique ID, that we may be familiar with in traditional databases.

import { factory, primaryKey } from '@mswjs/data';
import faker from 'faker';

const modelDictionary = {
  dog: {
    id: primaryKey(faker.datatype.uuid),
    breed: () => faker.helpers.randomize(BREEDS),
    age: () => faker.datatype.number(13),
    description: () => faker.lorem.words(5),
    owner: () => `${faker.name.firstName()} ${faker.name.lastName()}`,
  },
};

const db = factory(modelDictionary);

Seeding data

Once the database is created, we can seed it with data. Properties that aren’t set in the .create method will be resolved by the model dictionary definition.

export function seedDb() {
  db.dog.create({ owner: 'Jerico', breed: 'maltese' });
  db.dog.create({ owner: 'Jerry', breed: 'pug' });
}

Request handlers

These are functions that will mock the API requests from our app. In this app, we will be using the rest handlers to mock our REST API. More information on the syntax can be found in the msw docs.

export const handlers = [
  rest.get<DefaultRequestBody, PathParams, Dog[]>(
    '/api/dogs',
    (_req, res, ctx) => {
      return res(ctx.json(db.dog.getAll()));
    }
  ),
  rest.post<Omit<Dog, 'id'>, PathParams, Dog>('/api/dogs', (req, res, ctx) => {
    const created = db.dog.create(req.body);
    return res(ctx.json(created));
  }),
  rest.delete<DefaultRequestBody, { id: string }, Dog>(
    '/api/dogs/:id',
    (req, res, ctx) => {
      db.dog.delete({ where: { id: { equals: req.params.id } } });
      return res(ctx.status(204));
    }
  ),
  rest.put<Omit<Dog, 'id'>, { id: string }, Dog>(
    '/api/dogs/:id',
    (req, res, ctx) => {
      const updated = db.dog.update({
        where: { id: { equals: req.params.id } },
        data: req.body,
      });
      return res(ctx.json(updated!));
    }
  ),
];

Alternatively, mswjs/data provides a neat method that actually generates these request handlers using the following. Do note that the generated routes are in the following conventional format.

const handlers = [...db.user.toHandlers('rest')]

Running msw

In the browser

In our source code we can execute the following line. Note that we may want to conditionally execute this only on our local dev server.

import { setupWorker } from 'msw';

setupWorker(...handlers).start();

In the tests

Similarly, to mock API requests in our tests:

import { setupServer } from 'msw/node';

const server = setupServer(...handlers);

beforeAll(() => {
  server.listen();
});

afterAll(() => {
  server.close();
});

Implementation

The implementation will not be included in this post, but the full source code can be found in my repo and deployed here.

Wrap up

Writing a mock API using msw and mswjs/data allowed me to develop the UI while the actual API was being developed by another engineer. This setup also allowed me to write the request handlers only once for both my development server and tests. This personally made the effort worthwhile and made writing my tests enjoyable.

I hope this is something that will be of benefit to you, as much as it was for me.

Create and deploy a To-do CRUD service using Node.js, AWS and Serverless Framework

Jerico Pingul — Thu, 06 Aug 2020 16:22:33 +0000

Introduction

In this post, we will go through creating a simple CRUD (Create, Read, Update and Delete) service by creating a To-do service using Node.js, AWS and Serverless Framework. We will be creating and deploying AWS Lambda functions and expose them as RESTful APIs using Amazon API Gateway. We will also make use of a powerful Node.js middleware middy to make our development even simpler.

Architecture

Below is a high-level architecture of what we are going to build.

Setup

Before we get started, we will require some setup.

Create AWS Account

We must create an AWS account. For this set of instructions, it will not cost us anything. The AWS Free Tier should be plenty for our use case.

Serverless Framework Installation

We will install the Serverless Framework on our machines as a standalone binary.
There are multiple ways of doing this in the Serverless docs. In this post, we will be installing through NPM:

npm install -g serverless

To verify installation we will execute:

sls --version

AWS CLI Installation

In order to use the Serverless Framework efficiently in our machine, we will make use of the AWS CLI. Instructions specific to your machine can be found here. For macOS users like me, the instructions will be:

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"

sudo installer -pkg ./AWSCLIV2.pkg -target /

We can then verify the installation as follows:

aws --version

Configuring AWS CLI

At the moment AWS CLI does not know who we are. We will need to provide some information about this. The purpose of this is to link our local machine CLI with AWS.

Going back to our AWS console. We go into the Identity and Access Management (IAM) service. This service manages who can access our AWS resources.

Click on the "Users" tab.

Then, we can create a user.

Select "Attach existing policies directly". For the purpose of this post, we will grant this user with AdministratorAccess. Ideally, we should only grant users the level of access that is required.

The step to add tags can be skipped for this tutorial and we can proceed with creating the user.

Take note of your AWS Management Console access sign-in link. Note that the prefix on the link is our created user ID.

Also, take note of your Access Key ID and Secret Access Key.

Back in our terminal, we will execute the following command then enter the credentials we created. We will then select the location appropriate for us. In my case, I chose Europe as it is closest to me and that is where I would like my data to be stored.

aws configure

Now, AWS is configured and linked to our local machine.

Create Project

Now, we will create a project, which we will call todo-service. We will use a fork of a base project from Ariel Weinberger at codingly.io.

sls create --name todo-service --template-url https://github.com/jericopingul/sls-base

This will create a starter project for us. We have called it todo-service because all operations we will be doing for this to-do API will be defined within this service.

In our serverless.yml, we will add our region within the provider property. In my case it will be:

provider:
  stage: ${opt:stage, 'dev'}
  region: eu-west-1

You may be curious what the stage property is. In this case, this will define the stage to which where we will deploy our service. In real-life there will be multiple stages that include the likes of production or any other stage, depending on the development requirements. In this tutorial, we will just use one stage dev.
In terms of the syntax, the opt.stage can be used to reference variable, while the second parameter is a default ('dev') if opt.stage is not set.

We also use two plugins:

plugins:
  - serverless-bundle
  - serverless-pseudo-parameters

serverless-bundle provides us with a number of benefits including allowing us to bundle our JavaScript using webpack, reduce our bundle size, allow the use of modern JavaScript (ES6+) with minimal configuration.

serverless-pseudo-parameters allows us to easily interpolate AWS parameters which will make our life easier later on. More information on this plugin can be found here.

Create a Database

We will need to store our to-do items in a database. We will make use of a NoSQL DynamoDB provided by AWS. The AWS free tier gives us a generous amount of storage.

In order to create the database, we will add the following statement to our serverless.yml so that we can instruct CloudFormation to create it in AWS. We define an attribute that is going to be our primary key, in this case, it is id.

provider:
  ...

resources:
  Resources:
    TodoTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: TodoTable-${self:provider.stage}
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: id
            AttributeType: S
        KeySchema:
          - AttributeName: id
            KeyType: HASH

In the above statement, we are instructing AWS CloudFormation to create a table named TodoTable-dev with a primary key id with a PAY_PER_REQUEST billing.

With the changes above, we can create the database on AWS and deploy our project by using the command:

sls deploy -v

We are using an optional -v option which means verbose just to see more information on the logs.

In AWS CloudFormation we should see the todo-service-dev stack. In the resource tab, we can verify that our table has been created:

Third-party libraries

AWS SDK

We will require the aws-sdk library to create the DynamoDB client instance. More information here.

Middy

We will be using the middy middleware library to simplify our AWS Lambda code. We will be using middy, middy body-parser and middy HTTP error handler. So we will install the following:

yarn add @middy/core @middy/http-event-normalizer @middy/http-error-handler @middy/http-json-body-parser

The purpose of each library are as follows:

@middy/core is the core middy library.
@middy/http-event-normalizer simplifies accessing query string or path parameters.
@middy/http-error-handler handles uncaught errors and generates a proper HTTP response for them. See more info here.
@middy/http-json-body-parser parses HTTP requests with a JSON body and converts them into an object for use within our Lambdas.

Error handler

@middy/http-error-handler recommends using http-errors library to be used together with their library to simplify creating errors so we will also install the following:

yarn add http-errors

UUID

We will require to generate a unique identifier for each of our to-dos in the database so we will use the uuid library.

yarn add uuid

Creating our AWS Lambdas

Now, we will move onto creating our AWS Lambdas that we will expose via HTTP.

Create a To-do

Now we will create our create to-do Lambda function. In our serverless.yml we will add the following entry in the functions property:

functions:
  createTodo:
    handler: src/handlers/createTodo.handler
    events:
      - http:
          method: POST
          path: /todo

This means that we will have a createTodo.js file that exports a function handler in the src/handlers directory.

Here, we will use the middleware we installed. We will define a common middleware for all of Lambdas we will use in our project in common/middlware.js with the contents:

import middy from '@middy/core';
import jsonBodyParser from '@middy/http-json-body-parser';
import httpEventNormalizer from '@middy/http-event-normalizer';
import httpErrorHandler from '@middy/http-error-handler';

export default (handler) =>
  middy(handler).use([
    jsonBodyParser(),
    httpEventNormalizer(),
    httpErrorHandler(),
  ]);

This exported function will execute the listed middlewares in the array on the passed handler function.

Below, we add the custom property in our serverless.yml file. The purpose of this is to make it easier to make change our tables down the line. We make use of AWS CloudFormation intrinsic functions Ref and GetAtt so that when our stack is deployed then these values will be dynamically evaluated. For the purpose of this post, we will turn off linting on our JavaScript code but I would recommend this to be turned on in production code.

custom:
  TodoTable:
    name: !Ref TodoTable
    arn: !GetAtt TodoTable.Arn
  bundle:
    linting: false

We will also require to add permissions to our Lambda in serverless.yml to create entries in our database table:

provider:
  ...
  iamRoleStatements:
    - Effect: Allow
      Action:
        - dynamodb:PutItem

Below will be the code for our Lambda function in our createTodo.js file. We create a to-do item with the description from the request body and we set the done status as false by default. Note that we execute our common middleware in the last line.

const dynamoDB = new AWS.DynamoDB.DocumentClient();

async function createTodo(event, context) {
  const { description } = event.body;
  const now = new Date();

  const todo = {
    id: uuid(),
    description,
    created: now.toISOString(),
    updated: now.toISOString(),
    done: false,
  };

  try {
    await dynamoDB
      .put({
        TableName: process.env.TODO_TABLE_NAME,
        Item: todo,
      })
      .promise(); // to return a promise instead
  } catch (error) {
    console.error(error);
    throw new createError.InternalServerError(error);
  }

  return {
    statusCode: 201,
    body: JSON.stringify(todo),
  };
}

export const handler = middleware(createTodo);

We can deploy our changes with the same deploy command:

sls deploy -v

We should find our API URL/endpoint that we created in our terminal and we can verify using a REST client, here I'm using postman:

Retrieve To-dos

We create a new entry in serverless.yml to add the new getTodos function:

functions:
  ...     
  getTodos:
    handler: src/handlers/getTodos.handler
    events:
      - http:
          method: GET
          path: /todo

We are also required to add Scan action permissions.

provider:
  ...
  iamRoleStatements:
    - Effect: Allow
      Action:
        - dynamodb:Scan

Below is the code to retrieve all entries in the database table then returns it.

async function getTodos(event, context) {
  let todos;

  try {
    const result = await dynamoDB
      .scan({
        TableName: process.env.TODO_TABLE_NAME,
      })
      .promise();
    todos = result.Items;
  } catch (error) {
    console.error(error);
    throw new createError.InternalServerError(error);
  }

  return {
    statusCode: 200,
    body: JSON.stringify(todos),
  };
}

export const handler = middleware(getTodos);

Update a To-do

We will require to add the UpdateItem permissions.

provider:
  ...
  iamRoleStatements:
    - Effect: Allow
      Action:
        - dynamodb:UpdateItem

We create the following new function in our functions property. Note that we are using PATCH as we are going apply a partial update to the resource.

functions:
  ...
  updateTodo:
    handler: src/handlers/updateTodo.handler
    events:
      - http:
          method: PATCH
          path: /todo/{id}

Below we have the code for our update function. We will only allow the description and done fields to be updated. In the implementation below, we require at least one of description and done to be part of the request body, updates the data accordingly and finally returns the updated resource.

async function updateTodo(event, context) {
  const { id } = event.pathParameters;
  const { description, done } = event.body;
  const now = new Date();

  if (!description && done === undefined) {
    throw new createError.BadRequest(
      'You must update either description or done status!'
    );
  }

  const updatedAttributes = [];
  const expressionAttributeValues = {};

  if (description) {
    updatedAttributes.push(`description = :description`);
    expressionAttributeValues[':description'] = description;
  }

  if (done !== undefined) {
    updatedAttributes.push(`done = :done`);
    expressionAttributeValues[':done'] = !!done;
  }

  updatedAttributes.push(`updated = :updated`);
  expressionAttributeValues[':updated'] = new Date().toISOString();

  const updateExpression = `set ${updatedAttributes.join(', ')}`;

  const params = {
    TableName: process.env.TODO_TABLE_NAME,
    Key: { id },
    UpdateExpression: updateExpression,
    ExpressionAttributeValues: expressionAttributeValues,
    ReturnValues: 'ALL_NEW',
  };

  let updatedTodo;

  try {
    const result = await dynamoDB.update(params).promise();
    updatedTodo = result.Attributes;
  } catch (error) {
    console.error(error);
    throw new createError.InternalServerError(error);
  }

  return {
    statusCode: 200,
    body: JSON.stringify(updatedTodo),
  };
}

Delete a To-do

We first add the DeleteItem permission:

provider:
  ...
  iamRoleStatements:
    - Effect: Allow
      Action:
        - dynamodb:DeleteItem

Then add the new function in our functions property in serverless.yml:

functions:
  ...
  deleteTodo:
    handler: src/handlers/deleteTodo.handler
    events:
      - http:
          method: DELETE
          path: /todo/{id}

Below we have our delete function that simply deletes an entry in the database table based on the id.

async function deleteTodo(event, context) {
  const { id } = event.pathParameters;

  const params = {
    TableName: process.env.TODO_TABLE_NAME,
    Key: { id },
  };

  try {
    await dynamoDB.delete(params).promise();
  } catch (error) {
    console.error(error);
    throw new createError.InternalServerError(error);
  }

  return {
    statusCode: 200,
  };
}

Closing Notes

We have created a simple to-do CRUD service using Node.js, AWS Lambda and Serverless Framework. We have also made use of middleware libraries to simplify the development of our Lambdas.

There are a number of steps involved in the initial set up but once we have done this, it is straightforward to add create and add new functions.

Thank you for following along and I hope that this simple CRUD service helps in creating any serverless project. ✌🏼

Create a component library using Storybook and create-react-app

Jerico Pingul — Sun, 21 Jun 2020 22:44:44 +0000

In this post we will look at how we can use Storybook to create a component library using Create React App (CRA). In the end, we will create a simple button with some variations.

Setup

First we create the project using CRA. In this post, we will be using yarn but if you prefer to use npm, all commands should work as well so do feel free. In the CRA command below be sure to add the flag --use-npm to initialize as an npm project.

npx create-react-app component-lib

The next step is to add storybook to our project.

npx -p @storybook/cli sb init

You should see these new yarn scripts added to your package.json:

"scripts": {
  ...
  "storybook": "start-storybook -p 9009 -s public",
  "build-storybook": "build-storybook -s public"
}

Note: at this time of writing the version of Storybook used is 5.3.

By default, Storybook will read all files in your src/ directory that follows the .stories.js suffix (see .storybook/main.js)

stories: ['../src/**/*.stories.js'],

For the purpose of this post, we will keep it simple and place all our stories in the src/stories folder.

To run story book and you will be presented with the following dashboard:

yarn storybook

Storybook comes out of the box with demo buttons from their demo projects but we will be creating our own in the next step.

Creating your own component

Now we will create a simple button component with a few variations as examples so we can create different stories for each.

// src/components/Button.js
import React from 'react';
import './button.css';

const colors = {
  default: 'default',
  primary: 'primary',
  secondary: 'secondary',
};

const Button = ({ children, onClick, color, disabled }) => {
  const className = colors[color] ? `button ${colors[color]}` : 'button';
  return (
    <button className={className} onClick={onClick} disabled={disabled}>
      {children}
    </button>
  );
};

export default Button;

The styles for the component is defined below. Feel free to use your preferred method of styling your components. In this case we're just using plain CSS for simplicity's sake.

/* src/components/button.css */
.button {
  font-family: 'Roboto', 'Helvetica', 'Arial', sans-serif;
  padding: 6px 16px;
  font-size: 12px;
  min-width: 64px;
  box-sizing: border-box;
  font-weight: 500;
  line-height: 1.75;
  letter-spacing: 2px;
  cursor: pointer;
  border-radius: 4px;
  box-shadow: 0px 8px 15px rgba(0, 0, 0, 0.1);
}

.button[disabled] {
  cursor: default;
  pointer-events: none;
  color: rgba(0, 0, 0, 0.26);
  box-shadow: none;
  background-color: rgba(0, 0, 0, 0.12);
}

.primary {
  color: #fff;
  background-color: #1976d2;
}

.secondary {
  color: #fff;
  background-color: #dc004e;
}

We create the following stories for each variation of our Button component.

// src/stories/Button.stories.js
export const Primary = () => (
  <Button color="primary" onClick={action('clicked')}>
    Primary Button
  </Button>
);

export const Secondary = () => (
  <Button color="secondary" onClick={action('clicked')}>
    Secondary Button
  </Button>
);

export const Disabled = () => (
  <Button color="secondary" onClick={action('clicked')} disabled={true}>
    Disabled Button
  </Button>
);

export const WithEmojis = () => (
  <Button onClick={action('clicked')}>
    <span role="img" aria-label="so cool">
      With Emojis 😀 😎 👍 💯
    </span>
  </Button>
);

We should see the following in Storybook:

Building and exporting as a static app

Now that we have created our component library consisting of a single Button component. We now will think about building and exporting it. All we have to do is run the other yarn script:

"build-storybook": "build-storybook -s public"

Running the following will create the static Storybook files in the storybook-static directory.

yarn build-storybook

This can then be deployed as a static web app. In a follow-up post I will go through instructions how to do this.
For now we can test deploying this using the npm library http-server using the following command:

npx http-server storybook-static

Closing notes

We have gone through creating a simple React component library using Storybook and CRA. Storybook provides us the tools to make it straightforward to achieve this. We are just touching the surface and Storybook provides much more though add-ons, testing and more. See more information here. In a follow up post I will go through publishing deploying the static site and publishing our Button component as a library to a public npm registry so we can use it in other React apps so stay tuned.

Thanks for following and reading.✌🏼

DEV Community: Jerico Pingul

Mocking local dev and tests with msw + @mswjs/data

Background

Setup

Data model

Seeding data

Request handlers

Running msw

In the browser

In the tests

Implementation

Wrap up

Further reading

Create and deploy a To-do CRUD service using Node.js, AWS and Serverless Framework

Introduction

Architecture

Setup

Create AWS Account

Serverless Framework Installation

AWS CLI Installation

Configuring AWS CLI

Create Project

Create a Database

Third-party libraries

AWS SDK

Middy

Error handler

UUID

Creating our AWS Lambdas

Create a To-do

Retrieve To-dos

Update a To-do

Delete a To-do

Closing Notes

Create a component library using Storybook and create-react-app

Setup

Creating your own component

Building and exporting as a static app

Closing notes