git.gag.com Git - fw/sdcc/blob - doc/test_suite_spec.html/index.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2
   3 <!--Converted with LaTeX2HTML 99.1 release (March 30, 1999)
   4 original version by:  Nikos Drakos, CBLU, University of Leeds
   5 * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
   6 * with significant contributions from:
   7   Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
   8 <HTML>
   9 <HEAD>
  10 <TITLE>Proposed Test Suite Design</TITLE>
  11 <META NAME="description" CONTENT="Proposed Test Suite Design">
  12 <META NAME="keywords" CONTENT="test_suite_spec">
  13 <META NAME="resource-type" CONTENT="document">
  14 <META NAME="distribution" CONTENT="global">
  15
  16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  17 <META NAME="Generator" CONTENT="LaTeX2HTML v99.1 release">
  18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
  19
  20 <LINK REL="STYLESHEET" HREF="test_suite_spec.css">
  21
  22 </HEAD>
  23
  24 <BODY >
  25 <!--Navigation Panel-->
  26 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_group" SRC="next_group_motif_gr.gif">
  27 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up_motif_gr.gif">
  28 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="previous_motif_gr.gif">
  29 <BR>
  30 <BR>
  31 <BR>
  32 <!--End of Navigation Panel-->
  33
  34 <P>
  35
  36 <P>
  37
  38 <P>
  39
  40 <P>
  41
  42 <H1 ALIGN="CENTER">Proposed Test Suite Design</H1>
  43 <P ALIGN="CENTER"><STRONG>Michael Hope (michaelh@juju.net.nz)</STRONG></P>
  44 <P ALIGN="CENTER"><STRONG>13 July 2001</STRONG></P>
  45
  46 <H3>Abstract:</H3>
  47 <DIV>
  48 This article describes the goals, requirements, and suggested specification
  49 for a test suite for the output of the Small Device C Compiler (sdcc).
  50 Also included is a short list of existing works.
  51 </DIV>
  52 <P>
  53
  54 <P>
  55
  56 <H1><A NAME="SECTION00010000000000000000">
  57 Goals</A>
  58 </H1>
  59
  60 <P>
  61 The main goals of a test suite for sdcc are
  62
  63 <P>
  64
  65 <OL>
  66 <LI>To allow developers to run regression tests to check that core changes
  67 do not break any of the many ports. </LI>
  68 <LI>To verify the core. </LI>
  69 <LI>To allow developers to verify individual ports. </LI>
  70 <LI>To allow developers to test port changes. </LI>
  71 </OL>
  72 This design only covers the generated code. It does not cover a test/unit
  73 test framework for the sdcc application itself, which may be useful.
  74
  75 <P>
  76 One side effect of (1) is that it requires that the individual ports
  77 pass the tests originally. This may be too hard. See the section on
  78 Exceptions below.
  79
  80 <P>
  81
  82 <H1><A NAME="SECTION00020000000000000000">
  83 Requirements</A>
  84 </H1>
  85
  86 <P>
  87
  88 <H2><A NAME="SECTION00021000000000000000">
  89 Coverage</A>
  90 </H2>
  91
  92 <P>
  93 The suite is intended to cover language features only. Hardware specific
  94 libraries are explicitly not covered.
  95
  96 <P>
  97
  98 <H2><A NAME="SECTION00022000000000000000">
  99 Permutations</A>
 100 </H2>
 101
 102 <P>
 103 The ports often generate different code for handling different types
 104 (Byte, Word, DWord, and the signed forms). Meta information could
 105 be used to permute the different test cases across the different types.
 106
 107 <P>
 108
 109 <H2><A NAME="SECTION00023000000000000000">
 110 Exceptions</A>
 111 </H2>
 112
 113 <P>
 114 The different ports are all at different levels of development. Test
 115 cases must be able to be disabled on a per port basis. Permutations
 116 also must be able to be disabled on a port level for unsupported cases.
 117 Disabling, as opposed to enabling, on a per port basis seems more
 118 maintainable.
 119
 120 <P>
 121
 122 <H2><A NAME="SECTION00024000000000000000">
 123 Running</A>
 124 </H2>
 125
 126 <P>
 127 The tests must be able to run unaided. The test suite must run on
 128 all platforms that sdcc runs on. A good minimum may be a subset of
 129 Unix command set and common tools, provided by default on a Unix host
 130 and provided through cygwin on a Windows host.
 131
 132 <P>
 133 The tests suits should be able to be sub-divided, so that the failing
 134 or interesting tests may be run separately.
 135
 136 <P>
 137
 138 <H2><A NAME="SECTION00025000000000000000">
 139 Artifcats</A>
 140 </H2>
 141
 142 <P>
 143 The test code within the test cases should not generate artifacts.
 144 An artifact occurs when the test code itself interferes with the test
 145 and generates an erroneous result.
 146
 147 <P>
 148
 149 <H2><A NAME="SECTION00026000000000000000">
 150 Emulators</A>
 151 </H2>
 152
 153 <P>
 154 sdcc is a cross compiling compiler. As such, an emulator is needed
 155 for each port to run the tests.
 156
 157 <P>
 158
 159 <H1><A NAME="SECTION00030000000000000000">
 160 Existing works</A>
 161 </H1>
 162
 163 <P>
 164
 165 <H2><A NAME="SECTION00031000000000000000">
 166 DejaGnu</A>
 167 </H2>
 168
 169 <P>
 170 DejaGnu is a toolkit written in Expect designed to test an interactive
 171 program. It provides a way of specifying an interface to the program,
 172 and given that interface a way of stimulating the program and interpreting
 173 the results. It was originally written by Cygnus Solutions for running
 174 against development boards. I believe the gcc test suite is written
 175 against DejaGnu, perhaps partly to test the Cygnus ports of gcc on
 176 target systems.
 177
 178 <P>
 179
 180 <H2><A NAME="SECTION00032000000000000000">
 181 gcc test suite</A>
 182 </H2>
 183
 184 <P>
 185 I don't know much about the gcc test suite. It was recently removed
 186 from the gcc distribution due to issues with copyright ownership.
 187 The code I saw from older distributions seemed more concerned with
 188 esoteric features of the language.
 189
 190 <P>
 191
 192 <H2><A NAME="SECTION00033000000000000000">
 193 xUnit</A>
 194 </H2>
 195
 196 <P>
 197 The xUnit family, in particular JUnit, is a library of in test assertions,
 198 test wrappers, and test suite wrappers designed mainly for unit testing.
 199 PENDING: More.
 200
 201 <P>
 202
 203 <H2><A NAME="SECTION00034000000000000000">
 204 CoreLinux++ Assertion framework</A>
 205 </H2>
 206
 207 <P>
 208 While not a test suite system, the assertion framework is an interesting
 209 model for the types of assertions that could be used. They include
 210 pre-condition, post-condition, invariants, conditional assertions,
 211 unconditional assertions, and methods for checking conditions.
 212
 213 <P>
 214
 215 <H1><A NAME="SECTION00040000000000000000">
 216 Specification</A>
 217 </H1>
 218
 219 <P>
 220 This specification borrows from the JUnit style of unit testing and
 221 the CoreLinux++ style of assertions. The emphasis is on maintainability
 222 and ease of writing the test cases.
 223
 224 <P>
 225
 226 <H2><A NAME="SECTION00041000000000000000">
 227 Terms</A>
 228 </H2>
 229
 230 <P>
 231 PENDING: Align these terms with the rest of the world.
 232
 233 <P>
 234
 235 <UL>
 236 <LI>An <I>assertion</I> is a statement of how things should be. PENDING:
 237 Better description, an example. </LI>
 238 <LI>A <I>test point</I> is the smallest unit of a test suite, and consists
 239 of a single assertion that passes if the test passes. </LI>
 240 <LI>A <I>test case</I> is a set of test points that test a certain feature. </LI>
 241 <LI>A <I>test suite</I> is a set of test cases that test a certain set
 242 of features. </LI>
 243 </UL>
 244
 245 <P>
 246
 247 <H2><A NAME="SECTION00042000000000000000">
 248 Test cases</A>
 249 </H2>
 250
 251 <P>
 252 Test cases shall be contained in their own C file, along with the
 253 meta data on the test. Test cases shall be contained within functions
 254 whose names start with 'test' and which are descriptive of the test
 255 case. Any function that starts with 'test' will be automatically run
 256 in the test suite.
 257
 258 <P>
 259 To make the automatic code generation easier, the C code shall have
 260 this format
 261
 262 <P>
 263
 264 <UL>
 265 <LI>Test functions shall start with 'test' to allow automatic detection. </LI>
 266 <LI>Test functions shall follow the K&amp;R intention style for ease of detection.
 267 i.e. the function name shall start in the left column on a new line
 268 below the return specification. </LI>
 269 </UL>
 270
 271 <P>
 272
 273 <H2><A NAME="SECTION00043000000000000000">
 274 Assertions</A>
 275 </H2>
 276
 277 <P>
 278 All assertions shall log the line number, function name, and test
 279 case file when they fail. Most assertions can have a more descriptive
 280 message attached to them. Assertions will be implemented through macros
 281 to get at the line information. This may cause trouble with artifacts.
 282
 283 <P>
 284 The following definitions use C++ style default arguments where optional
 285 messages may be inserted. All assertions use double opening and closing
 286 brackets in the macros to allow them to be compiled out without any
 287 side effects. While this is not required for a test suite, they are
 288 there in case any of this code is incorporated into the main product.
 289
 290 <P>
 291 Borrowing from JUnit, the assertions shall include
 292
 293 <P>
 294
 295 <UL>
 296 <LI>FAIL((String msg = ``Failed'')). Used when execution should not
 297 get here. </LI>
 298 <LI>ASSERT((Boolean cond, String msg = ``Assertion failed''). Fails
 299 if cond is false. Parent to REQUIRE and ENSURE. </LI>
 300 </UL>
 301 JUnit also includes may sub-cases of ASSERT, such as assertNotNull,
 302 assertEquals, and assertSame.
 303
 304 <P>
 305 CoreLinux++ includes the extra assertions
 306
 307 <P>
 308
 309 <UL>
 310 <LI>REQUIRE((Boolean cond, String msg = ``Precondition failed'').
 311 Checks preconditions. </LI>
 312 <LI>ENSURE((Boolean cond, String msg = ``Postcondition failed'').
 313 Checks post conditions. </LI>
 314 <LI>CHECK((Boolean cond, String msg = ``Check failed'')). Used to
 315 call a function and to check that the return value is as expected.
 316 i.e. CHECK((fread(in, buf, 10) != -1)). Very similar to ASSERT, but
 317 the function still gets called in a release build. </LI>
 318 <LI>FORALL and EXISTS. Used to check conditions within part of the code.
 319 For example, can be used to check that a list is still sorted inside
 320 each loop of a sort routine. </LI>
 321 </UL>
 322 All of FAIL, ASSERT, REQUIRE, ENSURE, and CHECK shall be available.
 323
 324 <P>
 325
 326 <H2><A NAME="SECTION00044000000000000000">
 327 Meta data</A>
 328 </H2>
 329
 330 <P>
 331 PENDING: It's not really meta data.
 332
 333 <P>
 334 Meta data includes permutation information, exception information,
 335 and permutation exceptions.
 336
 337 <P>
 338 Meta data shall be global to the file. Meta data names consist of
 339 the lower case alphanumerics. Test case specific meta data (fields)
 340 shall be stored in a comment block at the start of the file. This
 341 is only due to style.
 342
 343 <P>
 344 A field definition shall consist of
 345
 346 <P>
 347
 348 <UL>
 349 <LI>The field name </LI>
 350 <LI>A colon. </LI>
 351 <LI>A comma separated list of values. </LI>
 352 </UL>
 353 The values shall be stripped of leading and trailing white space.
 354
 355 <P>
 356 Permutation exceptions are by port only. Exceptions to a field are
 357 specified by a modified field definition. An exception definition
 358 consists of
 359
 360 <P>
 361
 362 <UL>
 363 <LI>The field name. </LI>
 364 <LI>An opening square bracket. </LI>
 365 <LI>A comma separated list of ports the exception applies for. </LI>
 366 <LI>A closing square bracket. </LI>
 367 <LI>A colon. </LI>
 368 <LI>The values to use for this field for these ports. </LI>
 369 </UL>
 370 An instance of the test case shall be generated for each permutation
 371 of the test case specific meta data fields.
 372
 373 <P>
 374 The runtime meta fields are
 375
 376 <P>
 377
 378 <UL>
 379 <LI>port - The port this test is running on. </LI>
 380 <LI>testcase - The name of this test case. </LI>
 381 <LI>function - The name of the current function. </LI>
 382 </UL>
 383 Most of the runtime fields are not very usable. They are there for
 384 completeness.
 385
 386 <P>
 387 Meta fields may be accessed inside the test case by enclosing them
 388 in curly brackets. The curly brackets will be interpreted anywhere
 389 inside the test case, including inside quoted strings. Field names
 390 that are not recognised will be passed through including the brackets.
 391 Note that it is therefore impossible to use some strings within the
 392 test case.
 393
 394 <P>
 395 Test case function names should include the permuted fields in the
 396 name to reduce name collisions.
 397
 398 <P>
 399
 400 <H2><A NAME="SECTION00045000000000000000">
 401 An example</A>
 402 </H2>
 403
 404 <P>
 405 I don't know how to do pre-formatted text in L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X . Sigh.
 406
 407 <P>
 408 The following code generates a simple increment test for all combinations
 409 of the storage classes and all combinations of the data sizes. This
 410 is a bad example as the optimiser will often remove most of this code.
 411
 412 <P>
 413 <TT>/** Test for increment. </TT>
 414
 415 <P>
 416 <TT>type: char, int, long</TT>
 417
 418 <P>
 419 <TT>Z80 port does not fully support longs (4 byte)</TT>
 420
 421 <P>
 422 <TT>type[z80]: char, int</TT>
 423
 424 <P>
 425 <TT>class: ``'', register, static */</TT>
 426
 427 <P>
 428 <TT>static void</TT>
 429
 430 <P>
 431 <TT>testInc{class}{types}(void)</TT>
 432
 433 <P>
 434 <TT>{</TT>
 435
 436 <P>
 437 <TT>{class} {type} i = 0; </TT>
 438
 439 <P>
 440 <TT>i = i + 1;</TT>
 441
 442 <P>
 443 <TT>ASSERT((i == 1));</TT>
 444
 445 <P>
 446 <TT>}</TT>
 447
 448 <H1><A NAME="SECTION00050000000000000000">
 449 About this document ...</A>
 450 </H1>
 451  <STRONG>Proposed Test Suite Design</STRONG><P>
 452 This document was generated using the
 453 <A HREF="http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 99.1 release (March 30, 1999)
 454 <P>
 455 Copyright &#169; 1993, 1994, 1995, 1996,
 456 <A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
 457 Computer Based Learning Unit, University of Leeds.
 458 <BR>
 459 Copyright &#169; 1997, 1998, 1999,
 460 <A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
 461 Mathematics Department, Macquarie University, Sydney.
 462 <P>
 463 The command line arguments were: <BR>
 464  <STRONG>latex2html</STRONG> <TT>-split 0 -dir test_suite_spec.html test_suite_spec</TT>
 465 <P>
 466 The translation was initiated by Johan Knol on 2001-07-13<HR>
 467 <!--Navigation Panel-->
 468 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_group" SRC="next_group_motif_gr.gif">
 469 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up_motif_gr.gif">
 470 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="previous_motif_gr.gif">
 471 <BR>
 472 <!--End of Navigation Panel-->
 473 <ADDRESS>
 474 <I>Johan Knol</I>
 475 <BR><I>2001-07-13</I>
 476 </ADDRESS>
 477 </BODY>
 478 </HTML>