⟦e72121a9d⟧

TextFile


The unit test generation tool is intended to automatically generate a
template program that will, with user completion, unit test a given
subprogram interface.  Like Create_Body, this command creates a skeleton
program for unit testing the subprogram interfaces in a given package.
Completion of the template by the user is required before the test can
be executed.

The main procedure interface is:

  procedure Build_Unit_Test (Subprogram_Declarations : String := "";
                             Test_Program_Context : String := "");
                             
Parameters:

  Subprogram_Declarations: specifies subprogram declarations within the
  package to be tested.  Consider the following package specification:

    package Package_Under_Test is

        type T is private;

        function Init return T;
        procedure Flip (Input : T; Output : out Boolean);
        function Flop (D : Character) return String;

    private
        type T is new Boolean;
    end Package_Under_Test;
    
A reasonable naming expression might be "Package_Under_Test.@" to test
all subprograms, or "Package_Under_Test.[Flip, Flop]" to test only
procedure Flip and function flop.  Note: only subprograms declared
within a package can be handled at this time.

  Test_Program_Context: specifies the library in which to put the
  template test program.


This program generates ada code in a temporary file in
"!Machine.Temporary", then parses it into the library specified by
Test_Program_Context.  A package called Test_"Package_Under_Test" is
created with one test procedure for each specified declaration and
two procedures for opening and closing a report file.  Example:

    package Test_Package_Under_Test is

        procedure Open (Report_Name : String);

        procedure Close;

        procedure Test_Init;

        procedure Test_Flip;

        procedure Test_Flop;

    end Test_Package_Under_Test;

A main program for calling each unit test in turn is also generated.
Example:

    with Test_Package_Under_Test;
    procedure Test_All_Package_Under_Test_Subprograms
                 (Report_Name : String := "") is
    begin

        Test_Package_Under_Test.Open (Report_Name);

        Test_Package_Under_Test.Test_Init;
    
        Test_Package_Under_Test.Test_Flip;
    
        Test_Package_Under_Test.Test_Flop;
    
        Test_Package_Under_Test.Close;

    end Test_All_Package_Under_Test_Subprograms;
    pragma Main;
    
This procedure or a modified form of this procedure should be used for
executing the unit tests.  The Report_Name parameter specifies the name
of the file in which to put the output from testing.


For EACH subprogram under test the following Ada code is generated
and placed in the pacakge body of Test_Package_Under_Test:

    type Flip_Parameter_Values is
        record
            Output_Boolean_Expected_Value : Boolean := True;
            Input_T_Input_Value : Package_Under_Test.T := [expression];
        end record;

    procedure Yield (Values : out Flip_Parameter_Values; 
                     Quit   : out Boolean) is
        P : Flip_Parameter_Values;
    begin

        -- Initialization expressions go here

        Values := P;

        -- determination of when to quit is next:

        if True then
            Quit := True;
        else
            Quit := False;
        end if;
    end Yield;

A record type declaration is created to hold both input parameter values
and expected output values for each subprogram.  Functions have only
input values but an expected return value as well.  Record components
are initialized with appropriate values when possible.  The user should
edit these values and provides specific values for each [expression]
prompt.

The Yield procedure is called repeatedly by the unit test software
until the Quit parameter is reported as true.  Input parameters stored
in the record (provided by the Values parameter of the Yield procedure)
are submitted to the subprogram under test.  Output values from the
subprogram under test are then compared with the expected output values.
If the values are equal the test is reported as passed; otherwise it is
reported as failed.

The user is required to fill out the body of the Yield procedure to both
generate appropriate parameter values in the local record P and to
specify when to Quit.

The unit test software for each subprogram is created as a subunit.  No
modifications are necessary to this code although the user is ceratainly
allowed to modifiy the template in any way appropriate to the test.  An
Example:

    separate (Test_Package_Under_Test)
    procedure Test_Flip is

        Terminate_Iteration : Boolean := False;
        Parameters : Flip_Parameter_Values;
        Iteration_Count : Natural := 0;

        Output_Boolean_Output_Value : Boolean;

    begin

        Report.Begin_Execution
            ("!...TEST_PROGRAM_CONTEXT.PACKAGE_UNDER_TEST.FLIP");
        Report.New_Line;

        while not Terminate_Iteration loop

            Report.Capture_Output;

            Yield (Parameters, Terminate_Iteration);

            Iteration_Count := Iteration_Count + 1;

            Report.Comment ("ITERATION NUMBER: " &
                        Positive'Image (Iteration_Count));
            Report.New_Line;

            Report.Comment ("INPUTS:");
            Report.New_Line;

            Report_Value ("INPUT", Parameters.Input_T_Input_Value);
            Report.New_Line;
            Report.New_Line;

            Package_Under_Test.Flip (Output => Output_Boolean_Output_Value,
                                     Input => Parameters.Input_T_Input_Value);

            Report.New_Line;

            Report.Comment ("EXPECTED VALUE:");
            Report.New_Line;

            Report.Value ("OUTPUT", Parameters.Output_Boolean_Expected_Value);
            Report.Comment ("ACTUAL OUTPUTS:");
            Report.New_Line;

            Report.Value ("OUTPUT", Output_Boolean_Output_Value);

            Report.New_Line;

            Report.New_Line;
            Report.New_Line;

            Report.Terminate_Execution;
            Report.New_Line;

            if (Parameters.Output_Boolean_Expected_Value =
                Output_Boolean_Output_Value) then
                Report.Passed;
            else
                Report.Failed;
            end if;

            Report.New_Line;
            Report.New_Line;
        end loop;
    exception
        when others =>
            Report.Terminate_Execution;
            Report.New_Line;
            Report.Exception_Raise (Debug_Tools.Get_Exception_Name);

    end Test_Flip;

This software repeatedly calls the Yield procedure until a Quit is
signaled.  All inputs, expected outputs, and actual outputs are listed
in the report.  All Text_Io output is captured and displayed in the
report.  Any exceptions that are raised are also recorded in the report.

Note that visibility is required to the Report package in order to
compile the tests.  This package is part of the visible software
available with this tool.  The user is required to set up visibility to
this package.

Depending on the kind of parameters in the subprogram under test, the
following special considerations are required:

For Boolean, Integer, Float, and Character types and subtypes of those
types, no special considerations are necessary.

For String types, the unit test template stores them as unbounded
strings using an instantiation of the package "!Tools.Unbounded_String".
The user must also establish visibility to this package or use another
method for string storage.  The tool currently does NOT automatically
handle string parameters that are of mode OUT or IN_OUT.  The user will
have to specify a mechanism for handling these cases as well as any
other unconstrained OUT parameters.

For other types such as private and limited private types, records,
arrays, access, task, and derived types, the user must provide an Image
function for values of that type.  Example:

    function Image (A_T : Package_Under_Test.T) return String is
    begin
        return [expression];
    end Image;

This function generates a string image from a value of the type for
inclusion in the test report.

An example test report:

  TEST REPORT FOR PACKAGE PACKAGE_UNDER_TEST

  USER: DHE
  SESSION: S_1
  AT: September 7, 1987 at 7:13:14 PM
  ---------------------------------------------------------------------

  EXECUTING:

    !...PACKAGE_UNDER_TEST.INIT

  SUBPROGRAM PROFILE:

    function Init return T;


  ITERATION NUMBER:  1
  INPUTS:




    EXPECTED RETURN VALUE: TRUE
    ACTUAL   RETURN VALUE: TRUE


  OUTPUT FROM EXECUTION BETWEEN DASHES:
  ---------------------
  ---------------------

  !!! PASSED !!!


  ---------------------------------------------------------------------

  EXECUTING:

    !...PACKAGE_UNDER_TEST.FLIP

  SUBPROGRAM PROFILE:

    procedure Flip (Input : T; Output : out Boolean);


  ITERATION NUMBER:  1
  INPUTS:
    INPUT: TRUE



  EXPECTED VALUE:
    OUTPUT: TRUE
  ACTUAL OUTPUTS:
    OUTPUT: TRUE



  OUTPUT FROM EXECUTION BETWEEN DASHES:
  ---------------------
  ---------------------

  !!! PASSED !!!


  ITERATION NUMBER:  2
  INPUTS:
    INPUT: TRUE



  EXPECTED VALUE:
    OUTPUT: TRUE
  ACTUAL OUTPUTS:
    OUTPUT: FALSE



  OUTPUT FROM EXECUTION BETWEEN DASHES:
  ---------------------
  ---------------------

  *** FAILED ***


  ---------------------------------------------------------------------

  EXECUTING:

    !...PACKAGE_UNDER_TEST.FLOP

  SUBPROGRAM PROFILE:

    function Flop (D : Character) return String;


  ITERATION NUMBER:  1
  INPUTS:
    D: 'A'




    EXPECTED RETURN VALUE: ""
    ACTUAL   RETURN VALUE: ""


  OUTPUT FROM EXECUTION BETWEEN DASHES:
  ---------------------
This is some Text_Io output
that would go to the screen.
  ---------------------

  !!! PASSED !!!



To summarize the steps necessary to use this tool:

  1. Build a library to contain the generated unit test programs.  At a
  minimum, establish visibility to the Report package included in the
  interfaces for this tool and to the package !Tools.Unbounded_String.

  2. Execute the Build_Unit_Test procedure with appropriate values for
  specifying the subprograms to test and the test library created in
  step 1.

  3. Edit the body of the generated unit test program to:
  
     A. Complete any initial expressions for parameter inputs and
     expected outputs.
     
     B. Complete the Yield function to generated test input and expected
     output.
     
     C. Define image functions for non-predefined types.
     
  4. Compile and execute the unit test program providing a name for the
     report.
     
     
KNOW BUGS AND RESTRICTIONS:

  1.  The test report will not display images of user defined operator
      functions.  This is due to a bug in directory tools and should
      be fixed in the next release of the system


  2.  The program does not handle unconstrained out parameters (e.g. String)
DataMuseum.dk

Rational R1000/400 Tapes

⟦e72121a9d⟧ TextFile

Derivation

TextFile
