test.yml

name: Tests

on:
  push:
    branches: [ master, develop ]
  pull_request:
    branches: [ master, develop ]

env:
  # MATLAB batch licensing token (MathWorks pilot, license 1144083, expires
  # 2027-01-15). It licenses matlab-batch only, not the Engine API for Python,
  # so the parity tests reach MATLAB through tests/matlab/eegprep_batch_engine_serve.m
  # running inside matlab-batch (client: tests/matlab_batch_engine.py).
  MLM_LICENSE_TOKEN: ${{ secrets.MATLAB_BATCH_TOKEN }}

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  pre-commit:
    name: Pre-commit checks
    runs-on: ubuntu-22.04
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Fetch base branch
        run: |
          git fetch --no-tags origin "${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}"

      - name: Run pre-commit checks
        run: |
          ./pre-commit.py --changed-from "origin/${{ github.base_ref }}"

  lint:
    name: Ruff and ty
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          # Fetch the vendored EEGLAB reference itself, but not EEGLAB's nested
          # plugin submodules; upstream EEGLAB can temporarily point at plugin
          # commits that are unavailable for shallow GitHub Actions checkout.
          submodules: true

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Install Python 3.12
        run: |
          uv python install 3.12

      - name: Install dependencies
        run: |
          uv sync --python 3.12 --all-extras --group dev

      - name: Run Ruff lint
        run: |
          uv run --no-sync ruff check .

      - name: Run Ruff format check
        run: |
          uv run --no-sync ruff format --check .

      - name: Run ty type check
        run: |
          uv run --no-sync ty check

  test:
    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    needs: lint
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-22.04]
        python-version: ["3.12", "3.13"]
        include:
          # Test on macOS and Windows for Python 3.12 only
          - os: macos-latest
            python-version: "3.12"
          - os: windows-latest
            python-version: "3.12"

    steps:
      - uses: actions/checkout@v4
        with:
          # Fetch the vendored EEGLAB reference itself, but not EEGLAB's nested
          # plugin submodules; upstream EEGLAB can temporarily point at plugin
          # commits that are unavailable for shallow GitHub Actions checkout.
          submodules: true

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Install Python ${{ matrix.python-version }}
        run: |
          uv python install ${{ matrix.python-version }}

      - name: Install Linux GUI runtime libraries
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            libegl1 \
            libgl1 \
            libxkbcommon-x11-0 \
            libxcb-cursor0 \
            libxcb-icccm4 \
            libxcb-image0 \
            libxcb-keysyms1 \
            libxcb-randr0 \
            libxcb-render-util0 \
            libxcb-shape0 \
            libxcb-xinerama0
          echo "QT_QPA_PLATFORM=offscreen" >> "$GITHUB_ENV"

      - name: Determine MATLAB availability
        id: matlab-availability
        shell: bash
        run: |
          # Skip MATLAB on macOS and Windows, only enable on Ubuntu if token available
          if [[ "${{ matrix.os }}" == "ubuntu-22.04" ]] && [[ -n "$MLM_LICENSE_TOKEN" ]]; then
            available=true
          else
            available=false
          fi
          echo "available=${available}" >> "$GITHUB_OUTPUT"
          echo "EEGPREP_SKIP_MATLAB=1" >> "$GITHUB_ENV"

      - name: Install dependencies
        run: |
          uv sync --python ${{ matrix.python-version }} --all-extras --group dev

      - name: Set up MATLAB
        if: steps.matlab-availability.outputs.available == 'true'
        uses: matlab-actions/setup-matlab@v2
        with:
          release: R2024b
          # EEGLAB's reference functions need resample/firls/pwelch and the
          # statistics functions (tcdf, ttest, kmeans, ...).
          products: >-
            MATLAB
            Signal_Processing_Toolbox
            Statistics_and_Machine_Learning_Toolbox

      - name: Locate MATLAB root
        if: steps.matlab-availability.outputs.available == 'true'
        shell: bash
        run: |
          MATLAB_ROOT=$(python - <<'PY'
          import os
          from pathlib import Path
          tool_cache = Path(os.environ.get("RUNNER_TOOL_CACHE", "")) / "MATLAB"
          candidates = sorted(tool_cache.glob("*/x64"))
          if not candidates:
              raise SystemExit(f"No MATLAB installation found under {tool_cache}")
          print(candidates[-1])
          PY
          )
          echo "MATLAB_ROOT=$MATLAB_ROOT" >> $GITHUB_ENV
          echo "$MATLAB_ROOT/bin" >> $GITHUB_PATH

      - name: Fetch EEGLAB plugin submodules
        if: steps.matlab-availability.outputs.available == 'true'
        shell: bash
        working-directory: src/eegprep/eeglab
        run: |
          # One plugin at a time: a missing upstream commit costs one plugin, not the lane.
          for path in $(git config -f .gitmodules --get-regexp path | awk '{print $2}'); do
            if ! git submodule update --init --recursive --depth 1 -- "$path"; then
              echo "::warning title=EEGLAB plugin unavailable::Could not fetch $path; parity tests needing it will fail"
            fi
          done

      - name: Start MATLAB through matlab-batch
        id: matlab-batch
        if: steps.matlab-availability.outputs.available == 'true'
        shell: bash
        run: |
          BATCH_DIR="$RUNNER_TEMP/eegprep-matlab-batch"
          mkdir -p "$BATCH_DIR"
          nohup matlab-batch "addpath('$GITHUB_WORKSPACE/tests/matlab'); eegprep_batch_engine_serve('$BATCH_DIR')" \
            > "$BATCH_DIR/server.log" 2>&1 &
          echo $! > "$BATCH_DIR/server.pid"
          for i in $(seq 1 180); do
            [[ -f "$BATCH_DIR/ready" ]] && break
            if ! kill -0 "$(cat "$BATCH_DIR/server.pid")" 2>/dev/null; then break; fi
            sleep 2
          done
          if [[ ! -f "$BATCH_DIR/ready" ]]; then
            echo "::error title=MATLAB did not start::see server.log below"
            cat "$BATCH_DIR/server.log"
            exit 1
          fi
          echo "EEGPREP_MATLAB_BATCH_DIR=$BATCH_DIR" >> "$GITHUB_ENV"
          echo "EEGPREP_SKIP_MATLAB=0" >> "$GITHUB_ENV"

      - name: Run Python tests
        run: |
          uv run --no-sync pytest tests

      - name: Stop MATLAB
        if: always() && steps.matlab-batch.outcome == 'success'
        shell: bash
        run: |
          touch "$EEGPREP_MATLAB_BATCH_DIR/quit"
          for i in $(seq 1 30); do
            kill -0 "$(cat "$EEGPREP_MATLAB_BATCH_DIR/server.pid")" 2>/dev/null || break
            sleep 1
          done
          echo "--- matlab-batch server log (tail)"
          tail -n 60 "$EEGPREP_MATLAB_BATCH_DIR/server.log" | grep -v "$MLM_LICENSE_TOKEN" || true

      # eegprep-lean is a second distribution in this repo (ADR 0069) and the root
      # suite's `testpaths = ["tests"]` does not reach it, so without this step it ships
      # with lint as its only gate. Run from its own directory so its pyproject supplies
      # the `network` marker, with src on the path because the package is deliberately
      # not installed into this environment: it must keep working with no dependencies.
      # The network tier is excluded here and runs in lean-live.yml on a schedule, so a
      # NEMAR outage cannot turn every unrelated pull request red.
      - name: Run eegprep-lean tests
        if: always()
        working-directory: packages/eegprep-lean
        env:
          PYTHONPATH: src
        shell: bash
        run: |
          uv run --no-sync --project ../.. pytest tests -m "not network"

      # The store and window modules need the zarr extra, and skip without it, so the
      # step above proves only that they skip. This installs it so they actually run.
      # zarr is not added to the dev environment because the base install must keep
      # working with nothing present, which the step above is what verifies.
      - name: Run eegprep-lean tests with the zarr extra
        if: always()
        working-directory: packages/eegprep-lean
        # bash on every OS, as the steps above do. The default shell on windows-latest
        # is PowerShell, where a trailing backslash is not a line continuation but a
        # command to run, and `Failed to spawn: \` is the only clue you get -- printed
        # after a fully green test run.
        shell: bash
        run: |
          uv run --isolated --with 'zarr==3.4.0' --with pytest \
            python -m pytest tests -m "not network" -p no:cacheprovider

      # And the plot extra on its own, not alongside zarr. window.py imports zarr inside
      # read_window rather than at module scope precisely so this tier stands alone, and
      # a stray module-scope import would otherwise only show up in a browser, where the
      # zarr install is the awkward one.
      - name: Run eegprep-lean tests with the plot extra
        if: always()
        working-directory: packages/eegprep-lean
        shell: bash
        run: |
          uv run --isolated --with matplotlib --with pytest \
            python -m pytest tests -m "not network" -p no:cacheprovider

      # Both extras, which is the install a real session has. The three tiers above each
      # prove a tier stands alone; this one is the only place the cross-extra paths run,
      # such as reading a window and then plotting it.
      - name: Run eegprep-lean tests with both extras
        if: always()
        working-directory: packages/eegprep-lean
        shell: bash
        run: |
          uv run --isolated --with 'zarr==3.4.0' --with matplotlib --with pytest \
            python -m pytest tests -m "not network" -p no:cacheprovider

      - name: Display installed packages
        if: always()
        run: |
          uv pip list

  # No continue-on-error, so the job fails on any new failure or strict XPASS.
  # Maintainers should mark it required in branch protection. Known Python gaps
  # are individual strict xfails. GUI and slow contracts stay out because modal
  # Qt dialogs hang under offscreen Qt and the slow set exceeds this lane.
  # This lane deselects MATLAB-oracle unittest classes; they are not Python gaps.
  eeglab-python:
    name: EEGLAB Python backend
    runs-on: ubuntu-22.04
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Install Python 3.12
        run: |
          uv python install 3.12

      - name: Install Linux GUI runtime libraries
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            git-lfs \
            libegl1 \
            libgl1 \
            libxkbcommon-x11-0 \
            libxcb-cursor0 \
            libxcb-icccm4 \
            libxcb-image0 \
            libxcb-keysyms1 \
            libxcb-randr0 \
            libxcb-render-util0 \
            libxcb-shape0 \
            libxcb-xinerama0
          echo "QT_QPA_PLATFORM=offscreen" >> "$GITHUB_ENV"

      - name: Install dependencies
        run: |
          uv sync --python 3.12 --all-extras --group dev

      - name: Read pinned EEGLAB test commits
        id: pins
        run: |
          uv run --no-sync python - <<'PY'
          import os
          from tests.eeglab_tests import (
              EEGLAB_TESTS_COMMIT,
              EEGLAB_TESTS_EEGLAB_COMMIT,
              EEGLAB_TESTS_REPOSITORY,
          )
          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as handle:
              handle.write(f"suite-commit={EEGLAB_TESTS_COMMIT}\n")
              handle.write(f"eeglab-commit={EEGLAB_TESTS_EEGLAB_COMMIT}\n")
              handle.write(f"suite-repository={EEGLAB_TESTS_REPOSITORY}\n")
          PY

      - name: Checkout eeglab_tests
        env:
          SUITE_COMMIT: ${{ steps.pins.outputs.suite-commit }}
          EEGLAB_COMMIT: ${{ steps.pins.outputs.eeglab-commit }}
          SUITE_REPOSITORY: ${{ steps.pins.outputs.suite-repository }}
        run: |
          rm -rf eeglab_tests
          git init eeglab_tests
          git -C eeglab_tests remote add origin "$SUITE_REPOSITORY"
          git -C eeglab_tests fetch --depth 1 origin "$SUITE_COMMIT"
          git -C eeglab_tests checkout --detach FETCH_HEAD
          if [[ "$(git -C eeglab_tests rev-parse HEAD)" != "$SUITE_COMMIT" ]]; then
            echo "::error title=eeglab_tests pin mismatch::HEAD is not $SUITE_COMMIT"
            exit 1
          fi
          git -C eeglab_tests submodule set-url eeglab https://github.com/sccn/eeglab.git
          git -C eeglab_tests submodule sync -- eeglab
          git -C eeglab_tests submodule update --init --depth 1 -- eeglab
          if [[ "$(git -C eeglab_tests/eeglab rev-parse HEAD)" != "$EEGLAB_COMMIT" ]]; then
            echo "::error title=EEGLAB pin mismatch::suite submodule is not $EEGLAB_COMMIT"
            exit 1
          fi
          git -C eeglab_tests lfs install --local
          git -C eeglab_tests lfs pull
          # The working tree already holds the smudged files. The LFS cache copies them again.
          rm -rf eeglab_tests/.git/lfs

      - name: Run EEGLAB Python backend tests
        run: |
          uv run --no-sync pytest tests \
            --eeglab-backend python \
            --eeglab-suite-root "$GITHUB_WORKSPACE/eeglab_tests" \
            -m "parity and not slow and not gui" \
            --timeout=600 \
            --timeout-method=signal