% Unit Testing Framework for MATLAB.
%
% See also TESTCASE, TESTSUITE, GUITESTRUNNER, TEXTTESTRUNNER,
% DYNAMICTESTSUITE.
%
% A note about objects and classes in MATLAB:
%
% If you haven't done so, please read the MATLAB help documentation on
% "MATLAB Classes and Object Oriented Programming". All classes in
% mlunit_2008a use the new single file classdef syntax, and all are handle
% (not value) classes. Your test classes must also use this syntax - you
% cannot subclass one of the new classes using the old style class
% directory classes.
%
%
% QUICKSTART
% ----------
%
% Using mlunit_2008a is very simple and follows the pattern of other xUnit
% frameworks (at least those in OO languages). If you are already familiar
% with one of these frameworks, then you can probably get started right
% away by using the files in the samples directory as templates, then
% running one of the test runners (see class documentation).
%
%
% CREATING TESTS
% --------------
%
% To create tests, you create a test class by subclassing TestCase and
% adding test methods. Test methods are any methods with names beginning
% with "test". The testing framework automatically finds and runs these
% methods for you.
%
% Within your test methods you can run whatever arbitrary code you wish,
% and validate results using one of the inherited assert methods described
% below. In the signatures for each of these I am omitting the first
% parameter (the object on which the method is being called).
%
% assert(expr, [fail_message])
% Succeeds if expr is true, otherwise records a failure.
%
% assertEquals(expected, actual, [fail_message])
% Succeeds if actual equals expected, otherwise records a failure.
% Equality is determined using the MATLAB isequal() function, and works
% on pretty much any MATLAB types.
%
% assertNotEquals(a, b, [fail_message])
% Suceeds where assertEquals would fail, and vice versa.
%
% The optional fail message in each of these methods is added to the test
% report if the assert fails.
%
% You can also run code that throws a catchable exception (MException); the
% test framework will catch exceptions and record them as errors. You can
% also perform your own custom validations, and record errors using the
% fail() method:
%
% fail(message)
% Always records a failure.
%
% Setup/teardown
% --------------
%
% Sometimes it may be desirable to initialize some object under test with a
% known starting state. For instance, constructing a particular matrix
% that will get changed during testing. Another example may be opening a
% particular file.
%
% Rather than performing this operation yourself in each test method, you
% can override the inherited setUp method to do it for you. Add properties
% to your test class to hold the object you are setting up (the matrix,
% file handle, etc.) The setUp method is automatically run before every
% invocation of a test method (in case this isn't clear, if your class has
% 10 test methods, setUp will get called 10 times, once before each test
% method.
%
% In the same vein, tearDown is called after every test method, and can be
% used to clean up as necessary from your tests (e.g., closing a file
% handle).
%
%
% GROUPING TESTS INTO SUITES
% --------------------------
%
% You can group multiple test cases for convenience in running large sets
% of tests by creating a test suite. To create a test suite, simply
% subclass TestSuite and define the suite() method. The suite method can
% contain any code you wish, but must return a cell array of strings, each
% of which names a test case or test suite class to run as part of the
% suite.
%
% Note that adding test suites to test suites allows you to construct
% hierarchical test suites, which are reflected in the test runner reports.
%
%
% RUNNING TESTS
% -------------
%
% Running tests is performed using one of the supplied test runners. At
% this time, there are two test runners, described below. For most users,
% unless running without the MATLAB gui (-nodisplay), the GuiTestRunner is
% the best choice.
%
% GuiTestRunner
% -------------
%
% The GuiTestRunner class provides (duh) a
% graphical user interface for running tests. The interface is pretty
% minimal and should mostly be self- explanatory, but here is a brief
% summary of the interface components: To launch the interface, simply call
% the class constructor:
%
% >> GuiTestRunner
%
% Add Tests button - the icon looks like a document with a small "plus"
% icon in
% the corner, and this is the only button enabled when the gui first
% comes up. Add Tests is somewhat of a misnomer, because using it
% replaces any tests you had previously added. Clicking on the button
% brings up a file open dialog, in which you can select the test case
% and/or test suite classes you wish to run. The dialog allows multiple
% selections.
%
% Run Tests button - starts a run of all loaded test cases and suites.
%
% Stop Tests button - requests the stopping of the test run. The test run
% will continue through the end of the test method currently being run,
% and then stop.
%
% Progress bar - provides a visual indicator of the percentage of tests
% that
% have already been run. The bar remains green as long as no test
% failures have been recorded. At the first failure, the bar turns red.
%
% Tests pane - provides a tree-structured view of your test suites, test
% cases,
% and test methods. After tests have been run, the icons in the view
% reflect the success or failure of each item. Selecting a failed test
% method (click on it) will populate the Error messages pane.
%
% Error messages pane - provides the error message from the selected test,
% and
% a stack trace. The stack trace is most useful when an exception occurs
% in some called function. Selecting any line in the pane enables the Go
% To Code button.
%
% Go To Code... button - sorry, couldn't find an icon that made sense for
% this
% function. Clicking this button will open a MATLAB code editor to the
% failed test method or selected stack location.
%
% TextTestRunner
% --------------
%
% The TextTestRunner class provides a way to run tests without a display.
% Using the TextTestRunner involves constructing a TextTestRunner object
% and calling its various functions (described below). As usual, I will
% omit the object parameter in each method signature.
%
% TextTestRunner([names])
% Constructor for the TextTestRunner. The optional names parameter lets
% you set up the runner with an initial set of tests. See addTests below
% for syntax of the names parameter.
%
% addTests(names)
% Adds tests to the list of tests to be run by the runner. The names
% parameter can be a string or a cell array of strings. Each string
% should be the name of a test case or test suite class, which must be in
% the current MATLAB path. Unlike the Add Tests button of the
% GuiTestRunner, this actually appends tests to the current set of tests.
% Any test results are lost, however.
%
% clearTests()
% Removes any previously added tests and any associated results.
%
% runTests()
% Runs all tests. A text progress bar is provided, but note that it will
% be completely munged if any of the code under test uses disp or fprintf
% to write out to the screen. After the run, a summary of test results
% is displayed.
%
% showReport()
% Shows a summary of any existing test results. This is useful, for
% instance, while fixing a set of broken tests; rather than rerunning all
% of the tests, you can use showReport() to display the summary of the
% most recent test run.
%
%
% KNOWN ISSUES ------------
%
% * When you change a test case after a previous test run, MATLAB will warn you
% that the changes cannot be used due to existing objects of this class.
% Closing the GuiTestRunner or calling delete() on the TestRunner should clear
% any references to your classes, after which you can issue a "clear classes"
% command.
%
% * The GuiTestRunner makes use of an unsupported gui component, uitree, to
% provide the tree structured Tests pane. Mathworks warns that this
% feature will change in a future release.
%
