1This directory contains the test suite of Mnesia. 2Compile it with "erl -make". 3 4Test cases are identified with a {Mod, Fun} tuple that maps 5to a function Mod:Fun(Config), where the test case hopefully 6is implemented. The test suite is organized in a hierarchy 7with {mnesia_SUITE, all} as the top. 8 9The module called mt, implements various convenience functions 10to ease up the execution of test cases. It does also provide 11aliases for some test cases. For example the atom Mod is an 12alias for {Mod, all}, the atom all for {mnesia_SUITE, all}, 13evil for mnesia_evil_coverage_test etc. 14 15 mt:struct(TestCase) 16 17 Displays the test case structure from TestCase 18 and downwards the hierarchy. E.g. mt:struct(all) 19 will display the entire test suite. 20 21 mt:t(TestCase), mt:t(TestCase, Config) 22 23 Runs a single test case or a hierarchy of test cases. 24 mt:t(silly) is be a good starter, but you may also 25 try mt:t(all) directly if you feel lucky. 26 27 The identity of the last run test case and the outcome of 28 it is stored on file. mt:t() will re-run the last test case. 29 30 The Config argument contains various configuration 31 parameters for the test cases, such as which nodes that 32 are available for running the test suite. The default 33 settings should be enough for the most. Use mt:read_config() 34 to get the current default setting and change it with 35 mt:write_config(Config). 36 37 mt:doc(TestCase) 38 39 Generates html documentation for the test suite. 40 41In order to be able to run the test suite, the Erlang node must 42be started with the distribution enabled and the code path must 43be set to the mnesia/ebin, mnesia/examples, and mnesia/test 44directories. E.g. the following would do: 45 46 erl -sname a -pa $top/examples -pa $top/src -pa $top/ebin 47 48where $top is the path to the Mnesia installation. Many test 49cases needs 2 or 3 nodes. The node names may explicitly be 50stated as test suite configuration parameters, but by default 51the extra node names are generated. In this example the names 52will be: a, a1 and a2. It is enough to start the first node 53manually, the extra nodes will automatically be started if 54necessary. 55 56The attached UNIX shell script mt, does not work on all 57platforms, but it may be used as a source for inspiration. It 58starts three Erlang nodes in one xterm's each. The main xterm 59(a@localhost) logs all output in the Erlang shell to a 60file. The file is piped thru grep to easily find successful 61test cases (i.e. test cases that encountered an error). 62 63During development we want to be able to run the test cases 64in the debugger. This demands a little bit of preparations: 65 66 - Start the necessary number of nodes (normally 3). 67 This may either be done by running the mt script or 68 by starting the main node and then invoke mt:start_nodes() 69 to start the extra nodes with slave. 70 71 - Ensure that the nodes are connected. The easiest way to do 72 this is by invoking mt:ping(). 73 74 - Load all files that needs to be interpreted. This is typically 75 all Mnesia files plus the test case. By invoking mnesia:ni() 76 and mnesia:ni([TestModule]) the necessary modules will be 77 loaded on all CONNECTED nodes. 78 79The test case execution is supervised in order to ensure that no test 80case exceeds its maximum time limit, which by default is 5 minutes. 81When the limit is reached, the running test case gets aborted and the 82test server runs the next test case in line. This behaviour is useful 83when running the entire test suite during the night, but it is really 84annoying during debugging. 85 86 Use the "erl -mnesia_test_timeout" flag to disable the test case 87 time limit mechanism. 88 89Some mechanisms in Mnesia are almost impossible to test with a 90white box technique. In order to be able to write predictable 91test cases which tests the same thing every time it is run, 92Mnesia has been instrumented with debug functions. These may be 93controlled from a test program. For example to verify that the 94commit protocols work it is essential that it is possible to 95ensure that we are able to kill Mnesia in the most critical 96situations. Normally Mnesia is compiled with the debug 97functions disabled and this means that test cases which 98requires this functionality will be skipped. The mnesia:ni(), 99mentioned above, functions ensures that the interpreted code is 100instrumented with Mnesia's debug functionality. The mnesia:nc() 101functions compiles Mnesia with the debug setting enabled. 102 103Happy bug hunting! 104 105 Hakan Mattsson <hakan@erix.ericsson.se> 106 107 108