Github-CI

You can test your code with Octave or Matlab on Github.

To use it, create a YML file in your .github/workflows with the content described in one of the following sections.

Warning

The example shown below is the one we use for the MOxUnit repository and may need some tweaking to work on yours.

Octave

Using the moxunit Github action

There is a "preset" github action will test your code with Ubuntu and Octave.

---
name: CI octave action

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
    push:
        branches: [master]
    pull_request:
        branches: [master]
    workflow_dispatch:

# cancel previous runs on the same branch / PR
concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true

jobs:

    unit-tests:

        runs-on: ubuntu-latest

        steps:
        # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
        -   uses: actions/checkout@v5

        # Use A Github Action to perform tests
        -   name: run unit tests and documentation tests, generate coverage report
            uses: joergbrech/moxunit-action@v1.1
            with:
                tests: tests
                src: MOxUnit
                with_coverage: true
                doc_tests: true
                cover_xml_file: coverage.xml

        -   name: Store Coverage report as artifact
            uses: actions/upload-artifact@v4
            with:
                name: coverage_xml_file
                path: coverage.xml

'Manual' set up

If you do not use the github action, you have to install octave and all the relevant toolboxes.

---
name: CI octave

# - Installs
#   - octave
#   - MOcov
# - checks out MOXunit
# - Runs tests
# - If tests pass, uploads coverage to codecov

# Controls when the action will run.
# Triggers the workflow:
#   - on push for the master branch
#   - on pull request for all branches
on:
    push:
        branches: [master]
    pull_request:
        branches: ['*']

# cancel previous runs on the same branch / PR
concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true

env:
    OCTFLAGS: --no-gui --no-window-system --silent

jobs:
    tests:
        runs-on: ubuntu-latest
        steps:
        -   name: Checkout repository
            uses: actions/checkout@v5
        -   name: Install MOcov
            run: |
                git clone https://github.com/MOcov/MOcov.git --depth 1
        -   name: Install Octave
            run: |
                sudo apt-get -y -qq update
                sudo apt-get -y install \
                  octave octave-dev
                make install
                make -C MOcov install
        -   name: Octave version
            run: octave --version
        -   name: Run tests
            run: octave $OCTFLAGS --eval "moxunit_runtests tests -verbose -with_coverage -cover MOxUnit -cover_xml_file coverage.xml; exit(double(~ans))"


        -   name: Code coverage
            uses: codecov/codecov-action@v5
            with:
                files: coverage.xml
                flags: octave
                name: codecov-octave
                fail_ci_if_error: false
                token: ${{ secrets.CODECOV_TOKEN }}

Matlab

You can test your code with Matlab with several operating systems and Matlab versions.

---
name: CI matlab

# - Installs
#   - MATLAB github action
#   - MOcov
# - checks out MOXunit
# - Runs tests
# - If tests pass, uploads coverage to codecov

# Controls when the action will run.
# Triggers the workflow:
#   - on push for the master branch
#   - on pull request for all branches
on:
    push:
        branches: [master]
    pull_request:
        branches: ['*']

# cancel previous runs on the same branch / PR
concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true

jobs:

    tests:

        strategy:
            matrix:
                # Note that some older versions (e.g R2020a, R2020b...) may not be available on all OS
                matlab_version: [R2022a, R2022b, R2023a, R2023b]
                os: [ubuntu-latest, macos-latest, windows-latest]
            fail-fast: false # Don't cancel all jobs if one fails

        runs-on: ${{ matrix.os }}

        steps:
        # use matlab-actions/setup-matlab to setup a specific version of MATLAB
        # https://github.com/matlab-actions/setup-matlab
        -   name: Install MATLAB
            uses: matlab-actions/setup-matlab@v2
            with:
                release: ${{ matrix.matlab_version }}
        -   name: Checkout repository
            uses: actions/checkout@v5
        -   name: Install MOcov
            run: |
                git clone https://github.com/MOcov/MOcov.git --depth 1

        # use matlab-actions/setup-matlab to run a matlab command
        # https://github.com/matlab-actions/setup-matlab
        -   name: Run tests
            uses: matlab-actions/run-command@v2

            # This command will call the script run_tests_gh_ci.m that will:
            # - set up moxunit
            # - add MOcov to the path
            # - run the tests
            # - exit with the result
            with:
                command: run run_tests_gh_ci;

        -   name: Code coverage
            uses: codecov/codecov-action@v5
            with:
                files: coverage.xml
                flags: ${{ matrix.os }}_matlab-${{ matrix.matlab_version }}
                name: codecov-matlab
                fail_ci_if_error: false
                token: ${{ secrets.CODECOV_TOKEN }}

Note that this wokflow calls the following script:

% Script used to run tests with github CI

IS_CI = getenv('CI');
if ~IS_CI
    error('This script should only run in continuous integration.');
end

cd('MOxUnit');
moxunit_set_path();
cd ..;
addpath(fullfile(pwd, 'MOcov', 'MOcov'));
moxunit_runtests tests -verbose -with_coverage -cover MOxUnit -cover_xml_file coverage.xml;
exit(double(~ans));

Warning

You may need to use a slightly different run_tests_gh_ci.m by updating the values for path/to/src and path/to/tests to make sure it points to where your source code and tests are.

cd('./MOxUnit/MOxUnit/');
moxunit_set_path();
cd ../..;

addpath(fullfile(pwd, 'MOcov', 'MOcov'));

moxunit_runtests path/to/tests -verbose -with_coverage -cover path/to/src -cover_xml_file coverage.xml;

exit(double(~ans))

Alternatively, the commands can be part of a CI*.yaml file. For example, CoSMoMVPA uses more or less the following configuration in CI_matlab.yml (for simplicity, the documentation tests are left out):

        steps:
        # use matlab-actions/setup-matlab to setup a specific version of MATLAB
        # https://github.com/matlab-actions/setup-matlab
        -   name: Install MATLAB
            uses: matlab-actions/setup-matlab@v2
            with:
                release: ${{ matrix.matlab_version }}

        -   name: Checkout repository
            uses: actions/checkout@v4

        -   name: Install CoSMoMVPA
            uses: matlab-actions/run-command@v2
            with:
                command: |
                    cd('mvpa')
                    cosmo_set_path()
                    savepath()

        -   name: Download MOxUnit, MOcov
            run: |
                git clone https://github.com/MOxUnit/MOxUnit.git --depth 1
                git clone https://github.com/MOcov/MOcov.git --depth 1

        -   name: Install MOxUnit, MOcov
            uses: matlab-actions/run-command@v2
            with:
                command: |
                    origin=pwd()
                    disp('Current working directory and contents:')
                    disp(origin)
                    dir
                    prefix=[origin '/']
                    cd([prefix 'MOxUnit/MOxUnit']); moxunit_set_path()
                    cd([prefix 'MOcov/MOcov']); addpath(pwd)
                    savepath()
                    disp('Path is now')
                    disp(path)

        -   name: Run unit tests (no documentation tests)
            uses: matlab-actions/run-command@v2
            with:
                command: |
                    result=moxunit_runtests('tests','-verbose', '-cover', 'mvpa', '-with_coverage', '-cover_xml_file', 'coverage.xml');
                    exit(~result);

        -   name: Code coverage
            uses: codecov/codecov-action@v5
            with:
                files: coverage.xml
                flags: ${{ matrix.os }}_matlab-${{ matrix.matlab_version }}
                name: codecov-matlab
                fail_ci_if_error: false
                token: ${{ secrets.CODECOV_TOKEN }}