1 /* --COPYRIGHT--,EPL
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * --/COPYRIGHT--*/
12 /*
13 * ======== Test.xdc ========
14 */
15 package xdc.bld;
16
17 /*!
18 * ======== Test ========
19 * Model of a test
20 *
21 * Each Test instance represents a pair consisting of an executable and
22 * command line arguments for that executable. Each pair uniquely
23 * identifies an output sequence (the result of running the executable
24 * with the specified arguments) that can be compared to a known valid
25 * result. Executables that have non-deterministic execution behavior
26 * (e.g., multi-threaded apps) must ensure that the output is independent
27 * of these variations.
28 *
29 * Test instances are created via the `Executable.addTest()` function;
30 * this ensures that each test is associated with a containing executable.
31 *
32 * Test instances do not have unique names. However, each test does have
33 * a "group" name which is optionally specified via `Test.Attrs`. If the
34 * "group" name is not specified, it defaults to the name of the containing
35 * executable. To run any group of tests (which may consist of one or more
36 * executable and command-line pairs) it is sufficient to run
37 * the following command:
38 * @p(code) 39 * xdc <test_group_name>.test
40 * @p 41 * where `<test_group_name>` is the name of the test group to run.
42 *
43 * Each Executable instance (created via `PackageContents.addExecutable()`)
44 * implicitly adds a test whose "group" name is the name of the executable
45 * and whose arguments are empty (i.e., argc == 0). Thus, it is possible
46 * to run any executable that can be built using the following command:
47 * @p(code) 48 * xdc <exe_name>.test
49 * @p 50 * where `<exe_name>` is the name of the executable. Note that if you add a
51 * test to the executable (without specifying a unique `groupName`), the
52 * command above will run the executable more than once; it will run once
53 * for every test associated with the executable.
54 */
55 metaonlymodule Test {
56 /*!
57 * ======== Attrs ========
58 * Optional attributes for a test instance.
59 *
60 * Unspecified attributes are "inherited" from `{@link Executable#Attrs}`;
61 * i.e., if one of fields in this structure is unspecified *and* this
62 * field's name matches a field name in `Executable.Attrs`, then
63 * this field's value defaults to the value in specified by
64 * `Executable.Attrs`. This mechanism makes it possible to establish
65 * executable-specific default values for any of the "inherited"
66 * attributes.
67 *
68 * @field(args) this is a string of arguments (which may contain
69 * embedded strings) that are passed to the executable
70 * being run.
71 * @field(execCmd) this string names the "loader" which is responsible
72 * for running the executable with the arguments
73 * specified by the `args` field. If this field is
74 * `null` or `undefined`, the command used to run
75 * the executable is determined by the executable's
76 * configuration script; see
77 * `{@link xdc.cfg.Program#execCmd}`.
78 * @field(execArgs) this is a string of arguments passed to the
79 * "loader" to control how this loader manages the
80 * execution of the executable being run.
81 * @field(groupName) the name of the group of tests that this test is a
82 * a member of.
83 * @field(refOutput) the name of a "reference" text file that is used
84 * to validate the output generated by running
85 * the executable with the specified arguments. If
86 * the exit status of the executable is 0 and the
87 * output of the executable differs from the
88 * contents of `refOutput`, the test fails. If this
89 * comparison fails, the output of the executable is
90 * saved to a temporary file to allow analysis of the
91 * failure. The temporary file's name is:
92 * "`.tmp,{exeName},{id}`", where `{exeName}` is the
93 * name of the executable and `{id}` is a test
94 * id number.
95 *
96 * If `refOutput` is not defined (or set to `null`)
97 * no comparison is made; only the exit status of the
98 * executable is used to determine the success or
99 * failure of the test.
100 * @field(refExitCode) the expected exit status of the executable.
101 *
102 * If `refExitCode` is not defined (or set to `null`)
103 * an exit status of 0 is assumed.
104 *
105 * @see #attrs
106 */
107 struct Attrs {
108 string args; /*! arguments passed to the exe for this test */
109 string execCmd; /*! exec command for this test */
110 string execArgs; /*! arguments to the exec command itself */
111 string groupName; /*! name of a group of related tests */
112 string refOutput; /*! name of a reference output file */
113 int refExitCode; /*! expected exit code (default = 0) */
114 };
115
116 instance:
117 /*!
118 * ======== create ========
119 * @_nodoc 120 * Instances should only be created via Executable.addTest()
121 */
122 create();
123
124 /*!
125 * ======== attrs ========
126 * Optional attributes for this test instance.
127 *
128 * Default values for each of the fields in attrs:
129 * @p(dlist) 130 * - `groupName`
131 * name of the program "containing" this test
132 *
133 * - `execCmd`
134 * the first non-`null` value in:
135 * `prog.attrs.test.exec,
136 * xdc.cfg.Program.execCmd`,
137 * `prog.platform.getExecCmd()`.
138 *
139 * - execArgs
140 * the first non-`null` value in:
141 * `prog.attrs.test.execArgs`,
142 * "".
143 *
144 * - args
145 * the first non-`null` value in:
146 * `prog.attrs.test.args`,
147 * "".
148 */
149 config Test.Attrs attrs;
150 }
151 /*
152 * @(#) xdc.bld; 1, 0, 2,215; 7-29-2009 14:53:06; /db/ztree/library/trees/xdc-t56x/src/packages/
153 */
154