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

Matrix Combinations

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

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.

References

• GitHub Actions Documentation
• actions/setup-node
• actions/upload-artifact