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

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