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

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