1ct_property_test(3) Erlang Module Definition ct_property_test(3)
2
6 ct_property_test - Support in Common Test for running property-based
7 tests.
8
10 This module helps running property-based tests in the Common Test
11 framework. One (or more) of the property testing tools
12 * QuickCheck,
14 * PropEr or
16 * Triq
18 is assumed to be installed.
20 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
25 everything needed for the property tests are collected. The usual
26 Erlang application directory structure is assumed.
27 A typical Common Test test suite using ct_property_test is organized as
29 follows:
30 -module(my_prop_test_SUITE).
32 -compile(export_all).
33 -include_lib("common_test/include/ct.hrl").
35 all() -> [prop_ftp_case].
37 init_per_suite(Config) ->
39 ct_property_test:init_per_suite(Config).
40 %%%---- test case
42 prop_ftp_case(Config) ->
43 ct_property_test:quickcheck(
44 ftp_simple_client_server:prop_ftp(),
45 Config
46 ).
47 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 -module(ftp_simple_client_server).
53 -export([prop_ftp/0...]).
54 -include_lib("common_test/include/ct_property_test.hrl").
56 prop_ftp() ->
58 ?FORALL( ....
59
62 init_per_suite(Config) -> Config | {skip, Reason}
63 Initializes and extends Config for property based testing.
65 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 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 If no support is found for any tool, this function returns
77 {skip, Explanation}.
78 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 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,
86 depending on which tool that is first found. This could make
87 parts of the Erlang property tests code to be included or
88 excluded with the macro directives -ifdef(Macro). or -ifn‐
89 def(Macro)..
90 The file(s) in the property_test subdirectory could, or should,
92 include the ct_property_test include file:
93 -include_lib("common_test/include/ct_property_test.hrl").
95 This included file will:
98 * Include the correct tool's include file
100 * Set the macro 'MOD_eqc' to the correct module name for the
102 selected tool. That is, the macro 'MOD_eqc' is set to either
103 eqc, proper or triq.
104 quickcheck(Property, Config) -> true | {fail, Reason}
106 Calls the selected tool's function for running the Property. It
108 is usually and by historical reasons called quickcheck, and that
109 is why that name is used in this module (ct_property_test).
110 The result is returned in a form suitable for Common Test test
112 suites.
113 This function is intended to be called in test cases in test
115 suites.
116 present_result(Module, Cmds, Triple, Config) -> Result
118 Same as present_result(Module, Cmds, Triple, Config, [])
120 present_result(Module, Cmds, Triple, Config, Options) -> Result
122 Types:
124 Module = module()
126 Cmds =
128 the list of commands generated by the property testing
129 tool, for example by proper:commands/1 or by proper:paral‐
130 lel_commands/1
131 Triple =
132 the output from for example proper:run_commands/2 or
133 proper:run_parallel_commands/2
134 Config =
135 the Common Test Config in test cases.
136 Options = [present_option()]
137 present_option() = {print_fun, fun(Format,Args)}
138 | {spec, StatisticsSpec}
139 The print_fun defines which function to do the actual
140 printout. The default is ct:log/2. The spec defines what
141 statistics are to be printed
142 Result = boolean()
143 Is false if the test failed and is true if the test passed
144 Presents the result of stateful (statem) property testing using
146 the aggregate function in PropEr, QuickCheck or other similar
147 property testing tool.
148 It is assumed to be called inside the property called by
150 quickcheck/2:
151 RunResult = run_parallel_commands(?MODULE, Cmds),
153 ct_property_test:present_result(?MODULE, Cmds, RunResult, Config)
154 See the User's Guide for an example of the usage and of the
157 default printout.
158 The StatisticsSpec is a list of the tuples:
160 * {Title::string(), CollectFun::fun/1}
162 * {Title::string(), FrequencyFun::/0, CollectFun::fun/1}
164 Each tuple will produce one table in the order of their places
166 in the list.
167 * Title will be the title of one result table
169 * CollectFun is called with one argument: the Cmds. It should
171 return a list of the values to be counted. The following
172 pre-defined functions exist:
173 * ct_property_test:cmnd_names/1 returns a list of commands
175 (function calls) generated in the Cmnd sequence, without
176 Module, Arguments and other details.
177 * ct_property_test:num_calls/1 returns a list of the length
179 of commands lists
180 * ct_property_test:sequential_parallel/1 returns a list with
182 information about sequential and parallel parts from
183 Tool:parallel_commands/1,2
184 * FrequencyFun/0 returns a fun/1 which is supposed to take a
186 list of items as input, and return an iolist wich will be
187 printed as the table. Per default, the number of each item
188 is counted and the percentage is printed for each. The list
189 [a,b,a,a,c] could for example return
190 ["a 60%\n","b 20%\n","c 20%\n"]
192 a 60%
194 b 20%
195 c 20%
196 The default StatisticsSpec is:
198 * For sequential commands:
200 [{"Function calls", fun cmnd_names/1},
202 {"Length of command sequences", fun print_frequency_ranges/0,
203 fun num_calls/1}]
204 * For parallel commands:
207 [{"Distribution sequential/parallel", fun sequential_parallel/1},
209 {"Function calls", fun cmnd_names/1},
210 {"Length of command sequences", fun print_frequency_ranges/0,
211 fun num_calls/1}]
212Ericsson AB common_test 1.20 ct_property_test(3)