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