DEV Community: Marko Cen

Automate Node.js Website E2E Test with Cypress and GitHub Actions

Marko Cen — Wed, 24 Jun 2020 14:16:14 +0000

In this article, we are going to explain how to setup a continue integration job on GitHub Actions to automatically trigger end-to-end testing by using Cypress e2e framework.

TLDR, the working code can be found here.

Not Familiar with Cypress?

Cypress is an open sourced modern e2e testing framework. It provides out of box solution to test website functionalities with cross browsers support. Cypress leverages the most popular testing libraries, like Sinon, Chai, etc, if you are familiar with these libraries, you can start to write Cypress e2e tests with zero learning curve. Cypress also super easy to setup, you can literally setup an Cypress testing server in 5 minutes by following its official documents. In this article, we are going to use Cypress to test our production website.

Why GitHub Actions?

GitHub Actions is the latest CI/DI platform introduced by GitHub. It deeply integrated with GitHub source control, you can easily build, test, deploy your code right from the your GitHub code repository. It supports most major platforms, like popular Linux distros, Windows and MacOS. GitHub also offers 2,000 Actions minutes per month for free account, which it is enough for most side/small projects. You can simply define GitHub Action jobs by using a yaml files and commit it into source control.

Build Website

First we are going to build the testing website using nodejs and express, our website has one page and one API handler. When users visit the website, they will see a login form, and login request will be handled by /submit api.

import express from "express";
import * as http from "http";
import * as path from "path";

const app = express();

app.get("/", (req, res) => {
  res.sendFile(path.resolve("public/index.html"));
});

app.post("/submit", (req, res) => {
  res.end("submit success!");
});

const server = http.createServer(app);

server.listen("4040");

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Cypress E2E Test Demo Page</title>
  </head>
  <body>
    <!-- simple login form -->
    <form>
      <label>
        username
        <input type="text" id="username" />
      </label>
      <label>
        password
        <input type="password" id="password" />
      </label>
      <button type="submit">Submit</button>
    </form>

    <!-- we use axios as restful request client -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/axios/0.19.2/axios.min.js"></script>
    <script>
      const form = document.querySelector('form');

      form.onsubmit = (e) => {
        e.preventDefault();
        const username = form.querySelector('#username').value;
        const password = form.querySelector('#password').value;

        axios.post("/submit", { username, password });
      }
    </script>
  </body>
</html>

Setup E2E Test

First install Cypress through npm or yarn

npm install cypress -D

Then create cypress.json to config cypress server

{
  "baseUrl": "http://localhost:4040",
  "fixturesFolder": "e2e/fixtures",
  "integrationFolder": "e2e/tests",
  "screenshotsFolder": "e2e/screenshots",
  "videosFolder": "e2e/videos",
  "supportFile": false,
  "pluginsFile": false
}

We config the baseUrl to localhost because we are going to start the website in local CI environment. It also support remote url like using a deployed website url, in that case, e2e tests will be run against the production website. integrationFolder defined the path to test files, and fixturesFolder and screenshotsFolder will be used to locate fixture data and screenshot images.

The last thing is to write the test, for demonstrate purpose, we only have one test file which contains two tests to cover the login flow. You can check more usage details on cypress website.

// e2e/tests/index.test.js

describe("Index Page", () => {
  before(() => {
    cy.visit("localhost:4040");
  });

  it("should contain a form element", () => {
    const form = cy.get("form");
    form.should("exist");
    form.get('input#username').should('exist');
    form.get('input#password').should('exist');
    form.get('button[type="submit"]').should('exist');
  });

  it("should send http request with login payload when submit button clicked", () => {
    cy.server();
    cy.route("POST", "/submit").as("submit");
    cy.get('input#username').type("test");
    cy.get('input#password').type("123abc");
    cy.get('button[type="submit"]').click();

    cy.wait("@submit").should("have.property", "status", 200);

    cy.get("@submit").should((xhr) => {
      expect(xhr.request.body).to.deep.equal({ username: "test", password: "123abc" });
      expect(xhr.response.body).to.equal("submit success!");
    });
  });
});

Test Run

That's it, our Cypress server is ready to run, to start the server locally, execute npx cypress open, and the Cypress dashboard will show up

In dashboard, it lists the test we just wrote, we can select the testing browser and check previous running results. Now click 'Run all specs', Cypress will start to execute our tests (make sure our website is started before running tests!). We will see the target browser pop up and all tests executed successfully!

Define CI Pipeline

The last step is to setup GitHub Action workflow, workflow is a custom automated processes that we can set up in repository to build, test, package, release, or deploy any project on GitHub. We want the workflow can run e2e test automatically when there are new commits pushed to master branch, the workflow has several jobs, first it will checkout source code to local, then install nodejs and dependencies, finally start e2e testing.

To define workflow, we should create a yaml file and put it in .github/workflows folder, and commit it into source control. More workflow sytax detail can be found on here.

name: E2E Test

on:
  push:
    branches:
      - master

jobs:
  e2e:
    runs-on: ubuntu-16.04

    steps:
      - name: Checkout Code
        uses: actions/checkout@v2

      - name: Install Node
        uses: actions/setup-node@v1
        with:
          node-version: "14"

      - name: Install Dependencies
        run: npm i

      - name: Run Cypress
        uses: cypress-io/github-action@v2
        with:
          start: npm run start

Here we use the official cypress-io/github-action plugin to help us start cypress testing, but it's same as easy as setting up by ourself. Once this file committed and pushed, we will see workflow can be triggered by following commits.

Build RESTful API Server with Deno and Docker

Marko Cen — Sat, 30 May 2020 18:26:21 +0000

This article originally posted on 345Tool Blog

Deno 1.0 has been released in May, 2020. Deno is a modern runtime that uses V8 and is built in Rust. Compared to its predecessor Node.js, Deno ships with a set of standard modules and secure by default. Although there is still a long way to go, Deno gives the TypeScript users a solid option to build modern web applications. In this article, we are going to build a simple RESTful API server with Deno, and containerize it with Docker.

TLDR: If you prefer reading the code, you can find the working code here and the version of Deno is 1.2

What we are going to build

We are going to build a very typical RESTful API server, it will do CRUD operations on backend data based on the requests received. The server contains following logic:

User Service - a service to manipulate users data. For demonstrate purposes, the service will only manipulate the data stored in memory.

API Server - a Deno http server listens. This is the main part we going to build. When the server started, it exposes two API endpoints GET /users and POST /user.

Docker Image - finally we are going to containerize deno runtime and our application using docker.

User service

To keep it simple, we use a list of users to mock the database data, and the addUser method will insert a new user into the list, the listUsers method will return the users list. We will call these methods in server request handlers.

export interface User {
  id: number;  name: string;
}

const users: User[] = [
  { id: 1, name: "John" },
  { id: 2, name: "Emily" },
  { id: 3, name: "Kevin" },
];

export const listUsers = (): User[] => {
  return users;
};

export const addUser = (user: User): void => {
  users.push(user);
};

Deno Server

To create a http server in Deno, we are going to use the standard http module

// index.ts
import { serve, Server } from "https://deno.land/std/http/server.ts";

const app: Server = serve({ port: 4040 });
console.log('server started on localhost:4040')

Deno allows us import modules directly from remote url, when the code been executed at first time, Deno will download those remote modules and cache them in local, so next time we can run the code without internet access. Now let's run the code by executing

deno --allow-net index.ts

Notice --allow-net flag, it will enable the network access for Deno runtime, otherwise it will be failed to initiate the server. After running, we can see the ouput

Download https://deno.land/std/http/server.ts
server started on localhost:4040

So far, we have create a very basic http server without any functions, next we will make the server to listen for http requests and make responds. Deno implements the http server in a very elegant way, the Server class implements AsyncIterable<ServerRequest> interface, which allows us to use the for await syntax to iterate over the http requests asynchronously. You can read more about AsyncIterable in this awesome article. Lets add following lines

import { serve, Server } from "https://deno.land/std/http/server.ts";

const app: Server = serve({ port: 4040 });

console.log('server started on localhost:4040');

for await (const req of app) {
  req.respond({
    status: 200,
    body: "Hello World!",
  });
}

Now we have a http server which will respond Hello World! for each incoming request! Next, we are going to define the Restful APIs, we will handle following requests:

POST /user add a new user by calling addUser in API handler
GET /users respond with a list of users
For other requests, we will respond 404 error

Let's add more logic in for await block

import { serve, Server, ServerRequest } from "https://deno.land/std/http/server.ts";
import { listUsers, addUser, User } from "./user-service.ts";
import { respondNotFound, respondWithBody, parseRequestBody } from "./utilities.ts";

const app: Server = serve({ port: 4040 });

console.log('server started on localhost:4040')

for await (const req of app) {
  switch (req.url) {
    case "/user": {
      switch (req.method) {
        case "POST": {
          const newUser = await parseRequestBody<User>(req);
          addUser(newUser);
          respondWithBody(req, true);
          break;
        }
        default:
          respondNotFound(req);
      }
      break;
    }
    case "/users": {
      switch (req.method) {
        case "GET": {
          respondWithBody<User[]>(req, listUsers());
          break;
        }
        default:
          respondNotFound(req);
      }
      break;
    }
    default:
      respondNotFound(req);
  }
}

When a request coming, we use switch to check the req.url and req.method properties, and we only handle the request which both url and method matched our API defines, otherwise we call respondNotFound to throw 404 error. As you can see, it is a pretty basic way to triage incoming requests, as the number of APIs growing, for separation of concerns, we can split the code in switch block by implementing some middlewares.

Finally, let's take a look at the request handlers, parseRequestBody will read the request body binary and convert it to json object.

const parseRequestBody = async <T>(req: ServerRequest): Promise<T> => {
  const buf = new Uint8Array(req.contentLength || 0);
  let bufSlice = buf;
  let totRead = 0;
  while (true) {
    const nread = await req.body.read(bufSlice);
    if (nread === null) break;
    totRead += nread;
    if (totRead >= req.contentLength!) break;
    bufSlice = bufSlice.subarray(nread);
  }
  const str = new TextDecoder("utf-8").decode(bufSlice);
  return JSON.parse(str) as T;
};

respondWithBody and respondNotFound are two helper methods to send API respond

const respondNotFound = (req: ServerRequest) =>
  req.respond({
    status: 404,
    body: "request not found!",
  });

const respondWithBody = <T>(req: ServerRequest, body?: T) => {
  const headers = new Headers();
  headers.append("Content-Type", "application/json");

  req.respond({
    status: 200,
    headers,
    body: JSON.stringify(body),
  });
};

Docker image

To run our app in docker, first install Deno runtime and setup the path. Finally make sure the app running with --allow-net and --allow-read flags to have correct permissions

# Dockerfile
FROM ubuntu:18.04

COPY . server/

RUN apt-get update && apt-get install -y sudo; \
    sudo apt-get update && sudo apt-get -y install curl unzip; \
    curl -fsSL https://deno.land/x/install/install.sh | sh;

WORKDIR server/

EXPOSE 4040

ENV DENO_INSTALL="/root/.deno"

ENV PATH="$DENO_INSTALL/bin:$PATH"

CMD deno run --allow-net --allow-read index.ts