Main Content

matlab.unittest.qualifications.Assertable class

Package: matlab.unittest.qualifications

Qualification to validate preconditions of a test

Description

The Assertable class provides a qualification to validate preconditions of a test. Apart from actions performed for failures, the Assertable class works the same as other qualification classes in the matlab.unittest.qualifications package.

Upon an assertion failure, the Assertable class informs the testing framework of the failure by throwing an AssertionFailedException object. This behavior is most useful when a failure at the assertion point renders the remainder of the current test invalid, but does not prevent proper execution of subsequent tests. Often, you use assertions to ensure that preconditions of the current test are not violated or that fixtures are set up correctly. If you cannot make the fixture teardown exception safe or restore the environment state after failure, use fatal assertions instead.

When an assertion failure is produced within a method of the TestCase class, the type of the method determines which tests are affected:

  • Test method — The framework marks the entire Test method as failed and incomplete.

  • TestMethodSetup or TestMethodTeardown method — The framework marks the Test method to run for that method instance as failed and incomplete.

  • TestClassSetup or TestClassTeardown method — The framework marks the entire test class as failed and incomplete.

Assertions let remaining tests receive coverage when preconditions are violated in a test but the state is recoverable. They prevent unnecessary failures by not performing later verifications that fail due to invalidated preconditions. If the failure does not affect the preconditions of the test or cause problems with fixture setup or teardown, use verifications, which ensure that the full test content runs.

The matlab.unittest.qualifications.Assertable class is a handle class.

Methods

expand all

Events

Event NameTriggerEvent DataEvent Attributes
AssertionFailedTriggered upon failing assertion. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

AssertionPassedTriggered upon passing assertion. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

Examples

collapse all

To test multiplication of DocPolynom objects, first add the examples folder to the search path and validate that the DocPolynom class is available to your tests. For more information about the DocPolynom class, see Representing Polynomials with Classes.

In a file in your current folder, create the DocPolynomMultiplicationTest class, which tests multiplication of DocPolynom objects. To access DocPolynom in your tests, define the addDocPolynomClassToPath method within a TestClassSetup methods block. Use a PathFixture instance within the method to add the examples folder, including the DocPolynom class definition file, to the path. Then, use an assertion to validate that the fixture has made DocPolynom available to your tests. If the assertion fails, the framework fails the Test methods without trying to run them. Otherwise, the framework runs the Test methods. Finally, the framework tears down the fixture and restores the path to its previous state.

classdef DocPolynomMultiplicationTest < matlab.unittest.TestCase
    properties
        TextToDisplay = "Equation under test: "
    end

    methods (TestClassSetup)
        function addDocPolynomClassToPath(testCase)
            import matlab.unittest.fixtures.PathFixture
            folder = fullfile(matlabroot, ...
                "help","techdoc","matlab_oop","examples");
            testCase.applyFixture(PathFixture(folder))
            testCase.assertNotEmpty(?DocPolynom)
        end
    end
end

Now, add your tests to a methods block with the Test attribute.

classdef DocPolynomMultiplicationTest < matlab.unittest.TestCase
    properties
        TextToDisplay = "Equation under test: "
    end

    methods (TestClassSetup)
        function addDocPolynomClassToPath(testCase)
            import matlab.unittest.fixtures.PathFixture
            folder = fullfile(matlabroot, ...
                "help","techdoc","matlab_oop","examples");
            testCase.applyFixture(PathFixture(folder))
            testCase.assertNotEmpty(?DocPolynom)
        end
    end

    methods (Test)
        function test1(testCase)
            p1 = DocPolynom([1 0 3]);
            p2 = DocPolynom([5 2]);
            actual = p1 * p2;
            expected = DocPolynom([5 2 15 6]);
            diagnostic = [testCase.TextToDisplay ...
                "(x^2 + 3) * (5*x + 2) = 5*x^3 + 2*x^2 + 15*x + 6"];
            testCase.verifyEqual(actual,expected,diagnostic)
        end

        function test2(testCase)
            p1 = DocPolynom([1 4]);
            p2 = DocPolynom([2 3]);
            p3 = DocPolynom([1 0 -1]);
            actual = p1 * p2 * p3;
            expected = DocPolynom([2 11 10 -11 -12]);
            diagnostic = [testCase.TextToDisplay ...
                "(x + 4) * (2*x + 3) * (x^2 - 1) = 2*x^4 + 11*x^3 + 10*x^2 - 11*x - 12"];
            testCase.verifyEqual(actual,expected,diagnostic)
        end
    end
end

Run the tests in the DocPolynomMultiplicationTest class. In this example, both of the tests pass.

runtests("DocPolynomMultiplicationTest")
Running DocPolynomMultiplicationTest
..
Done DocPolynomMultiplicationTest
__________
ans = 
  1×2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 0 Failed, 0 Incomplete.
   0.38698 seconds testing time.

More About

expand all

Introduced in R2013a