tests/README.how-to

   1 Suggestions and tips for writing and running 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 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. For example,
  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 a test triggers an `asksign`,
  72 unfortunately, Maxima doesn't print the 'asksign` question and it might appear
  73 to stall while waiting for input. When Maxima appears to be stalled, enter a
  74 bogus expression such as `[;`. Doing so will allow you discover the test that
  75 triggers the 'asksign.'
  76
  77 Once your test file runs to completion, commit it.
  78
  79 (9) Other:
  80
  81 (a) Check that your test runs multiple times without error. After
  82 appending a new test to Maxima's test suite, make sure that run_testsuite()
  83 runs multiple times without error.
  84
  85 (b) Always test the simple cases: abs(0), abs(0.0), abs(0.0b0), and ... Also,
  86 check that functions work correctly for CRE expressions, arguments that
  87 contain '%i', empty lists, empty matrices, and ... Thus always test
  88 the 'boundary' cases; these are things like max(), min(), apply("*",[]), ....
  89
  90 (c) Check the Maxima bug list for all reported bugs for the functions(s)
  91 you are testing. Include tests for these bugs; also put a comment in your
  92 test file that references the bug report:
  93
  94 /* #358 expand dot expr; fatal error/FIX */
  95 expand((vt . a^^(-1) . u+1)^^(-2));
  96 ((vt.a^^(-1).u)^^2+2*(vt.a^^(-1).u)+1)^^(-1)$
  97
  98 If a bug causes a fatal error, you'll need to exclude it from your test
  99 (or better, include it, but comment it out).
 100
 101 (d) It might be easier to place all known failures at the top of the
 102 file. With this policy, you can append new tests without updating the
 103 list of known failures in testsuite.lisp.
 104
 105 (e) If a test checks a not so well known identity, include a reference to the
 106 identity:
 107
 108 /* A&S 13.6.1 */
 109 hgfred([v+1/2],[2*v+1],2*%i*z);
 110 4^(v/2)*bessel_j(v,z)*gamma(v+1)*exp(%i*z)/z^v$
 111
 112 (f) Maxima evaluates the input, but only simplifies the expected output. Thus
 113 a test such as
 114
 115   makelist(sin(k * %pi),k,1,5);
 116   makelist(0,k,1,5)$
 117
 118 will fail. You'll need to write the test as either
 119
 120   makelist(sin(k * %pi),k,1,5);
 121   ''(makelist(0,k,1,5))$
 122
 123 or
 124
 125   makelist(sin(k * %pi),k,1,5);
 126   [0,0,0,0,0]$
 127
 128 To get a test to pass, you may need to insert a few parenthesis in the
 129 expected output; for example
 130
 131   -a/2;
 132   -(a/2)$
 133
 134 Another way to handle such things is to use explicit calls to ratsimp:
 135
 136   ratsimp(-a/2);
 137   ''(ratsimp(-a/2))$
 138
 139 Of course, to test a function such as factor, you do not want to apply ratsimp.
 140
 141 (g) When the expected result is messy, I suggest that you *not* routinely use additional
 142 simplifications (ratsimp, factor, radcan, ...) to make the expected result
 143 nicer. Such simplifications can hide changes that might be useful for a developer to
 144 know about. Of course, the simplification functions need their own testing.