matlab-tests.yml

name: matlab-tests

on:
  push:
    branches: [main]
    paths:
      - 'src/matlab/**'
      - 'tests/matlab/**'
      - 'tests/fixtures/**'
      - '.github/workflows/matlab-tests.yml'
  pull_request:
    branches: [main]
    paths:
      - 'src/matlab/**'
      - 'tests/matlab/**'
      - 'tests/fixtures/**'
      - '.github/workflows/matlab-tests.yml'

permissions:
  contents: read

# A single test job that installs MATLAB (matlab-actions/setup-matlab is
# free for public repos), clones EEGLAB plus the plugins needed for our
# Phase 1 tests, then runs tests/matlab/run_all_tests.m against the
# real-data fixture under tests/fixtures/bids_mini/. The fixture itself
# is committed to the repo (tracked, ~2-3 MB) so CI never reaches for the
# /Volumes path that only exists on the maintainer's machine.

jobs:
  matlab-tests:
    name: matlab unit + smoke tests
    runs-on: ubuntu-latest
    timeout-minutes: 45

    env:
      # Pin EEGLAB to a tagged release so CI is reproducible across runs.
      # 2026.0.0 is the latest stable as of 2026-05-12. The release bundles
      # the plugins we need for phase 1 as git submodules: EEG-BIDS,
      # clean_rawdata, dipfit, firfilt, ICLabel. Biosig (for BDF I/O) is
      # not bundled and is auto-installed by EEGLAB's plugin manager on
      # first call to pop_biosig; we trigger that explicitly below.
      EEGLAB_TAG: "2026.0.0"
      EEGLAB_DIR: ${{ github.workspace }}/.eeglab
      HBN_BIDS_ROOT: ${{ github.workspace }}/tests/fixtures/bids_mini

    steps:
      - uses: actions/checkout@v4

      # EEGLAB plus its bundled submodule plugins is >500 MB and slow to
      # clone fresh on every run. Cache it keyed on the pinned tag so a
      # version bump invalidates cleanly.
      - name: Cache EEGLAB + bundled plugins
        id: cache-eeglab
        uses: actions/cache@v4
        with:
          path: ${{ env.EEGLAB_DIR }}
          key: eeglab-${{ env.EEGLAB_TAG }}-${{ runner.os }}-v2-amica

      - name: Clone EEGLAB (cache miss)
        if: steps.cache-eeglab.outputs.cache-hit != 'true'
        run: |
          set -euo pipefail
          git clone --depth 1 --branch "$EEGLAB_TAG" --recurse-submodules \
            https://github.com/sccn/eeglab.git "$EEGLAB_DIR"

      - name: Install MPI runtime for AMICA Linux binary
        # The AMICA plugin ships amica15ex (Linux Fortran binary) which
        # dynamically links against MPICH's Fortran library libmpifort.so.12.
        # Ubuntu runners do not have it preinstalled; without it AMICA
        # fails at "error while loading shared libraries: libmpifort.so.12".
        # libmpich-dev pulls the runtime plus headers; runtime-only is also
        # fine but the -dev package resolves regardless of Ubuntu version.
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y libmpich-dev

      - uses: matlab-actions/setup-matlab@v2
        with:
          release: R2024a

      - name: Run MATLAB tests against the fixture
        uses: matlab-actions/run-command@v2
        with:
          command: |
            addpath('${{ env.EEGLAB_DIR }}');
            evalc('eeglab nogui');
            % Plugins not bundled with EEGLAB are auto-installed here via
            % plugin_askinstall (headless). Biosig is needed for BDF I/O;
            % amica is needed for Phase 2 ICA decomposition; Fieldtrip-lite
            % is required by pop_dipfit_settings for dipole fitting.
            for plugin = {'Biosig', 'amica', 'Fieldtrip-lite'}
                try
                    plugin_askinstall(plugin{1}, [], true);
                catch ME
                    warning('hbn:ci:plugin_install', ...
                        '%s auto-install failed: %s', plugin{1}, ME.message);
                end
            end
            evalc('eeglab nogui'); % re-init to pick up newly installed plugins
            addpath(genpath(fullfile(pwd, 'src', 'matlab')));
            addpath(genpath(fullfile(pwd, 'tests', 'matlab')));
            results = run_all_tests();
            disp(results);
            if any(~results.passed)
                error('hbn:ci:test_failures', ...
                    'One or more MATLAB tests failed; see table above.');
            end