metaonly module xdc.bld.Test
index URL

Model of a test

Each Test instance represents a pair consisting of an executable and command line arguments for that executable. Each pair uniquely identifies an output sequence (the result of running the executable with the specified arguments) that can be compared to a known valid result. Executables that have non-deterministic execution behavior (e.g., multi-threaded apps) must ensure that the output is independent of these variations. [ more ... ]
XDCscript usage meta-domain sourced in xdc/bld/Test.xdc
var Test = xdc.useModule('xdc.bld.Test');
module-wide constants & types
    var obj = new Test.Attrs// Optional attributes for a test instance;
        obj.args// arguments passed to the exe for this test = String  ...
        obj.execCmd// exec command for this test = String  ...
        obj.execArgs// arguments to the exec command itself = String  ...
        obj.groupName// name of a group of related tests = String  ...
        obj.refOutput// name of a reference output file = String  ...
        obj.refExitCode// expected exit code (default = 0) = Int  ...
per-instance config parameters
    var params = new Test.Params// Instance config-params object;
        params.attrs// Optional attributes for this test instance = Test.Attrs undefined;
 
DETAILS
Each Test instance represents a pair consisting of an executable and command line arguments for that executable. Each pair uniquely identifies an output sequence (the result of running the executable with the specified arguments) that can be compared to a known valid result. Executables that have non-deterministic execution behavior (e.g., multi-threaded apps) must ensure that the output is independent of these variations.
Test instances are created via the Executable.addTest() function; this ensures that each test is associated with a containing executable.
Test instances do not have unique names. However, each test does have a "group" name which is optionally specified via Test.Attrs. If the "group" name is not specified, it defaults to the name of the containing executable. To run any group of tests (which may consist of one or more executable and command-line pairs) it is sufficient to run the following command:
      xdc <test_group_name>.test
where <test_group_name> is the name of the test group to run.
Each Executable instance (created via PackageContents.addExecutable()) implicitly adds a test whose "group" name is the name of the executable and whose arguments are empty (i.e., argc == 0). Thus, it is possible to run any executable that can be built using the following command:
      xdc <exe_name>.test
where <exe_name> is the name of the executable. Note that if you add a test to the executable (without specifying a unique groupName), the command above will run the executable more than once; it will run once for every test associated with the executable.
struct Test.Attrs
index URL

Optional attributes for a test instance

XDCscript usage meta-domain
var obj = new Test.Attrs;
 
    obj.args = String  ...
    // arguments passed to the exe for this test
    obj.execCmd = String  ...
    // exec command for this test
    obj.execArgs = String  ...
    // arguments to the exec command itself
    obj.groupName = String  ...
    // name of a group of related tests
    obj.refOutput = String  ...
    // name of a reference output file
    obj.refExitCode = Int  ...
    // expected exit code (default = 0)
FIELDS
args — this is a string of arguments (which may contain embedded strings) that are passed to the executable being run.
execCmd — this string names the "loader" which is responsible for running the executable with the arguments specified by the args field. If this field is null or undefined, the command used to run the executable is determined by the executable's configuration script; see xdc.cfg.Program.execCmd.
execArgs — this is a string of arguments passed to the "loader" to control how this loader manages the execution of the executable being run.
groupName — the name of the group of tests that this test is a a member of.
refOutput — the name of a "reference" text file that is used to validate the output generated by running the executable with the specified arguments. If the exit status of the executable is 0 and the output of the executable differs from the contents of refOutput, the test fails. If this comparison fails, the output of the executable is saved to a temporary file to allow analysis of the failure. The temporary file's name is: ".tmp,{exeName},{id}", where {exeName} is the name of the executable and {id} is a test id number.
If refOutput is not defined (or set to null) no comparison is made; only the exit status of the executable is used to determine the success or failure of the test.
refExitCode — the expected exit status of the executable.
If refExitCode is not defined (or set to null) an exit status of 0 is assumed.
DETAILS
Unspecified attributes are "inherited" from Executable.Attrs; i.e., if one of fields in this structure is unspecified *and* this field's name matches a field name in Executable.Attrs, then this field's value defaults to the value in specified by Executable.Attrs. This mechanism makes it possible to establish executable-specific default values for any of the "inherited" attributes.
SEE
attrs
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Test.Params;
// Instance config-params object
    params.attrs = Test.Attrs undefined;
    // Optional attributes for this test instance
config Test.attrs  // instance
index URL

Optional attributes for this test instance

XDCscript usage meta-domain
var params = new Test.Params;
  ...
params.attrs = Test.Attrs undefined;
DETAILS
Default values for each of the fields in attrs:
groupName
name of the program "containing" this test
execCmd
the first non-null value in: prog.attrs.test.exec, xdc.cfg.Program.execCmd, prog.platform.getExecCmd().
execArgs
the first non-null value in: prog.attrs.test.execArgs, "".
args
the first non-null value in: prog.attrs.test.args, "".
generated on Tue, 24 Aug 2010 15:39:30 GMT