Run Unit Testing using Matrix Strategy

Leverage GitHub Actions’ matrix strategy to run your unit tests across multiple Node.js versions and operating systems in parallel. This ensures comprehensive coverage and compatibility without duplicating workflows.

Why Use a Matrix Strategy?

Parallel execution for faster feedback
Broad runtime and OS compatibility
Simplified maintenance by centralizing variations

1. Defining the Matrix

First, configure your workflow triggers, environment variables, and a basic matrix under the unit-testing job. Here’s an example that hard-codes the runner and Node.js version:

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - 'feature/*'

env:
  MONGO_URI: 'mongodb+srv://supercluster.d83jj.mongodb.net/superData'
  MONGO_USERNAME: ${{ vars.MONGO_USERNAME }}
  MONGO_PASSWORD: ${{ secrets.MONGO_PASSWORD }}

jobs:
  unit-testing:
    name: Unit Testing
    strategy:
      matrix:
        nodejs_version: [18, 19, 20]
        operating_system: [ubuntu-latest, macos-latest]
      exclude:
        - nodejs_version: 18
          operating_system: macos-latest
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Node.js 18
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install Dependencies
        run: npm install

We define three Node.js versions and two OS targets. The exclude block omits Node.js 18 on macOS.

Matrix Combinations

Node.js Version	Operating System	Included?
18	ubuntu-latest	✔️
18	macos-latest	❌
19	ubuntu-latest	✔️
19	macos-latest	✔️
20	ubuntu-latest	✔️
20	macos-latest	✔️

2. Referencing Matrix Variables

Next, update runs-on and the Node.js setup step to dynamically reference your matrix values. This allows every job to automatically select the correct OS and Node.js version:

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - 'feature/*'

env:
  MONGO_URI: 'mongodb+srv://supercluster.d83jj.mongodb.net/superData'
  MONGO_USERNAME: ${{ vars.MONGO_USERNAME }}
  MONGO_PASSWORD: ${{ secrets.MONGO_PASSWORD }}

jobs:
  unit-testing:
    name: Unit Testing
    strategy:
      matrix:
        nodejs_version: [18, 19, 20]
        operating_system: [ubuntu-latest, macos-latest]
      exclude:
        - nodejs_version: 18
          operating_system: macos-latest
    runs-on: ${{ matrix.operating_system }}
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.nodejs_version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.nodejs_version }}

      - name: Install Dependencies
        run: npm install

      - name: Run Unit Tests
        run: npm test

      - name: Archive Test Results
        uses: actions/upload-artifact@v3

Use ${{ matrix.nodejs_version }} and ${{ matrix.operating_system }} to automatically pick each configured combination.

For more details, see GitHub Actions Matrix Strategy.

3. Running and Observing the Workflow

Commit and push your changes with a descriptive message, for example:

git add .github/workflows/unit-tests.yml
git commit -m "chore: test on multiple OS using matrix strategy"
git push

GitHub Actions will spawn parallel jobs for each matrix entry (excluding the defined pair). Inspect each job under the Actions tab to view logs and artifacts.

The image shows a GitHub Actions workflow interface, displaying a "test on multiple os using matrix" job in progress, with unit testing being conducted on various operating systems.

The image shows a GitHub Actions workflow interface with unit testing jobs for different operating systems, including Ubuntu and macOS. The highlighted job is "Unit Testing (20, ubuntu-latest)" which has succeeded.

Introduction

Continuous Integration with GitHub Actions

Continuous Deployment with GitHub Actions

Reusable Workflows and Reporting

Custom Actions

Self Hosted Runner

Security Guide

GitHub Actions - Core Concepts

Run Unit Testing using Matrix Strategy

Why Use a Matrix Strategy?

1. Defining the Matrix

Matrix Combinations

2. Referencing Matrix Variables

3. Running and Observing the Workflow

References

Watch Video

​Why Use a Matrix Strategy?

​1. Defining the Matrix

​Matrix Combinations

​2. Referencing Matrix Variables

​3. Running and Observing the Workflow

​References

Watch Video

Why Use a Matrix Strategy?

1. Defining the Matrix

Matrix Combinations

2. Referencing Matrix Variables

3. Running and Observing the Workflow

References