Node Packages - Unit Tests and Github Actions (Part - II)

[nakamume]

Checkout Issue I, where I covered writing a very simple node package and publishing that to github packages.

In this post, we'll build on top of that. Rewriting the whole thing again, we'll add support for unit tests and github actions to run our tests and publish our package.

To avoid distractions, I intentionally didn’t put the source code in last blog. You can find it here. Let's get started.

Adding unit tests

1. To keep our code more manageable, let's create two new folders src and test. BTW, I've named my repo rei-node-package, rei(例) is Japanese for example.

   cd <your-repo>
   mkdir src test
   

   src to hold our package's core code and test for . . . well, you might have guessed.

2. Move our source code to src folder (we have index.js file only 😊).

   mv index.js src
   

3. We'll use jest JS testing framework. At this point our package.json should be changed to

   {
    "name": "@<SCOPE>/rei-node-package",
    "version": "1.0.0",
    "description": "This is an example node package",
    "repository": "https://github.com/<SCOPE>/rei-node-package",
    "main": "src/index.js",
    "publishConfig": {
      "registry": "https://npm.pkg.github.com"
    },
    "devDependencies": {
      "jest": "^26.6.3"
    },
    "scripts": {
      "test": "jest"
    }
   }
   

   Notice the changes we made? We have changed main, added jest dependency(dev dependency) and using jest for testing.

4. Next, let's add a test to test our very complex 😉 rei function. In test/index.test.js file

   const rei = require('../src/index')
   
   describe("rei package", () => {
    it("return: You have succesfull installed and ran lionbridgeai's rei package", () => {
      expect(rei()).toEqual("You have succesfull installed and ran lionbridgeai's rei package")
    })
   })
   

5. Ready to run the tests? First do a npm install to install dependencies (jest) and then npm test.

   npm test
   
   > @nakamorg/rei-node-package@0.1.0 test
   > jest
   
   Browserslist: caniuse-lite is outdated. Please run:
   npx browserslist@latest --update-db
   
   Why you should do it regularly:
   https://github.com/browserslist/browserslist#browsers-data-updating
   PASS test/index.test.js
     rei package
       ✓ return: You have succesfull installed and ran nakamorg's rei package (3 ms)
   
   Test Suites: 1 passed, 1 total
   Tests:       1 passed, 1 total
   Snapshots:   0 total
   Time:        1.05 s
   Ran all test suites.
   

   Hoping all your tests pass 🤞🏽

6. Let's publish our new version.

   npm version major # you might have to commit your existing changes first
   npm publish       # check part 1 of this blog series on how to publish
   

Using Github Actions

In this section we'll explore how to run tests whenever someone creates a PR to master for your package. And how to publish on every push to master.

Github Actions reads instructions from workflow(.github/workflows) files and runs them. A workflow to run tests on every PR for master would look like(let's name it .github/workflows/build.yml)

name: build

on:
  pull_request:
    branches:
    - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 16
      - run: npm install
      - run: npm test

Now, whenever someone creates a PR, github actions would run the required tests and send the checks back to PR. It would be a very helpful input in deciding whether to merge the PR or not.

Next, let's add a workflow to publish our package whenever a push is made to master (either directly or a PR to master is merged). Workflow file (let's name it .github/workflows/publish.yml) would be like

name: publish

on:
  push:
    branches:
    - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 16
      - run: npm install
      - run: npm test
  publish:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 16
          registry-url: https://npm.pkg.github.com/
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

Note that this workflow has two jobs build and publish. build job runs the tests(same as build.yml workflow we saw earlier) and publish simply publishes our package to github packages. Note the NODE_AUTH_TOKEN env var, it's set to GITHUB_TOKEN secret. This secret is automatically created for your repo and has necessary permissions to publish a package. Don't forget to update your package version whenever you create a PR or push to master. Or you can update the version while running publish workflow(take it as an exercise 😉).