Merge pull request #211 from gibbonCode/ci-test-install

Add CI testing infrastructure

Author: Kevin-Mattheus-Moerman

.github/workflows/run_tests.yml

@@ -0,0 +1,58 @@
+name: Run Tests
+
+on:
+  push:
+    paths:
+      - lib/**
+      - tests/**
+      - installGibbon.m
+      - .github/workflows/run_tests.yml
+  pull_request:
+    paths:
+      - lib/**
+      - tests/**
+      - installGibbon.m
+      - .github/workflows/run_tests.yml
+
+jobs:
+  my-job:
+    name: Run MATLAB Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Set up products
+        uses: matlab-actions/setup-matlab@v3
+        with:
+          release: latest
+          cache: true
+          products: >
+            Optimization_Toolbox
+            Symbolic_Math_Toolbox
+            Image_Processing_Toolbox
+            Curve_Fitting_Toolbox
+
+      - name: Install GIBBON
+        uses: matlab-actions/run-command@v3
+        with:
+          command: installGibbon
+
+      - name: Run tests
+        uses: matlab-actions/run-tests@v3
+        with:
+          source-folder: lib
+          select-by-folder: tests
+          strict: false
+          test-results-html: test-results
+          code-coverage-cobertura: code-coverage/coverage.xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: code-coverage/coverage.xml
+          flags: matlab
+          fail_ci_if_error: false

CONTRIBUTING.md

@@ -24,7 +24,13 @@ gpublish HELP_functionName
 This will "publish" the documentation in the form of HTML files in the `GIBBON/docs/html` folder. The content there will then be automatically added to, and rendered on, the website when the website is updated. 
 
 ## Testing
-For the moment the DEMO_ and HELP_ files may serves as a test suite. The `testGibbon` function can be used to run (and "publish" HTML if needed) these tests/demos automatically. 
+
+New code should define well-structured [unit tests](https://www.mathworks.com/help/matlab/matlab_prog/ways-to-write-unit-tests.html), stored in the `tests` directory and labeled `TEST_functionName.m`. These will
+be picked up by our CI pipeline and run on a remote GitHub runner, so make sure to keep your tests small and portable.
+
+If you are new to unit tests, the examples `functionTestTemplate` and `ClassTestTemplate` might be a good starting point.
+
+Unfortunately, the bulk of the code does not yet have structured tests. The `DEMO_*` and `HELP_*` files may serve as a more extensive test suite. The `testGibbon` function can be used to run (and "publish" HTML if needed) these tests/demos automatically.
 
 ## Pull requests
 - Try not to pollute your pull request with unintended changes – keep them simple and small. If possible, squash your commits.

README.md

@@ -1,3 +1,5 @@
+[![tests](https://github.com/gibbonCode/GIBBON/actions/workflows/run_tests.yml/badge.svg?event=push)](https://github.com/gibbonCode/GIBBON/actions/workflows/run_tests.yml)
+[![codecov](https://codecov.io/github/gibbonCode/GIBBON/graph/badge.svg?token=J0W2ZBWP3L)](https://codecov.io/github/gibbonCode/GIBBON)
 
 <img src="docs/img/logos/gibbonLogoBanner_1018x300.png" href="https://gibboncode.org" alt="GIBBON" width="100%">   
 

installGibbon.m

@@ -110,6 +110,13 @@ function installGibbon(interactive, FEBioPath, profileNameVCW)
         disp(opts);
     end
 
+    %% Check for Toolboxes
+    requirements = {'Image Processing Toolbox', 'Statistics and Machine Learning Toolbox', 'Symbolic Math Toolbox', 'Curve Fitting Toolbox', 'Parallel Computing Toolbox'};
+    fulfilled = ismember(requirements, {ver().Name});
+    if ~all(fulfilled)
+        warning('GIBBON:ToolboxCheck', 'Some required toolboxes might be missing:\n\t%s', strjoin(requirements(~fulfilled),'\n\t'));
+    end
+
     %% Unzip compressed data
     updateStatus('Unzipping compressed data');
 

tests/ClassTestTemplate.m

@@ -0,0 +1,85 @@
+classdef ClassTestTemplate < matlab.unittest.TestCase
+% Example of class-based unit tests. See:
+% https://www.mathworks.com/help/matlab/matlab_prog/class-based-unit-tests.html
+% https://www.mathworks.com/help/matlab/matlab_prog/ways-to-write-unit-tests.html
+%
+% If you're new to tests, you may want to start with function-based unit tests
+% See also: functionTestTemplate
+
+    %% (Optional) Test Parameters
+    % TestParameter properties are used to define parameterized tests,
+    % i.e. "variations" of a single test method, ran with different inputs.
+    % See the 'testParameterizedMultiply' method below, and:
+    % https://www.mathworks.com/help/matlab/matlab_prog/use-parameters-in-class-based-tests.html
+
+    properties (TestParameter)
+        b = {3,4}
+        a = struct('one', 1, 'two', 2)  % use a struct to name parameter values 
+    end
+
+    %% (Optional) Custom Properties
+    % Define your own properties to pass data between fixtures and test methods.
+
+    properties
+        TempDir  % used to store a temporary directory for the tests
+        oldPath  % used to store the current directory before each test
+    end
+
+    %% (Optional) Fixtures
+    % Fixtures run before and after tests, to do preparation or cleanup.
+
+    methods (TestClassSetup)
+        function setupOnce(testCase)
+            % Runs once for the whole class.
+            % Use for expensive one-time setup (temp dirs, large test data, etc.).
+            tempDir = tempname;
+            mkdir(tempDir);
+            testCase.TempDir = tempDir;
+        end
+    end
+
+    methods (TestClassTeardown)
+        function teardownOnce(testCase)
+            % Runs once after all tests in this class.
+            if isfolder(testCase.TempDir)
+                rmdir(testCase.TempDir, 's');
+            end
+        end
+    end
+
+    methods (TestMethodSetup)
+        function setup(testCase)
+            % Runs before each test method.
+            testCase.oldPath = pwd;
+            cd(testCase.TempDir);
+        end
+    end
+
+    methods (TestMethodTeardown)
+        function teardown(testCase)
+            % Runs after each test method.
+            cd(testCase.oldPath);
+        end
+    end
+
+    %% Test Methods
+
+    methods (Test)
+        function testWritingFilesWorks(testCase)
+  
+            writelines('Class tests are great!', 'test.txt');
+            testCase.verifyTrue(isfile('test.txt'));
+        end
+
+        function testParameterizedMultiply(testCase, a, b)
+        % a, b will take the values defined in the TestParameter properties above
+
+            c = multiply(a,b);
+            testCase.assertEqual(c, a*b);
+        end
+    end
+end
+
+function c = multiply(a, b)
+    c = a*b;
+end

tests/TEST_patchArea.m

@@ -0,0 +1,68 @@
+classdef TEST_patchArea < matlab.unittest.TestCase
+    properties (TestParameter)
+        geom = testGeometries();
+    end
+
+    methods (Test)
+        function testPatchArea(testCase, geom)
+            areaEstimate = sum(patchArea(geom.F, geom.V), 'all');
+            testCase.verifyEqual(areaEstimate, geom.areaTotalTrue, 'RelTol', 3.5e-3);
+        end
+    end
+end
+
+function C = testGeometries()
+
+    C = struct();
+    for idx = 1:6
+    switch idx
+    case 1 % Circle
+        name = 'circle';
+        r = 1;
+        n = 250;
+        t = linspace(-pi, pi, n)';
+        t = t(1:end-1);
+        V = [r*cos(t) r*sin(t) zeros(size(t))];
+        F = 1:size(V,1);
+        areaTotalTrue = pi*r^2;
+    case 2 % Single element square 1x1
+        name = 'singleElementSquare';
+        V = [0 0 0; 1 0 0; 0 1 0; 1 1 0];
+        F = [1 2 4 3];
+        areaTotalTrue = 1;
+    case 3 % Multi-element square rotated 1x1
+        name = 'multiElementSquareRotated';
+        V1 = 0.5*[-1 -1; -1 1; 1 1; 1 -1];
+        regionCell = {V1};
+        plotOn = 0;
+        pointSpacing = 0.1;
+        resampleCurveOpt = 1;
+        [F,V] = regionTriMesh2D(regionCell, pointSpacing, resampleCurveOpt, plotOn);
+        V(:,3) = 0;
+        R = euler2DCM([-0.25*pi 0.25*pi 0]);
+        V = V*R;
+        areaTotalTrue = 1;
+    case 4 % Cube
+        name = 'cube';
+        [V,F] = platonic_solid(2);
+        V = V./max(V(:))/2;
+        areaTotalTrue = 6;
+    case 5 % Sphere quads
+        name = 'sphereQuads';
+        r = 1;
+        n = 4;
+        [F,V] = quadSphere(n, r, 2);
+        areaTotalTrue = 4*pi*r^2;
+    case 6 % Sphere triangles
+        name = 'sphereTriangles';
+        r = 1;
+        n = 4;
+        [F,V] = geoSphere(n, r);
+        areaTotalTrue = 4*pi*r^2;
+    end
+    
+    C.(name).F = F;
+    C.(name).V = V;
+    C.(name).areaTotalTrue = areaTotalTrue;
+    end
+end

tests/TEST_patchVolume.m

@@ -0,0 +1,88 @@
+classdef TEST_patchVolume < matlab.unittest.TestCase
+    properties (TestParameter)
+        geom = testGeometries();
+    end
+    methods (Test)
+        function testPatchVolume(testCase, geom)
+            makeAbsolute = 0;
+            volEst=patchVolume(geom.F, geom.V, makeAbsolute);
+            testCase.verifyEqual(volEst, geom.volTotalTrue, 'RelTol', 3.5e-3);
+        end
+    end
+end
+
+function C = testGeometries()
+
+    C = struct();
+    for idx = 1:9
+        switch idx   
+        case 1 
+            name = 'trianglulatedSphere';
+            r=2;
+            ns=5;
+            [F,V]=geoSphere(ns,r);         
+            volTotalTrue=4/3*pi*r^3; %True theoretical volume
+        case 2 %Trianglulated sphere
+            name = 'quadrangulatedSphere';
+            r=2;
+            ns=6;
+            [F,V]=quadSphere(ns,r);         
+            volTotalTrue=4/3*pi*r^3; %True theoretical volume
+
+            %Shift randomly to create non-zero centred patch data
+            V=V+10.*randn(1,3);
+        case 3
+            name = 'triangulatedTorus';
+            r=1; %Sphere radius
+            R=2; %Central radius
+            nr=76;
+            nc=150;
+            [F,V]=patchTorus(r,nr,R,nc,'tri');
+            volTotalTrue=2*pi^2*r*R; %True theoretical volume
+        case 4
+            name = 'quadrangulatedTorus';
+            r=1; %Sphere radius
+            R=2; %Central radius
+            nr=76;
+            nc=150;
+            [F,V]=patchTorus(r,nr,R,nc,'quad');
+            volTotalTrue=2*pi^2*r*R; %True theoretical volume
+        case 5
+            name = 'honeycombTorus';
+            r=1; %Sphere radius
+            R=2; %Central radius        
+            nr=76;
+            nc=150;
+            [F,V]=patchTorus(r,nr,R,nc,'honey');
+            volTotalTrue=2*pi^2*r*R; %True theoretical volume
+        case 6
+            name = 'triangulatedBox';
+            boxDim=[5 2 1];
+            pointSpacing=1;
+            [F,V]=triBox(boxDim,pointSpacing); 
+            volTotalTrue=prod(boxDim); %True theoretical volume
+        case 7
+            name = 'quadrangulatedBox';
+            boxDim=[5 2 1];
+            [F,V]=quadBox(boxDim,[5 2 1]);
+            volTotalTrue=prod(boxDim); %True theoretical volume
+        case 8
+            name = 'mixedMeshOfPentahedraAndHexahedra';
+            r=2;
+            ns=5;
+            [Ft,Vt]=geoSphere(ns,r);
+            [V,F]=patch_dual(Vt,Ft);        
+            volTotalTrue=4/3*pi*r^3; %True theoretical volume
+        case 9
+            name = 'trianglulatedSphereWithFlippedFaces';
+            r=2;
+            ns=5;
+            [F,V]=geoSphere(ns,r);         
+            F=fliplr(F);
+            volTotalTrue=-4/3*pi*r^3; %True theoretical volume
+        end
+        C.(name).F = F;
+        C.(name).V = V;
+        C.(name).volTotalTrue = volTotalTrue;
+    end
+end