Improve tests #28
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |