tests/README.txt

   1 Please read this file before making any modifications to the test suite.
   2
   3 **********************************************************************
   4 **********************************************************************
   5 * Overview
   6 **********************************************************************
   7 **********************************************************************
   8
   9 The test suite is based on a shell script, 'run_tests.sh', which
  10 calls pcb to export various test case layouts to different output
  11 formats.  The tests to be run are defined in the file 'tests.list'.
  12 The 'tests.list' file defines the export command line options passed
  13 to pcb, the name of the input .pcb file, and the names and file types
  14 for the expected output files.
  15
  16 After a particular test is run, the output files are compared against
  17 a set of "golden" files which are in the golden/ subdirectory.
  18 ALL CHANGES TO THE GOLDEN FILES MUST BE HAND VERIFIED.  This point
  19 can not be emphasized too much.
  20
  21 While this testsuite is clearly not comprehensive (the GUI is totally
  22 left out of the testing for example), it is still better than nothing
  23 and can help detect newly introduced bugs.
  24
  25 **********************************************************************
  26 **********************************************************************
  27 * Running an existing test
  28 **********************************************************************
  29 **********************************************************************
  30
  31 To run all of the tests defined in tests.list run:
  32
  33   ./run_tests.sh
  34
  35 To only run a specific test or tests, then simply list them by name
  36 on the command line like:
  37
  38   ./run_tests.sh test_one test_two ...
  39
  40 **********************************************************************
  41 **********************************************************************
  42 * Updating existing "golden" files
  43 **********************************************************************
  44 **********************************************************************
  45
  46 ./run_tests.sh --regen <testname>
  47
  48 will regenerate the golden file for <testname>.  If you are generating
  49 ASCII output such as BOMs or RS-274X files, then use the diff(3) program
  50 to examine all differences.  If you are generating a graphics file
  51 such as a PNG, then I suggest saving off a copy and using ImageMagick
  52 to look for the differences visually.  The run_tests.sh script has
  53 examples of comparing .png files.  Make sure the changes are only
  54 the expected ones and then check the new files back into git.  Do
  55 not blindly update these files as that defeats the purpose of the tests.
  56
  57 **********************************************************************
  58 **********************************************************************
  59 * Adding New Tests
  60 **********************************************************************
  61 **********************************************************************
  62
  63 ----------------------------------------------------------------------
  64 Create input files
  65 ----------------------------------------------------------------------
  66
  67 Create a *small* layout input file and put it in the inputs/
  68 directory.  The goal is to have a file which tests one particular aspect
  69 of the capabilities of pcb.
  70
  71 ----------------------------------------------------------------------
  72 Add to tests.list
  73 ----------------------------------------------------------------------
  74
  75 Add an entry to the tests.list file for your new tests.  Use existing
  76 entries as an example.
  77
  78 ----------------------------------------------------------------------
  79 Generate the reference files
  80 ----------------------------------------------------------------------
  81
  82 Generate the reference files for your new tests using the following
  83
  84 ./run_tests.sh --regen <new_test_name>
  85
  86 where <new_test_name> is the name of your new test from tests.list.  If you
  87 are adding multiple tests, then you can list them all on the same
  88 command line.
  89
  90 *IMPORTANT*
  91 Verify that the generated .png files for your new tests are correct.  These
  92 files will have been placed in the golden/ subdirectory.
  93
  94 ----------------------------------------------------------------------
  95 Update Makefile.am's
  96 ----------------------------------------------------------------------
  97
  98 Update inputs/Makefile.am and golden/Makefile.am to include your new
  99 files.  If you added new Makefile.am's then be sure to also update
 100 configure.ac at the top level of the source tree.
 101
 102 ----------------------------------------------------------------------
 103 Add the new files to git
 104 ----------------------------------------------------------------------
 105
 106