Run your MATLAB tests on every commit

Install RunMat in one step and run runmat test. Test results come out as JUnit and coverage as Cobertura or LCOV, formats most CI systems can show in a pull request. Use it on a runner or in the official container image.

See the example repository

.github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: runmat-org/setup-runmat@v1
- run: runmat test

What you get in CI

Nothing to activate

RunMat checks no license server and needs no token or sign-in. A new runner can run tests as soon as the binary is installed.

Results in the pull request

JUnit, TAP and JSON results, and LCOV, Cobertura and HTML coverage. A pull request shows which test failed and which lines ran.

One binary that starts quickly

Install is one download, cached between runs, and a short script runs in under a tenth of a second.

Pinned packages

runmat.lock pins every package version. --locked fails when the lock is out of date, and --frozen fails if the job tries to reach the network.

Add it to your pipeline

The workflow above runs your tests. A full setup usually adds four things, each one step in the file:

  1. 1

    Run tests on Linux, macOS and Windows in a matrix

    One job definition runs once per operating system, so a platform-specific failure shows up before release.

  2. 2

    Check the code first

    runmat check finds errors without running anything, so a typo fails in seconds.

  3. 3

    Pin packages

    If the project uses packages, runmat --locked package fetch fails the build when runmat.lock is out of date. Leave it out if there are none.

  4. 4

    Keep the results

    --report junit and --coverage write test results and coverage to reports/, and a reporting step shows them in the pull request.

.github/workflows/ci.yml
name: CI
on: [push, pull_request]
permissions:
contents: read
checks: write
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v5
- uses: runmat-org/setup-runmat@v1
- run: runmat --locked package fetch
- run: runmat check src/checkBeam.m
- run: >-
runmat test --report junit --report-dir reports
--coverage --coverage-format cobertura
- uses: mikepenz/action-junit-report@v5
if: always()
with:
report_paths: reports/**/test-results.xml

setup-runmat installs the latest release (or the version you pin), verifies its SHA-256, adds it to PATH and caches packages keyed on runmat.lock.

How to use runmat test

runmat test finds script-based, function-based and class-based MATLAB tests and runs each test file in its own process. These are the options you are most likely to need.

Run every test in the projectrunmat test
Run one folder or filerunmat test tests/solver
Run tests whose name matchesrunmat test --name convergence
Run only tests with a tagrunmat test --tag fast
See what would run, without running itrunmat test --list
Write JUnit results for CIrunmat test --report junit --report-dir reports
Measure coveragerunmat test --coverage --coverage-format lcov
Split the suite across 4 CI jobs (this is job 1)runmat test --shard-index 1 --shard-count 4
Run test groups in parallel on one machinerunmat test --jobs 4
Stop a test that hangsrunmat test --timeout-ms 60000
Run the tests on your own clusterrunmat test --cluster CLUSTER_ID

FAQ

01Does the runner need a license server, token or account?

No. There is no license check, so there is no CI secret to store.

02Which CI systems does it work with?

Any that can run a Linux, macOS or Windows command. GitHub Actions has the setup-runmat action; GitLab, Jenkins, Buildkite and others use the official image or the install script.

RunMat in containers

03Do my existing MATLAB tests run?

Script-based, function-based and class-based tests written for MATLAB's unit test framework run with runmat test. Run runmat test --list first to see what it discovers.

04How do I pin the RunMat version?

Set version on setup-runmat, or use a versioned image tag such as runmat/runmat:0.6.3. Package versions are pinned by runmat.lock.

setup-runmat inputs