tests/README.how-to

   1 Suggestions and tips for writing test files
   2 Barton Willis
   3
   4 (1) A test file contains pairs of expressions. The first
   5 expression is the input, and the second is the expected output; for
   6 example, here are two tests:
   7
   8 x + 0;
   9 x$
  10
  11 x - x;
  12 0$
  13
  14 You may terminate each line with either a semicolon or a dollar
  15 sign. To keep the file somewhat organized, terminate the input line
  16 with a semicolon and the expected output with a dollar sign. It's helpful to
  17 separate each input / expected output pair with a blank line.
  18
  19 (2) Name your file "rtest_<a word that describes its contents>.mac".
  20 For example, "rtest_abs.mac" is a good name for tests for the absolute
  21 value function.
  22
  23 (3) If the input is something that doesn't need to be checked, make a
  24 compound statement with the last statement being 0. Thus
  25
  26 (assume(x > 0), 0);
  27 0$
  28
  29 abs(x);
  30 x$
  31
  32 (4) If a test needs to use a non-default value for an option variable, try to
  33 make the change local instead of global. For example
  34
  35 is (x < 1), prederror : false;
  36 unknown$
  37
  38 Doing so keeps your test from modifying the global environment.
  39
  40 (5) The first line of the test file should be
  41
  42 (kill(all),0);
  43 0$
  44
  45 (6) From a Maxima input prompt, use the 'batch' function to run your test:
  46
  47      (%i1) batch("rtest_abs.mac", 'test);
  48      Error log on #<output stream rtest_abs.ERR>
  49
  50 You may need to give Maxima a full pathname to the file. After the
  51 test finishes, you can look at the .ERR file to see which tests
  52 failed.
  53
  54 (7) If your test defines functions, makes assumptions, or assigns
  55 values to symbols, the last few lines of your test should clean up the
  56 global environment; thus if your test does assume(x > 0), assigns a
  57 value to 'a', and defines a function 'f', the last line of your test
  58 should be something like
  59
  60 (forget(x > 0), remvalue(a), remfunction(f),0);
  61 0$
  62
  63 (8) To append a test file to the main Maxima test suite,
  64 you'll need to append the file name to the list in the file
  65 /src/testsuite.lisp. If your test has known errors, you'll need to
  66 include this data into testsuite.lisp. To illustrate, the tests
  67 42 and 43 in rtest_abs are known bugs. To tell Maxima that these
  68 are known bugs, append ((mlist) "rtest_abs" 42 43) to the file
  69 list in testsuite.lisp.
  70
  71 Finally, build Maxima and run the test suite. If all goes
  72 well, commit the new test file.
  73
  74 (9) Other:
  75
  76 (a) Check that your test runs multiple times without error. After
  77 appending a new test to Maxima's test suite, make sure that run_testsuite()
  78 runs multiple times without error.
  79
  80 (b) Always test the simple cases: abs(0), abs(0.0), abs(0.0b0), ... Also,
  81 check that functions work correctly for CRE expressions, arguments that
  82 contain '%i', empty lists, empty matrices, ... Thus always test
  83 the 'boundary' cases; these are things like max(), min(), apply("*",[]), ....
  84
  85 (c) Check the sourceforge bug list for all reported bugs for the functions(s)
  86 you are testing. Include tests for these bugs; also put a comment in your
  87 test file that references the bug report:
  88
  89 /*  See SF Bug #  771061 */
  90
  91 expand((vt . a^^(-1) . u+1)^^(-2));
  92 ((vt.a^^(-1).u)^^2+2*(vt.a^^(-1).u)+1)^^(-1)$
  93
  94 If a bug causes a fatal error, you'll need to exclude it from your test
  95 (or better, include it, but comment it out).
  96
  97 (d) It might be easier to place all known failures at the top of the
  98 file. With this policy, you can append new tests without updating the
  99 list of known failures in testsuite.lisp.
 100
 101 (e) If a test checks a not so well known identity, include a reference to the
 102 identity:
 103
 104 /* A&S 13.6.1 */
 105 hgfred([v+1/2],[2*v+1],2*%i*z);
 106 4^(v/2)*bessel_j(v,z)*gamma(v+1)*exp(%i*z)/z^v$
 107
 108 (f) Maxima evaluates the input, but only simplifies the expected output. Thus
 109 a test such as
 110
 111   makelist(sin(k * %pi),k,1,5);
 112   makelist(0,k,1,5)$
 113
 114 will fail. You'll need to write the test as either
 115
 116   makelist(sin(k * %pi),k,1,5);
 117   ''(makelist(0,k,1,5))$
 118
 119 or
 120
 121   makelist(sin(k * %pi),k,1,5);
 122   [0,0,0,0,0]$
 123
 124 To get a test to pass,you may need to insert a few parenthesis in the
 125 expected output; for example
 126
 127   -a/2;
 128   -(a/2)$
 129
 130 Another way to handle such things is to use explicit calls to ratsimp:
 131
 132   ratsimp(-a/2);
 133   ''(ratsimp(-a/2))$
 134
 135 To test a function such as factor, you do not want to apply ratsimp.
 136
 137