cantera/ext/matlab_xunit/TestRunDisplay.m

classdef TestRunDisplay < TestRunMonitor
%TestRunDisplay Print test suite execution results.
%   TestRunDisplay is a subclass of TestRunMonitor.  If a TestRunDisplay
%   object is passed to the run method of a TestComponent, such as a
%   TestSuite or a TestCase, it will print information to the Command
%   Window (or specified file handle) as the test run proceeds.
%
%   TestRunDisplay methods:
%       testComponentStarted  - Update Command Window display
%       testComponentFinished - Update Command Window display
%       testCaseFailure       - Log test failure information
%       testCaseError         - Log test error information
%
%   TestRunDisplay properties:
%       TestCaseCount         - Number of test cases executed
%       Faults                - Struct array of test fault info
%
%   See also TestRunLogger, TestRunMonitor, TestSuite

%   Steven L. Eddins
%   Copyright 2008-2010 The MathWorks, Inc.
    
    properties (SetAccess = private)
        %TestCaseCount - Number of test cases executed
        TestCaseCount
        
        %Faults - Struct array of test fault info
        %   Faults is a struct array with these fields:
        %       Type      - either 'failure' or 'error'
        %       TestCase  - the TestCase object that suffered the fault
        %       Exception - the MException thrown when the fault occurred
        Faults = struct('Type', {}, 'TestCase', {}, 'Exception', {});
        
    end
    
    properties (SetAccess = private, GetAccess = private)
        %InitialTic - Out of tic at beginning of test run
        InitialTic
        
        %InitialComponent First test component executed
        %   InitialComponent is set to the first test component executed in the
        %   test run.  This component is saved so that the end of the test run
        %   can be identified.
        InitialComponent = []   
        
    end
    
    properties (Access = protected)
        %FileHandle - Handle used by fprintf for displaying results.
        %             Default value of 1 displays to Command Window.
        FileHandle = 1
    end
        
    
    methods
        function self = TestRunDisplay(output)
            if nargin > 0
                if ischar(output)
                    self.FileHandle = fopen(output, 'w');
                    if self.FileHandle < 0
                        error('xunit:TestRunDisplay:FileOpenError', ...
                            'Could not open file "%s" for writing.', ...
                            filename);
                    end
                else
                    self.FileHandle = output;
                end
            end
        end
        
        function testComponentStarted(self, component)
            %testComponentStarted Update Command Window display
            %    If the InitialComponent property is not yet set, 
            %    obj.testComponentStarted(component) sets the property and calls
            %    obj.testRunStarted(component).
            
            if isempty(self.InitialComponent)
                self.InitialComponent = component;
                self.testRunStarted(component);
            end
        end    
            
        function testComponentFinished(self, component, did_pass)
            %testComponentFinished Update Command Window display
            %    If component is a TestCase object, then 
            %    obj.testComponentFinished(component, did_pass) prints pass/fail
            %    information to the Command Window.
            %
            %    If component is the InitialComponent, then
            %    obj.testRunFinished(did_pass) is called.
            
            if isa(component, 'TestCase')
                self.TestCaseCount = self.TestCaseCount + 1;
                if did_pass
                    fprintf(self.FileHandle, '.');
                else
                    fprintf(self.FileHandle, 'F');
                end
                line_length = 20;
                if mod(self.TestCaseCount, line_length) == 0
                    fprintf(self.FileHandle, '\n');
                end
            end
            
            if isequal(component, self.InitialComponent)
                self.testRunFinished(did_pass);
            end
        end
               
        function testCaseFailure(self, test_case, failure_exception)
            %testCaseFailure Log test failure information
            %    obj.testCaseFailure(test_case, failure_exception) logs the test
            %    case failure information.
            
            self.logFault('failure', test_case, ...
                failure_exception);
        end
        
        function testCaseError(self, test_case, error_exception)
            %testCaseError Log test error information
            %    obj.testCaseError(test_case, error_exception) logs the test
            %    case error information.
            
            self.logFault('error', test_case, ...
                error_exception);
        end
        
    end
    
    methods (Access = protected)
        function testRunStarted(self, component)
            %testRunStarted Update Command Window display
            %    obj.testRunStarted(component) displays information about the test
            %    run to the Command Window.
            
            self.InitialTic = tic;
            self.TestCaseCount = 0;
            num_cases = component.numTestCases();
            if num_cases == 1
                str = 'case';
            else
                str = 'cases';
            end
            fprintf(self.FileHandle, 'Starting test run with %d test %s.\n', ...
                num_cases, str);
        end
        
        function testRunFinished(self, did_pass)
            %testRunFinished Update Command Window display
            %    obj.testRunFinished(component) displays information about the test
            %    run results, including any test failures, to the Command Window.
            
            if did_pass
                result = 'PASSED';
            else
                result = 'FAILED';
            end
            
            fprintf(self.FileHandle, '\n%s in %.3f seconds.\n', result, toc(self.InitialTic));
            
            self.displayFaults();
        end
        

        
        function logFault(self, type, test_case, exception)
            %logFault Log test fault information
            %    obj.logFault(type, test_case, exception) logs test fault
            %    information. type is either 'failure' or 'error'. test_case is a
            %    TestCase object.  exception is an MException object.
            
            self.Faults(end + 1).Type = type;
            self.Faults(end).TestCase = test_case;
            self.Faults(end).Exception = exception;
        end
        
        function displayFaults(self)
            %displayFaults Display test fault info to Command Window
            %    obj.displayFaults() displays a summary of each test failure and
            %    test error to the command window.
            for k = 1:numel(self.Faults)
                faultData = self.Faults(k);
                if strcmp(faultData.Type, 'failure')
                    str = 'Failure';
                else
                    str = 'Error';
                end
                fprintf(self.FileHandle, '\n===== Test Case %s =====\nLocation: %s\nName:     %s\n\n', str, ...
                    faultData.TestCase.Location, faultData.TestCase.Name);
                displayStack(filterStack(faultData.Exception.stack), ...
                    self.FileHandle);
                fprintf(self.FileHandle, '\n%s\n', faultData.Exception.message);

                fprintf(self.FileHandle, '\n');
            end
        end
        
    end
    
end

function displayStack(stack, file_handle)
%displayStack Display stack trace from MException instance
%   displayStack(stack) prints information about an exception stack to the
%   command window. 

for k = 1:numel(stack)
    filename = stack(k).file;
    linenumber = stack(k).line;
    href = sprintf('matlab: opentoline(''%s'',%d)', filename, linenumber);
    fprintf(file_handle, '%s at <a href="%s">line %d</a>\n', filename, href, linenumber);
end
end

function new_stack = filterStack(stack)
%filterStack Remove unmeaningful stack trace calls
%    new_stack = filterStack(stack) removes from the input stack trace calls
%    that are framework functions and methods that are not likely to be
%    meaningful to the user.

% Testing stack traces follow this common pattern:
%
% 1. The first function call in the trace is often one of the assert functions
% in the framework directory.  This is useful to see.
%
% 2. The next function calls are in the user-written test functions/methods and
% the user-written code under test.  These calls are useful to see.
%
% 3. The final set of function calls are methods in the various framework
% classes.  There are usually several of these calls, which clutter up the 
% stack display without being that useful.
%
% The pattern above suggests the following stack filtering strategy: Once the
% stack trace has left the framework directory, do not follow the stack trace back
% into the framework directory.

mtest_directory = fileparts(which('runtests'));
last_keeper = numel(stack);
have_left_mtest_directory = false;
for k = 1:numel(stack)
    directory = fileparts(stack(k).file);
    if have_left_mtest_directory
        if strcmp(directory, mtest_directory)
            % Stack trace has reentered mtest directory.
            last_keeper = k - 1;
            break;
        end
    else
        if ~strcmp(directory, mtest_directory)
            have_left_mtest_directory = true;
        end
    end
end

new_stack = stack(1:last_keeper);
            
end