Provided by: erlang-manpages_25.3.2.8+dfsg-1ubuntu4_all bug

NAME

       ct_property_test - Support in Common Test for running property-based tests.

DESCRIPTION

       This module helps running property-based tests in the Common Test framework. One (or more)
       of the property testing tools

         * QuickCheck,

         * PropEr or

         * Triq

       is assumed to be installed.

       The idea with this module is to have a Common Test test suite calling a  property  testing
       tool with special property test suites as defined by that tool. The tests are collected in
       the  test  directory  of  the  application.  The  test  directory   has   a   subdirectory
       property_test,  where  everything  needed  for the property tests are collected. The usual
       Erlang application directory structure is assumed.

       A typical Common Test test suite using ct_property_test is organized as follows:

       -module(my_prop_test_SUITE).
       -compile(export_all).

       -include_lib("common_test/include/ct.hrl").

        all() -> [prop_ftp_case].

        init_per_suite(Config) ->
            ct_property_test:init_per_suite(Config).

        %%%---- test case
        prop_ftp_case(Config) ->
            ct_property_test:quickcheck(
              ftp_simple_client_server:prop_ftp(),
              Config
             ).

       and the the property test module (in this example ftp_simple_client_server.erl) as  almost
       a usual property testing module (More examples are in the User's Guide):

       -module(ftp_simple_client_server).
       -export([prop_ftp/0...]).

       -include_lib("common_test/include/ct_property_test.hrl").

       prop_ftp() ->
           ?FORALL( ....

EXPORTS

       init_per_suite(Config) -> Config | {skip, Reason}

              Initializes and extends Config for property based testing.

              This function investigates if support is available for either QuickCheck, PropEr or
              Triq and compiles the properties with the first tool found. It is  supposed  to  be
              called in the init_per_suite/1 function in a CommonTest test suite.

              Which  tools  to  check  for,  and  in  which  order  could  be set with the option
              {prop_tools, list(eqc|proper|triq)} in the  CommonTest  configuration  Config.  The
              default value is [eqc, proper, triq] with eqc being the first one searched for.

              If no support is found for any tool, this function returns {skip, Explanation}.

              If  support  is found, the option {property_test_tool,ToolModule} with the selected
              tool main module name (eqc, proper or triq) is added to the list Config which  then
              is returned.

              The  property  tests  are  assumed to be in a subdirectory named property_test. All
              found Erlang files in that directory are compiled with one  of  the  macros  'EQC',
              'PROPER'  or  'TRIQ'  set,  depending on which tool that is first found. This could
              make parts of the Erlang property tests code to be included or  excluded  with  the
              macro directives -ifdef(Macro). or -ifndef(Macro)..

              The  file(s)  in  the  property_test  subdirectory  could,  or  should, include the
              ct_property_test include file:

              -include_lib("common_test/include/ct_property_test.hrl").

              This included file will:

                * Include the correct tool's include file

                * Set the macro 'MOD_eqc' to the correct module name for the selected tool.  That
                  is, the macro 'MOD_eqc' is set to either eqc, proper or triq.

       quickcheck(Property, Config) -> true | {fail, Reason}

              Calls  the  selected tool's function for running the Property. It is usually and by
              historical reasons called quickcheck, and that is why that name  is  used  in  this
              module (ct_property_test).

              The result is returned in a form suitable for Common Test test suites.

              This function is intended to be called in test cases in test suites.

       present_result(Module, Cmds, Triple, Config) -> Result

              Same as present_result(Module, Cmds, Triple, Config, [])

       present_result(Module, Cmds, Triple, Config, Options) -> Result

              Types:

                 Module = module()

                 Cmds =
                   the  list  of  commands generated by the property testing tool, for example by
                   proper:commands/1 or by proper:parallel_commands/1
                 Triple =
                   the     output     from     for     example      proper:run_commands/2      or
                   proper:run_parallel_commands/2
                 Config =
                   the Common Test Config in test cases.
                 Options = [present_option()]
                 present_option() = {print_fun, fun(Format,Args)}
                  | {spec, StatisticsSpec}
                   The print_fun defines which function to do the actual printout. The default is
                   ct:log/2. The spec defines what statistics are to be printed
                 Result = boolean()
                   Is false if the test failed and is true if the test passed

              Presents the result of stateful (statem)  property  testing   using  the  aggregate
              function in PropEr, QuickCheck or other similar property testing tool.

              It is assumed to be called inside the property called by quickcheck/2:

              ...
              RunResult = run_parallel_commands(?MODULE, Cmds),
              ct_property_test:present_result(?MODULE, Cmds, RunResult, Config)
              ...

              See the User's Guide for an example of the usage and of the default printout.

              The StatisticsSpec is a list of the tuples:

                * {Title::string(), CollectFun::fun/1}

                * {Title::string(), FrequencyFun::/0, CollectFun::fun/1}

              Each tuple will produce one table in the order of their places in the list.

                * Title will be the title of one result table

                * CollectFun  is  called  with one argument: the Cmds. It should return a list of
                  the values to be counted. The following pre-defined functions exist:

                  * ct_property_test:cmnd_names/1 returns a list  of  commands  (function  calls)
                    generated in the Cmnd sequence, without Module, Arguments and other details.

                  * ct_property_test:num_calls/1 returns a list of the length of commands lists

                  * ct_property_test:sequential_parallel/1  returns a list with information about
                    sequential and parallel parts from Tool:parallel_commands/1,2

                * FrequencyFun/0 returns a fun/1 which is supposed to take a  list  of  items  as
                  input,  and  return  an iolist which will be printed as the table. Per default,
                  the number of each item is counted and the percentage is printed for each.  The
                  list [a,b,a,a,c] could for example return

                 ["a 60%\n","b 20%\n","c 20%\n"]

                 a 60%
                 b 20%
                 c 20%

              The default StatisticsSpec is:

                * For sequential commands:

                [{"Function calls", fun cmnd_names/1},
                 {"Length of command sequences", fun print_frequency_ranges/0,
                                                                  fun num_calls/1}]

                * For parallel commands:

                [{"Distribution sequential/parallel", fun sequential_parallel/1},
                 {"Function calls", fun cmnd_names/1},
                 {"Length of command sequences", fun print_frequency_ranges/0,
                                                                  fun num_calls/1}]