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