1ct_property_test(3)        Erlang Module Definition        ct_property_test(3)
2
3
4

NAME

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

DESCRIPTION

10       This module helps running  property-based  tests  in  the  Common  Test
11       framework. One (or more) of the property testing tools
12
13         * QuickCheck,
14
15         * PropEr or
16
17         * Triq
18
19       is assumed to be installed.
20
21       The idea with this module is to have a Common Test test suite calling a
22       property testing tool with special property test suites as  defined  by
23       that  tool. The tests are collected in the test directory of the appli‐
24       cation. The test directory has a subdirectory property_test, where  ev‐
25       erything  needed for the property tests are collected. The usual Erlang
26       application directory structure is assumed.
27
28       A typical Common Test test suite using ct_property_test is organized as
29       follows:
30
31       -module(my_prop_test_SUITE).
32       -compile(export_all).
33
34       -include_lib("common_test/include/ct.hrl").
35
36        all() -> [prop_ftp_case].
37
38        init_per_suite(Config) ->
39            ct_property_test:init_per_suite(Config).
40
41        %%%---- test case
42        prop_ftp_case(Config) ->
43            ct_property_test:quickcheck(
44              ftp_simple_client_server:prop_ftp(),
45              Config
46             ).
47
48       and   the   the   property   test  module  (in  this  example  ftp_sim‐
49       ple_client_server.erl) as almost a usual property testing module  (More
50       examples are in the User's Guide):
51
52       -module(ftp_simple_client_server).
53       -export([prop_ftp/0...]).
54
55       -include_lib("common_test/include/ct_property_test.hrl").
56
57       prop_ftp() ->
58           ?FORALL( ....
59
60

EXPORTS

62       init_per_suite(Config) -> Config | {skip, Reason}
63
64              Initializes and extends Config for property based testing.
65
66              This  function  investigates  if support is available for either
67              QuickCheck, PropEr or Triq and compiles the properties with  the
68              first   tool   found.  It  is  supposed  to  be  called  in  the
69              init_per_suite/1 function in a CommonTest test suite.
70
71              Which tools to check for, and in which order could be  set  with
72              the option {prop_tools, list(eqc|proper|triq)} in the CommonTest
73              configuration Config. The default value is [eqc,  proper,  triq]
74              with eqc being the first one searched for.
75
76              If  no  support  is  found  for  any tool, this function returns
77              {skip, Explanation}.
78
79              If support is found, the option  {property_test_tool,ToolModule}
80              with the selected tool main module name (eqc, proper or triq) is
81              added to the list Config which then is returned.
82
83              The property tests are assumed to be  in  a  subdirectory  named
84              property_test. All found Erlang files in that directory are com‐
85              piled with one of the macros 'EQC', 'PROPER' or 'TRIQ' set,  de‐
86              pending on which tool that is first found. This could make parts
87              of the Erlang property tests code to  be  included  or  excluded
88              with the macro directives -ifdef(Macro). or -ifndef(Macro)..
89
90              The  file(s) in the property_test subdirectory could, or should,
91              include the ct_property_test include file:
92
93              -include_lib("common_test/include/ct_property_test.hrl").
94
95
96              This included file will:
97
98                * Include the correct tool's include file
99
100                * Set the macro 'MOD_eqc' to the correct module name  for  the
101                  selected tool. That is, the macro 'MOD_eqc' is set to either
102                  eqc, proper or triq.
103
104       quickcheck(Property, Config) -> true | {fail, Reason}
105
106              Calls the selected tool's function for running the Property.  It
107              is usually and by historical reasons called quickcheck, and that
108              is why that name is used in this module (ct_property_test).
109
110              The result is returned in a form suitable for Common  Test  test
111              suites.
112
113              This  function  is  intended  to be called in test cases in test
114              suites.
115
116       present_result(Module, Cmds, Triple, Config) -> Result
117
118              Same as present_result(Module, Cmds, Triple, Config, [])
119
120       present_result(Module, Cmds, Triple, Config, Options) -> Result
121
122              Types:
123
124                 Module = module()
125
126                 Cmds =
127                   the list of commands  generated  by  the  property  testing
128                   tool,  for example by proper:commands/1 or by proper:paral‐
129                   lel_commands/1
130                 Triple =
131                   the  output  from  for  example  proper:run_commands/2   or
132                   proper:run_parallel_commands/2
133                 Config =
134                   the Common Test Config in test cases.
135                 Options = [present_option()]
136                 present_option() = {print_fun, fun(Format,Args)}
137                  | {spec, StatisticsSpec}
138                   The  print_fun  defines  which  function  to  do the actual
139                   printout. The default is ct:log/2. The  spec  defines  what
140                   statistics are to be printed
141                 Result = boolean()
142                   Is false if the test failed and is true if the test passed
143
144              Presents the result of stateful (statem) property testing  using
145              the aggregate function in PropEr, QuickCheck  or  other  similar
146              property testing tool.
147
148              It  is  assumed  to  be  called  inside  the  property called by
149              quickcheck/2:
150
151              RunResult = run_parallel_commands(?MODULE, Cmds),
152              ct_property_test:present_result(?MODULE, Cmds, RunResult, Config)
153
154
155              See the User's Guide for an example of the usage and of the  de‐
156              fault printout.
157
158              The StatisticsSpec is a list of the tuples:
159
160                * {Title::string(), CollectFun::fun/1}
161
162                * {Title::string(), FrequencyFun::/0, CollectFun::fun/1}
163
164              Each  tuple  will produce one table in the order of their places
165              in the list.
166
167                * Title will be the title of one result table
168
169                * CollectFun is called with one argument: the Cmds. It  should
170                  return  a  list  of  the values to be counted. The following
171                  pre-defined functions exist:
172
173                  * ct_property_test:cmnd_names/1 returns a list  of  commands
174                    (function  calls)  generated in the Cmnd sequence, without
175                    Module, Arguments and other details.
176
177                  * ct_property_test:num_calls/1 returns a list of the  length
178                    of commands lists
179
180                  * ct_property_test:sequential_parallel/1 returns a list with
181                    information  about  sequential  and  parallel  parts  from
182                    Tool:parallel_commands/1,2
183
184                * FrequencyFun/0  returns  a fun/1 which is supposed to take a
185                  list of items as input, and return an iolist  wich  will  be
186                  printed  as  the table. Per default, the number of each item
187                  is counted and the percentage is printed for each. The  list
188                  [a,b,a,a,c] could for example return
189
190                 ["a 60%\n","b 20%\n","c 20%\n"]
191
192                 a 60%
193                 b 20%
194                 c 20%
195
196              The default StatisticsSpec is:
197
198                * For sequential commands:
199
200                [{"Function calls", fun cmnd_names/1},
201                 {"Length of command sequences", fun print_frequency_ranges/0,
202                                                                  fun num_calls/1}]
203
204
205                * For parallel commands:
206
207                [{"Distribution sequential/parallel", fun sequential_parallel/1},
208                 {"Function calls", fun cmnd_names/1},
209                 {"Length of command sequences", fun print_frequency_ranges/0,
210                                                                  fun num_calls/1}]
211
212
213Ericsson AB                    common_test 1.21            ct_property_test(3)
Impressum