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

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass article
   4 \begin_preamble
   5 \pdfoptionpdfminorversion=3
   6 \usepackage[
   7   pdftitle={Proposed Test Suite Design},
   8   pdfauthor={Michael Hope},
   9   pdfkeywords={c case compiler framework GPL regression SDCC suite test},
  10   colorlinks=true,
  11   linkcolor=blue] {hyperref}
  12 \end_preamble
  13 \language english
  14 \inputencoding auto
  15 \fontscheme times
  16 \graphics default
  17 \paperfontsize default
  18 \spacing single
  19 \papersize Default
  20 \paperpackage a4
  21 \use_geometry 0
  22 \use_amsmath 0
  23 \use_natbib 0
  24 \use_numerical_citations 0
  25 \paperorientation portrait
  26 \secnumdepth 3
  27 \tocdepth 3
  28 \paragraph_separation indent
  29 \defskip medskip
  30 \quotes_language english
  31 \quotes_times 2
  32 \papercolumns 1
  33 \papersides 1
  34 \paperpagestyle default
  35
  36 \layout Title
  37
  38 Proposed Test Suite Design
  39 \begin_inset ERT
  40 status Open
  41
  42 \layout Standard
  43
  44 \backslash
  45 date{2001-07-13}
  46 \end_inset
  47
  48
  49 \layout Author
  50
  51 Michael Hope (michaelh @ juju.net.nz)
  52 \layout Abstract
  53
  54 This article describes the goals, requirements, and suggested specification
  55  for a test suite for the output of the Small Device C Compiler (sdcc).
  56  Also included is a short list of existing works.
  57
  58 \layout Section
  59
  60 Goals
  61 \layout Standard
  62
  63 The main goals of a test suite for sdcc are
  64 \layout Enumerate
  65
  66 To allow developers to run regression tests to check that core changes do
  67  not break any of the many ports.
  68
  69 \layout Enumerate
  70
  71 To verify the core.
  72
  73 \layout Enumerate
  74
  75 To allow developers to verify individual ports.
  76
  77 \layout Enumerate
  78
  79 To allow developers to test port changes.
  80
  81 \layout Standard
  82
  83 This design only covers the generated code.
  84  It does not cover a test/unit test framework for the sdcc application itself,
  85  which may be useful.
  86 \layout Standard
  87
  88 One side effect of (1) is that it requires that the individual ports pass
  89  the tests originally.
  90  This may be too hard.
  91  See the section on Exceptions below.
  92 \layout Section
  93
  94 Requirements
  95 \layout Subsection
  96
  97 Coverage
  98 \layout Standard
  99
 100 The suite is intended to cover language features only.
 101  Hardware specific libraries are explicitly not covered.
 102 \layout Subsection
 103
 104 Permutations
 105 \layout Standard
 106
 107 The ports often generate different code for handling different types (Byte,
 108  Word, DWord, and the signed forms).
 109  Meta information could be used to permute the different test cases across
 110  the different types.
 111 \layout Subsection
 112
 113 Exceptions
 114 \layout Standard
 115
 116 The different ports are all at different levels of development.
 117  Test cases must be able to be disabled on a per port basis.
 118  Permutations also must be able to be disabled on a port level for unsupported
 119  cases.
 120  Disabling, as opposed to enabling, on a per port basis seems more maintainable.
 121 \layout Subsection
 122
 123 Running
 124 \layout Standard
 125
 126 The tests must be able to run unaided.
 127  The test suite must run on all platforms that sdcc runs on.
 128  A good minimum may be a subset of Unix command set and common tools, provided
 129  by default on a Unix host and provided through cygwin on a Windows host.
 130 \layout Standard
 131
 132 The tests suits should be able to be sub-divided, so that the failing or
 133  interesting tests may be run separately.
 134 \layout Subsection
 135
 136 Artifcats
 137 \layout Standard
 138
 139 The test code within the test cases should not generate artifacts.
 140  An artifact occurs when the test code itself interferes with the test and
 141  generates an erroneous result.
 142 \layout Subsection
 143
 144 Emulators
 145 \layout Standard
 146
 147 sdcc is a cross compiling compiler.
 148  As such, an emulator is needed for each port to run the tests.
 149 \layout Section
 150
 151 Existing works
 152 \layout Subsection
 153
 154 DejaGnu
 155 \layout Standard
 156
 157 DejaGnu is a toolkit written in Expect designed to test an interactive program.
 158  It provides a way of specifying an interface to the program, and given
 159  that interface a way of stimulating the program and interpreting the results.
 160  It was originally written by Cygnus Solutions for running against development
 161  boards.
 162  I believe the gcc test suite is written against DejaGnu, perhaps partly
 163  to test the Cygnus ports of gcc on target systems.
 164 \layout Subsection
 165
 166 gcc test suite
 167 \layout Standard
 168
 169 I don't know much about the gcc test suite.
 170  It was recently removed from the gcc distribution due to issues with copyright
 171  ownership.
 172  The code I saw from older distributions seemed more concerned with esoteric
 173  features of the language.
 174 \layout Subsection
 175
 176 xUnit
 177 \layout Standard
 178
 179 The xUnit family, in particular JUnit, is a library of in test assertions,
 180  test wrappers, and test suite wrappers designed mainly for unit testing.
 181  PENDING: More.
 182 \layout Subsection
 183
 184 CoreLinux++ Assertion framework
 185 \layout Standard
 186
 187 While not a test suite system, the assertion framework is an interesting
 188  model for the types of assertions that could be used.
 189  They include pre-condition, post-condition, invariants, conditional assertions,
 190  unconditional assertions, and methods for checking conditions.
 191 \layout Section
 192
 193 Specification
 194 \layout Standard
 195
 196 This specification borrows from the JUnit style of unit testing and the
 197  CoreLinux++ style of assertions.
 198  The emphasis is on maintainability and ease of writing the test cases.
 199 \layout Subsection
 200
 201 Terms
 202 \layout Standard
 203
 204 PENDING: Align these terms with the rest of the world.
 205 \layout Itemize
 206
 207 An
 208 \emph on
 209 assertion
 210 \emph default
 211  is a statement of how things should be.
 212  PENDING: Better description, an example.
 213
 214 \layout Itemize
 215
 216 A
 217 \emph on
 218 test point
 219 \emph default
 220  is the smallest unit of a test suite, and consists of a single assertion
 221  that passes if the test passes.
 222
 223 \layout Itemize
 224
 225 A
 226 \emph on
 227 test case
 228 \emph default
 229  is a set of test points that test a certain feature.
 230
 231 \layout Itemize
 232
 233 A
 234 \emph on
 235 test suite
 236 \emph default
 237  is a set of test cases that test a certain set of features.
 238
 239 \layout Subsection
 240
 241 Test cases
 242 \layout Standard
 243
 244 Test cases shall be contained in their own C file, along with the meta data
 245  on the test.
 246  Test cases shall be contained within functions whose names start with 'test'
 247  and which are descriptive of the test case.
 248  Any function that starts with 'test' will be automatically run in the test
 249  suite.
 250 \layout Standard
 251
 252 To make the automatic code generation easier, the C code shall have this
 253  format
 254 \layout Itemize
 255
 256 Test functions shall start with 'test' to allow automatic detection.
 257
 258 \layout Itemize
 259
 260 Test functions shall follow the K&R intention style for ease of detection.
 261  i.e.
 262  the function name shall start in the left column on a new line below the
 263  return specification.
 264
 265 \layout Subsection
 266
 267 Assertions
 268 \layout Standard
 269
 270 All assertions shall log the line number, function name, and test case file
 271  when they fail.
 272  Most assertions can have a more descriptive message attached to them.
 273  Assertions will be implemented through macros to get at the line information.
 274  This may cause trouble with artifacts.
 275 \layout Standard
 276
 277 The following definitions use C++ style default arguments where optional
 278  messages may be inserted.
 279  All assertions use double opening and closing brackets in the macros to
 280  allow them to be compiled out without any side effects.
 281  While this is not required for a test suite, they are there in case any
 282  of this code is incorporated into the main product.
 283 \layout Standard
 284
 285 Borrowing from JUnit, the assertions shall include
 286 \layout Itemize
 287
 288 FAIL((String msg =
 289 \begin_inset Quotes eld
 290 \end_inset
 291
 292 Failed
 293 \begin_inset Quotes erd
 294 \end_inset
 295
 296 )).
 297  Used when execution should not get here.
 298
 299 \layout Itemize
 300
 301 ASSERT((Boolean cond, String msg =
 302 \begin_inset Quotes eld
 303 \end_inset
 304
 305 Assertion failed
 306 \begin_inset Quotes erd
 307 \end_inset
 308
 309 ).
 310  Fails if cond is false.
 311  Parent to REQUIRE and ENSURE.
 312
 313 \layout Standard
 314
 315 JUnit also includes may sub-cases of ASSERT, such as assertNotNull, assertEquals
 316 , and assertSame.
 317 \layout Standard
 318
 319 CoreLinux++ includes the extra assertions
 320 \layout Itemize
 321
 322 REQUIRE((Boolean cond, String msg =
 323 \begin_inset Quotes eld
 324 \end_inset
 325
 326 Precondition failed
 327 \begin_inset Quotes erd
 328 \end_inset
 329
 330 ).
 331  Checks preconditions.
 332
 333 \layout Itemize
 334
 335 ENSURE((Boolean cond, String msg =
 336 \begin_inset Quotes eld
 337 \end_inset
 338
 339 Postcondition failed
 340 \begin_inset Quotes erd
 341 \end_inset
 342
 343 ).
 344  Checks post conditions.
 345
 346 \layout Itemize
 347
 348 CHECK((Boolean cond, String msg =
 349 \begin_inset Quotes eld
 350 \end_inset
 351
 352 Check failed
 353 \begin_inset Quotes erd
 354 \end_inset
 355
 356 )).
 357  Used to call a function and to check that the return value is as expected.
 358  i.e.
 359  CHECK((fread(in, buf, 10) != -1)).
 360  Very similar to ASSERT, but the function still gets called in a release
 361  build.
 362
 363 \layout Itemize
 364
 365 FORALL and EXISTS.
 366  Used to check conditions within part of the code.
 367  For example, can be used to check that a list is still sorted inside each
 368  loop of a sort routine.
 369
 370 \layout Standard
 371
 372 All of FAIL, ASSERT, REQUIRE, ENSURE, and CHECK shall be available.
 373 \layout Subsection
 374
 375 Meta data
 376 \layout Standard
 377
 378 PENDING: It's not really meta data.
 379 \layout Standard
 380
 381 Meta data includes permutation information, exception information, and permutati
 382 on exceptions.
 383 \layout Standard
 384
 385 Meta data shall be global to the file.
 386  Meta data names consist of the lower case alphanumerics.
 387  Test case specific meta data (fields) shall be stored in a comment block
 388  at the start of the file.
 389  This is only due to style.
 390 \layout Standard
 391
 392 A field definition shall consist of
 393 \layout Itemize
 394
 395 The field name
 396 \layout Itemize
 397
 398 A colon.
 399
 400 \layout Itemize
 401
 402 A comma separated list of values.
 403
 404 \layout Standard
 405
 406 The values shall be stripped of leading and trailing white space.
 407 \layout Standard
 408
 409 Permutation exceptions are by port only.
 410  Exceptions to a field are specified by a modified field definition.
 411  An exception definition consists of
 412 \layout Itemize
 413
 414 The field name.
 415
 416 \layout Itemize
 417
 418 An opening square bracket.
 419
 420 \layout Itemize
 421
 422 A comma separated list of ports the exception applies for.
 423
 424 \layout Itemize
 425
 426 A closing square bracket.
 427
 428 \layout Itemize
 429
 430 A colon.
 431
 432 \layout Itemize
 433
 434 The values to use for this field for these ports.
 435
 436 \layout Standard
 437
 438 An instance of the test case shall be generated for each permutation of
 439  the test case specific meta data fields.
 440 \layout Standard
 441
 442 The runtime meta fields are
 443 \layout Itemize
 444
 445 port - The port this test is running on.
 446
 447 \layout Itemize
 448
 449 testcase - The name of this test case.
 450
 451 \layout Itemize
 452
 453 function - The name of the current function.
 454
 455 \layout Standard
 456
 457 Most of the runtime fields are not very usable.
 458  They are there for completeness.
 459 \layout Standard
 460
 461 Meta fields may be accessed inside the test case by enclosing them in curly
 462  brackets.
 463  The curly brackets will be interpreted anywhere inside the test case, including
 464  inside quoted strings.
 465  Field names that are not recognised will be passed through including the
 466  brackets.
 467  Note that it is therefore impossible to use some strings within the test
 468  case.
 469 \layout Standard
 470
 471 Test case function names should include the permuted fields in the name
 472  to reduce name collisions.
 473 \layout Subsection
 474
 475 An example
 476 \layout Standard
 477
 478 I don't know how to do pre-formatted text in LaTeX.
 479  Sigh.
 480 \layout Standard
 481
 482 The following code generates a simple increment test for all combinations
 483  of the storage classes and all combinations of the data sizes.
 484  This is a bad example as the optimiser will often remove most of this code.
 485 \newline
 486
 487 \layout Verse
 488
 489
 490 \family typewriter
 491 /** Test for increment.
 492
 493 \newline
 494 \SpecialChar ~
 495 \SpecialChar ~
 496 type: char, int, long
 497 \newline
 498 \SpecialChar ~
 499 \SpecialChar ~
 500 Z80 port does not fully support longs (4 byte)
 501 \newline
 502 \SpecialChar ~
 503 \SpecialChar ~
 504 type[z80]: char, int
 505 \newline
 506 \SpecialChar ~
 507 \SpecialChar ~
 508 class:
 509 \begin_inset Quotes eld
 510 \end_inset
 511
 512
 513 \begin_inset Quotes erd
 514 \end_inset
 515
 516 , register, static */
 517 \newline
 518
 519 \newline
 520 static void
 521 \newline
 522 testInc{class}{types}(void)
 523 \newline
 524 {
 525 \newline
 526 \SpecialChar ~
 527 \SpecialChar ~
 528 {class} {type} i = 0;
 529 \newline
 530 \SpecialChar ~
 531 \SpecialChar ~
 532 i = i + 1;
 533 \newline
 534 \SpecialChar ~
 535 \SpecialChar ~
 536 ASSERT((i == 1));
 537 \newline
 538 }
 539 \the_end