tests/README.how-to

   1 Suggestions and tips for writing test files
   2 Barton Willis
   3
   4 (1) 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 /tests/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 42 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 Also, you'll need to append the name of the test file to
  72 makefile.am. Finally, build Maxima and run the test suite. If all goes
  73 well, commit the new test file.
  74
  75 (9) Other:
  76
  77 (a) Check that your test runs multiple times without error. After
  78 appending a new test to Maxima's test suite, make sure that run_testsuite()
  79 runs multiple times without error.
  80
  81 (b) Always test the simple cases: abs(0), abs(0.0), abs(0.0b0), ... Also,
  82 check that functions work correctly for CRE expressions, arguments that
  83 contain '%i', empty lists, empty matrices, ... Thus always test
  84 the 'boundary' cases; these are things like max(), min(), apply("*",[]), ....
  85
  86 (c) Check the sourceforge bug list for all reported bugs for the functions(s)
  87 you are testing. Include tests for these bugs; also put a comment in your
  88 test file that references the bug report:
  89
  90 /*  See SF Bug #  771061 */
  91
  92 expand((vt . a^^(-1) . u+1)^^(-2));
  93 ((vt.a^^(-1).u)^^2+2*(vt.a^^(-1).u)+1)^^(-1)$
  94
  95 If a bug causes a fatal error, you'll need to exclude it from your test
  96 (or better, include it, but comment it out).
  97
  98 (d) It might be easier to place all known failures at the top of the
  99 file. With this policy, you can append new tests without updating the
 100 list of known failures in testsuite.lisp.
 101
 102 (e) If a test checks a not so well known identity, include a reference to the
 103 identity:
 104
 105 /* A&S 13.6.1 */
 106 hgfred([v+1/2],[2*v+1],2*%i*z);
 107 4^(v/2)*bessel_j(v,z)*gamma(v+1)*exp(%i*z)/z^v$
 108
 109 (f) Maxima evaluates the input, but only simplifies the expected output. Thus
 110 a test such as
 111
 112   makelist(sin(k * %pi),k,1,5);
 113   makelist(0,k,1,5)$
 114
 115 will fail. You'll need to write the test as either
 116
 117   makelist(sin(k * %pi),k,1,5);
 118   ''(makelist(0,k,1,5))$
 119
 120 or
 121
 122   makelist(sin(k * %pi),k,1,5);
 123   [0,0,0,0,0]$
 124
 125 To get a test to pass,you may need to insert a few parenthesis in the
 126 expected output; for example
 127
 128   -a/2;
 129   -(a/2)$
 130
 131 Another way to handle such things is to use explicit calls to ratsimp:
 132
 133   ratsimp(-a/2);
 134   ''(ratsimp(-a/2))$
 135
 136 To test a function such as factor, you do not want to apply ratsimp.
 137
 138
 139
 140