HeaderDoc::Test

Declared In:

Introduction

Test framework for parser and C preprocessor tests.

Discussion

The Test class is a test framework for testing the HeaderDoc parser and related routines. Each test file is a freeze-dried instance of this class that is loaded by headerDoc2HTML.pl.

Member Functions

_initialize: Initializes an instance of a Test object.
convertToHash: Converts an array alternating between keys and values (one per line) to a hash.
cppTests: Grabs the C preprocessor info from the block parser and stores the results in the Test class.
dbprint: Prints a Test object for debugging purposes.
dumpObjNames: Grabs the HeaderDoc object names resulting from parsing this declaration and stores the results in the Test class.
filterResults: Filters out bits of the test results for comparison purposes.
multiPrint: Prints both the expected and actual values as-is.
new: Creates a new Test object.
objCmp: Compares two object dumps.
readFromFile: Loads this instance from a test file.
runTest: Runs this test.
runtest_sub: Runs this test in the specified mode.
showresults: Compares actual results with expected.
showresults_sub: Compares actual results with expected in a given mode.
singlePrint: Shows the individual lines in two arrays that difer.
starbox: Prints an explanatory message in a box of asterisks.
supportsAllDecs: Returns whether this Test object supports the "all declarations" (-E) mode.
writeToFile: Writes a freeze-dried copy of this instance to a test file.
writeToPlist: Writes tests to a property list file. Currently disabled.

convertToHash

Converts an array alternating between keys and values (one per line) to a hash.

sub convertToHash

Parameters

self: This Test object.
arrayRef: A reference to the source array.

cppTests

Grabs the C preprocessor info from the block parser and stores the results in the Test class.

sub cppTests

Parameters

self: This Test object.

Discussion

If any CPP hash changes occur as a result of parsing this declaration, they are captured by this code.

dumpObjNames

Grabs the HeaderDoc object names resulting from parsing this declaration and stores the results in the Test class.

sub dumpObjNames

Parameters

self: This Test object.
obj: The object tree to dump.

Discussion

This includes the important keys from the HeaderDoc API objects. It does not attempt to include every possible key.

filterResults

Filters out bits of the test results for comparison purposes.

sub filterResults

multiPrint

Prints both the expected and actual values as-is.

sub multiPrint

Parameters

self: This Test object.
string1: The expected values.
string2: The actual values.

new

Creates a new Test object.

sub new

Parameters

param: A reference to the relevant package object (e.g. HeaderDoc::Test->new() to allocate a new instance of this class).

objCmp

Compares two object dumps.

sub objCmp

Parameters

self: This Test object.
string1: The expected values.
string2: The actual values.
all: Set to 0 normally. Set to 1 if you want to see all keys whether they are different or not.

Discussion

Takes the output of an object (key-value pairs) and displays the keys that are different, missing, or added in the actual results.

readFromFile

Loads this instance from a test file.

sub readFromFile

Parameters

self: A newly-created Test class instance.
filename: The filename to read.

runTest

Runs this test.

sub runTest

Parameters

self: The test instance.

Return Value

Returns 0 on success, 1 if the test fails.

runtest_sub

Runs this test in the specified mode.

sub runtest_sub

Parameters

self

The test instance.

alldecs

Pass 0 to run the test normally.

Pass 1 to run the test with the equivalent of the -E command-line flag.

Return Value

Returns 0 on success, 1 if the test fails.

showresults

Compares actual results with expected.

sub showresults

Parameters

self: This Test object.
expanded: See showresults_sub for details.

showresults_sub

Compares actual results with expected in a given mode.

sub showresults_sub

Parameters

self

This Test object.

expanded

Supported values are:

-1 — Reduced output; uses diff to show a minimal set of differences.
0 — Standard output mode.
1 — Expanded output; more raw output.

alldecs

Specifies whether to do the result comparison for the alldecs (-E) results or not (0/1).

singlePrint

Shows the individual lines in two arrays that difer.

sub singlePrint

Parameters

self: This Test object.
string1: The expected results.
string2: The actual results.

starbox

Prints an explanatory message in a box of asterisks.

sub starbox

Parameters

self: This Test object.
string: The string to print.

writeToFile

Writes a freeze-dried copy of this instance to a test file.

sub writeToFile

Parameters

self: A filled-out Test class instance.
filename: The filename to write.

writeToPlist

Writes tests to a property list file. Currently disabled.

sub writeToPlist

Member Data

CODE: The actual code to parse.
COMMENT: The HeaderDoc comment block associated with this test. Used only for parser tests. Empty for C preprocessor tests.
CPPCODE: The C preprocessor macros to parse; used to modify the declaration in CODE. Used only in C preprocessor tests. Empty for parser tests.
EXPECTED_FILTERED_RESULT: A filtered copy of the expected result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.
EXPECTED_FILTERED_RESULT_ALLDECS: A filtered copy of the expected "all declarations" result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.
EXPECTED_RESULT: The expected test results. During test creation, this is filled in by running the test once, ignoring the test failure, and copying the obtained results into this field from RESULT.
EXPECTED_RESULT_ALLDECS: The expected test results. During test creation, this is filled in by running the test once, ignoring the test failure, and copying the obtained results into this field from RESULT_ALLDECS.
FAILMSG: A message to display if the test fails. This can be used to provide additional information about what functionality the test covers.
FILENAME: Filename for this test. Derived from NAME.
FILTERED_RESULT: A filtered copy of the actual result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.
FILTERED_RESULT_ALLDECS: A filtered copy of the actual "all declarations" result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.
HeaderDoc::running_test: Set to 1 if HeaderDoc is currently running a test, else 0.
HeaderDoc::Test::VERSION: The revision control revision number for this module.
HeaderDoc::test_alldecs: Enables "all decs" support in the test module.
LANG: The programming language for the test.
NAME: Name of this test.
RESULT: The actual test results. Filled in automatically by runtest_sub. Because this should always match the expected results, this field should never be serialized to disk.
RESULT_ALLDECS: The actual test results for "all declarations" mode (equivalent to passing the -E flag). Filled in automatically by runtest_sub. Because this should always match the expected results, this field should never be serialized to disk.
SUBLANG: The programming language variant for the test. Usually same as the language, but may differ for languages built on other languages, e.g. javascript or MIG. C language derivatives, in particular, are not specified more precisely; the parser changes languages as it enters a class block.
TYPE: The type of test. Currently either parser or cpp.

CODE

The actual code to parse.

$self->{CODE}

COMMENT

The HeaderDoc comment block associated with this test. Used only for parser tests. Empty for C preprocessor tests.

$self->{COMMENT}

CPPCODE

The C preprocessor macros to parse; used to modify the declaration in CODE. Used only in C preprocessor tests. Empty for parser tests.

$self->{CPPCODE}

A filtered copy of the expected result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.

$self->{EXPECTED_FILTERED_RESULT}

EXPECTED_FILTERED_RESULT_ALLDECS

A filtered copy of the expected "all declarations" result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.

$self->{EXPECTED_FILTERED_RESULT_ALLDECS}

EXPECTED_RESULT

The expected test results. During test creation, this is filled in by running the test once, ignoring the test failure, and copying the obtained results into this field from RESULT.

$self->{EXPECTED_RESULT}

EXPECTED_RESULT_ALLDECS

The expected test results. During test creation, this is filled in by running the test once, ignoring the test failure, and copying the obtained results into this field from RESULT_ALLDECS.

$self->{EXPECTED_RESULT_ALLDECS}

FAILMSG

A message to display if the test fails. This can be used to provide additional information about what functionality the test covers.

$self->{FAILMSG}

FILENAME

Filename for this test. Derived from NAME.

$self->{FILENAME}

FILTERED_RESULT

A filtered copy of the actual result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.

$self->{FILTERED_RESULT}

FILTERED_RESULT_ALLDECS

A filtered copy of the actual "all declarations" result after applying a series of regular expressions to ignore parts of the results. Used for simplifying comparison when a particular type of change is expected. This is temporary data that should never be serialized to disk.

$self->{FILTERED_RESULT_ALLDECS}

HeaderDoc::running_test

Set to 1 if HeaderDoc is currently running a test, else 0.

$HeaderDoc::running_test = 0;

Discussion

Disables lots of warnings caused by imperfect test data while the tests are running.

HeaderDoc::Test::VERSION

The revision control revision number for this module.

$HeaderDoc::Test::VERSION = '$Revision: 1334261201 $';

Discussion

In the git repository, contains the number of seconds since January 1, 1970.

HeaderDoc::test_alldecs

Enables "all decs" support in the test module.

$HeaderDoc::test_alldecs = 0;  # Here, there be dragons.

Discussion

For now, this should be zero. In addition to some languages being ostensibly "supported" by alldecs but not being perfectly supported in that mode (Perl, Pascal), there's also the problem of a bunch of tests whose results change radically that I just don't have time to hand-verify. (TODO: DAG: FIXME)

Also, there are tests that probably will have to be significantly modified because declarations that are not currently being parsed will suddenly get parsed, resulting in lots of apple_ref conflicts and other such madness. In short, it's a major effort that will have to wait a bit.

LANG

The programming language for the test.

$self->{LANG}

NAME

Name of this test.

$self->{NAME}

RESULT

The actual test results. Filled in automatically by runtest_sub. Because this should always match the expected results, this field should never be serialized to disk.

$self->{RESULT}

RESULT_ALLDECS

The actual test results for "all declarations" mode (equivalent to passing the -E flag). Filled in automatically by runtest_sub. Because this should always match the expected results, this field should never be serialized to disk.

$self->{RESULT_ALLDECS}

SUBLANG

The programming language variant for the test. Usually same as the language, but may differ for languages built on other languages, e.g. javascript or MIG. C language derivatives, in particular, are not specified more precisely; the parser changes languages as it enters a class block.

$self->{SUBLANG}

TYPE

The type of test. Currently either parser or cpp.

$self->{TYPE}

Last Updated: Saturday, August 06, 2016