ci.yml

name: MATLAB CI and Pages

# WORKFLOW OVERVIEW
# ==================
# This workflow implements a multi-release MATLAB testing and documentation pipeline.
# It tests courseware code across multiple MATLAB releases in parallel, validates results,
# generates a status badge, and deploys documentation to GitHub Pages.
#
# ARCHITECTURE:
#   Phase 1 - test-matrix (parallel): Run tests independently for each MATLAB release
#   Phase 2 - report-and-deploy (sequential): Merge artifacts, validate, generate badge, deploy
#
# KEY FILES:
#   - buildfile.m              : Defines build tasks (testing, validation, badge generation)
#   - SoftwareTests/CoursewareSmokeTests.m     : Tests core courseware scripts
#   - SoftwareTests/FunctionTests.m            : Placeholder for development function tests
#   - SoftwareTests/CrossReleaseTestResults.m : Validates all releases passed (gate for badge)
#
# ARTIFACT FLOW:
#   1. test-matrix job (runs for each MATLAB release R2025a, R2025b):
#      $ buildtool test
#      -> public/R2025a/CoursewareSmokeTests.mat, FunctionTests.mat, etc.
#      -> Upload artifacts: test-results-R2025a, test-results-R2025b
#
#   2. report-and-deploy job (runs once, after test-matrix completes):
#      $ Download and merge all test-results-* artifacts into public/
#      $ buildtool report  (runs report:validate, report:badge, report:link tasks)
#      -> SoftwareTests/CrossReleaseTestResults.m validates all releases passed
#      -> createBadge() generates public/TestedWith.json (shields.io format)
#      -> linkResultArtifactPathsInReportIndex() wraps test result links in HTML
#      -> Deploy public/ to GitHub Pages
#
# CUSTOMIZATION:
#   To change tested MATLAB releases: Edit matrix.Releases list (line 29)
#   To add/remove products: Edit MATLAB_PRODUCTS env variable (line 28)
#   To change deploy trigger: Edit 'on' workflow events (lines 3-7)
#
# FOR YOUR OWN COURSEWARE:
#   1. Copy buildfile.m and SoftwareTests/ structure to your repo
#   2. Create SoftwareTests/CoursewareSmokeTests.m with your own test suite
#      (reference: https://www.mathworks.com/help/matlab/matlab_prog/write-simple-test-suite.html)
#   3. Update .github/workflows/ci.yml with your product list and release matrix
#   4. Push to your release branch and monitor GitHub Actions
#
# TROUBLESHOOTING:
#   If tests fail in CI but pass locally:
#     - Check version(-release) output matches your installed MATLAB
#     - Verify all dependencies (products) are listed in MATLAB_PRODUCTS
#     - Review public/index.html report for detailed test output
#   If badge generation fails:
#     - Ensure SoftwareTests/CrossReleaseTestResults.m can find all release artifacts
#     - Check public/CrossReleaseTestResults.mat for missing or empty result variables

# Controls when the action will run.
on:
  push:
    branches: [ release ]
  pull_request:
    branches: [ release ]
  workflow_dispatch:

# Add permission to write GitHub pages
permissions:
  contents: write
  pages: write
  id-token: write

# Cancel older in-progress runs on the same ref to save CI time.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test-matrix:
    name: Test on ${{ matrix.Releases }}
    strategy:
      fail-fast: false
      matrix:
        Releases: [R2025b, R2026a]
    runs-on: ubuntu-latest
    env:
      MATLAB_PRODUCTS: Symbolic_Math_Toolbox
      LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libstdc++.so.6
    steps:
      # Checks-out your repository
      - uses: actions/checkout@v6

      # Sets up a display server
      - name: Start display server
        if: ${{ always() }}
        run: |
          sudo apt-get update
          sudo apt-get install -y xvfb
          Xvfb :99 &
          echo "DISPLAY=:99" >> $GITHUB_ENV

      # Sets up MATLAB
      - name: Setup MATLAB ${{ matrix.Releases }}
        uses: matlab-actions/setup-matlab@v3
        with:
          release: ${{ matrix.Releases }}
          products: ${{ env.MATLAB_PRODUCTS }}
          cache: true

      # Run aggregated test task from buildfile.m.
      - name: Run buildtool test
        uses: matlab-actions/run-build@v3
        with:
          tasks: test
          build-options: -continueOnFailure

      # Upload only files required by buildtool report/pages to reduce artifact size.
      - name: Upload test results artifact
        if: ${{ always() }}
        uses: actions/upload-artifact@v6
        with:
          name: ${{ matrix.Releases }}
          path: |
            ./public/${{ matrix.Releases }}/
          overwrite: true
          retention-days: 7

  report-and-deploy:
    name: Build badge and deploy reports
    if: ${{ always() }}
    needs: [test-matrix]
    runs-on: ubuntu-latest
    steps:

      # Checks-out your repository
      - uses: actions/checkout@v6

      # GitHub-hosted jobs are isolated; MATLAB install from test-matrix cannot be reused here.
      # Keep this setup minimal (no extra products) and use artifacts from matrix jobs.

      # Sets latest MATLAB for report task (no toolbox list needed).
      - name: Setup MATLAB latest
        uses: matlab-actions/setup-matlab@v3
        with:
          release: latest
          cache: true

      # Download the test results from artifact
      - name: Download All TestResults
        uses: actions/download-artifact@v8
        with:
          path: public
          pattern: R20*
          merge-multiple: false

      # Aggregate test reports and generate badge via buildfile.
      - name: Run buildtool report
        uses: matlab-actions/run-build@v3
        with:
          tasks: report
          build-options: -continueOnFailure

      # Upload the badge as artifact
      - name: Upload Badge
        if: ${{ always() }}
        uses: actions/upload-artifact@v6
        with:
          name: Badge-Artifact
          path: ./public/TestedWith.json
          overwrite: true

      # Deploy reports to GitHub pages
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4