> %CopyrightBegin%
>
> SPDX-License-Identifier: Apache-2.0
>
> Copyright Ericsson AB 2010-2025. All Rights Reserved.
>
> Licensed under the Apache License, Version 2.0 (the "License");
> you may not use this file except in compliance with the License.
> You may obtain a copy of the License at
>
>     http://www.apache.org/licenses/LICENSE-2.0
>
> Unless required by applicable law or agreed to in writing, software
> distributed under the License is distributed on an "AS IS" BASIS,
> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the License for the specific language governing permissions and
> limitations under the License.
>
> %CopyrightEnd%

This directory contains the test suite of Mnesia.
Compile it with "erl -make".

Test cases are identified with a {Mod, Fun} tuple that maps
to a function Mod:Fun(Config), where the test case hopefully
is implemented. The test suite is organized in a hierarchy
with {mnesia_SUITE, all} as the top.

The module called mt, implements various convenience functions
to ease up the execution of test cases. It does also provide
aliases for some test cases. For example the atom Mod is an
alias for {Mod, all}, the atom all for {mnesia_SUITE, all},
evil for mnesia_evil_coverage_test etc.

   mt:struct(TestCase)

      Displays the test case structure from TestCase
      and downwards the hierarchy. E.g. mt:struct(all)
      will display the entire test suite.

   mt:t(TestCase), mt:t(TestCase, Config)

      Runs a single test case or a hierarchy of test cases.
      mt:t(silly) is be a good starter, but you may also
      try mt:t(all) directly if you feel lucky.

      The identity of the last run test case and the outcome of
      it is stored on file. mt:t() will re-run the last test case.

      The Config argument contains various configuration
      parameters for the test cases, such as which nodes that
      are available for running the test suite. The default
      settings should be enough for the most. Use mt:read_config()
      to get the current default setting and change it with
      mt:write_config(Config).

   mt:doc(TestCase)

      Generates html documentation for the test suite.

In order to be able to run the test suite, the Erlang node must
be started with the distribution enabled and the code path must
be set to the mnesia/ebin, mnesia/examples, and mnesia/test
directories. Running the following in this directory would do:

    top=$ERL_TOP/lib/mnesia
    erl -sname a -pa $top/examples -pa $top/src -pa $top/ebin

Many test cases need 2 or 3 nodes. The node names may explicitly
be stated as test suite configuration parameters, but by default
the extra node names are generated. In this example the names
will be: a, a1 and a2. It is enough to start the first node
manually, the extra nodes will automatically be started if
necessary.

The attached UNIX shell script mt, does not work on all
platforms, but it may be used as a source for inspiration. It
starts three Erlang nodes in one xterm's each. The main xterm
(a@localhost) logs all output in the Erlang shell to a
file. The file is piped thru grep to easily find successful
test cases (i.e. test cases that encountered an error).

During development we want to be able to run the test cases
in the debugger. This demands a little bit of preparations:

  - Start the necessary number of nodes (normally 3).
    This may either be done by running the mt script or
    by starting the main node and then invoke mt:start_nodes()
    to start the extra nodes with `peer`.

  - Ensure that the nodes are connected. The easiest way to do
    this is by invoking mt:ping().

  - Load all files that needs to be interpreted. This is typically
    all Mnesia files plus the test case. By invoking mnesia:ni()
    and mnesia:ni([TestModule]) the necessary modules will be
    loaded on all CONNECTED nodes.

The test case execution is supervised in order to ensure that no test
case exceeds its maximum time limit, which by default is 5 minutes.
When the limit is reached, the running test case gets aborted and the
test server runs the next test case in line. This behaviour is useful
when running the entire test suite during the night, but it is really
annoying during debugging.

   Use the "erl -mnesia_test_timeout" flag to disable the test case
   time limit mechanism.

Some mechanisms in Mnesia are almost impossible to test with a
white box technique. In order to be able to write predictable
test cases which tests the same thing every time it is run,
Mnesia has been instrumented with debug functions. These may be
controlled from a test program. For example to verify that the
commit protocols work it is essential that it is possible to
ensure that we are able to kill Mnesia in the most critical
situations. Normally Mnesia is compiled with the debug
functions disabled and this means that test cases which
require this functionality will be skipped. To compile mnesia
with debug functionality, (re-)compile it with erlc flag
"-Ddebug", for instance, with make:

    make clean
    make ERLC=$(pwd)/../../bin/erlc ERL_COMPILE_FLAGS="-Ddebug"

Happy bug hunting!

        Hakan Mattsson <hakan@erix.ericsson.se>


