GitHub Actions — Create a Testing Matrix

Using GitHub Actions are a good use-case for testing purposes. You can conveniently provision testing dependencies like databases using the Docker-based architecture. You may also test your application against a combination of versions, a so called testing matrix.

This tutorial outlines the steps to test your application against all combinations of four Node.js versions and two database versions.

GitHub Actions Series Overview

  1. Getting Started With Node.js
  2. Create a Testing Matrix
  3. Using MongoDB (Coming soon)
  4. Using Redis (Coming soon)

Create a Testing Matrix in GitHub Actions

A GitHub Actions workflow configuration must at least define one job. Let's say you have a testing job and you want to test against the latest LTS or stable Node.js releases.

The tests may also require a database, like MongoDB. Besides the Node.js versions, you also want to ensure that the app works fine with MongoDB 4.0 and 4.2.

Use a job's strategysetting and define the matrix key in the workflow's YAML file. The provide an array of versions you want to test your app against.

Here's a sample GitHub Actions workflow creating a testing matrix for Node.js and MongoDB:

name: Run tests

on: [push]

jobs:  
  testing:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x, 13.x]
        mongodb-version: [4.0, 4.2]

    steps:
    - name: Git checkout
      uses: actions/checkout@v1

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    - name: Start MongoDB v${{ matrix.node-version }}
        uses: superchargejs/mongodb-github-action@1.0.0
      with:
        mongodb-version: ${{ matrix.mongodb-version }}


    - run: npm install

    - run: npm test
      env:
        CI: true

The result in your GitHub Actions will then look like this:

GitHub Actions Testing Matrix overview

The left sidebar shows all combinations of the Node.js versions with one of the MongoDB versions.

Adding More Combinations to the Matrix

You can surely go ahead and add more combinations to the testing matrix. For example, you may add a Redis database to your test runs and append the list of Redis versions to the existing build matrix:

name: Run tests

on: [push]

jobs:  
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x, 13.x]
        mongodb-version: [4.0, 4.2]
        redis-version: [4, 5]

    steps:
    - name: Git checkout
      uses: actions/checkout@v1

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    - name: Start MongoDB v${{ matrix.node-version }}
        uses: superchargejs/mongodb-github-action@1.0.0
      with:
        mongodb-version: ${{ matrix.mongodb-version }}

    - name: Start Redis v${{ matrix.redis-version }}
      uses: superchargejs/redis-github-action@1.0.0
      with:
        redis-version: ${{ matrix.redis-version }}

    - run: npm install

    - run: npm test
      env:
        CI: true

Here’s a sample screenshot of a testing matrix using four Node.js versions, two MongoDB versions, and two Redis versions:

GitHub Actions Testing Matrix with Node.js, MongoDB, and Redis

Have fun creating a testing matrix for your project!

Testing Matrix Workflow in the GitHub Action Playground

You can find a sample workflow for a GitHub Actions testing matrix in the superchargejs/github-actions-playground repository.


Mentioned Resources

Explore the Library

Find interesting tutorials and solutions for your problems.