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 ev‐
25 erything needed for the property tests are collected. The usual Erlang
26 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, 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 The file(s) in the property_test subdirectory could, or should,
91 include the ct_property_test include file:
92 -include_lib("common_test/include/ct_property_test.hrl").
94 This included file will:
97 * Include the correct tool's include file
99 * 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 quickcheck(Property, Config) -> true | {fail, Reason}
105 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 The result is returned in a form suitable for Common Test test
111 suites.
112 This function is intended to be called in test cases in test
114 suites.
115 present_result(Module, Cmds, Triple, Config) -> Result
117 Same as present_result(Module, Cmds, Triple, Config, [])
119 present_result(Module, Cmds, Triple, Config, Options) -> Result
121 Types:
123 Module = module()
125 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 Presents the result of stateful (statem) property testing using
145 the aggregate function in PropEr, QuickCheck or other similar
146 property testing tool.
147 It is assumed to be called inside the property called by
149 quickcheck/2:
150 RunResult = run_parallel_commands(?MODULE, Cmds),
152 ct_property_test:present_result(?MODULE, Cmds, RunResult, Config)
153 See the User's Guide for an example of the usage and of the de‐
156 fault printout.
157 The StatisticsSpec is a list of the tuples:
159 * {Title::string(), CollectFun::fun/1}
161 * {Title::string(), FrequencyFun::/0, CollectFun::fun/1}
163 Each tuple will produce one table in the order of their places
165 in the list.
166 * Title will be the title of one result table
168 * 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 * 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 * ct_property_test:num_calls/1 returns a list of the length
178 of commands lists
179 * 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 * FrequencyFun/0 returns a fun/1 which is supposed to take a
185 list of items as input, and return an iolist which 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 ["a 60%\n","b 20%\n","c 20%\n"]
191 a 60%
193 b 20%
194 c 20%
195 The default StatisticsSpec is:
197 * For sequential commands:
199 [{"Function calls", fun cmnd_names/1},
201 {"Length of command sequences", fun print_frequency_ranges/0,
202 fun num_calls/1}]
203 * For parallel commands:
206 [{"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}]
211Ericsson AB common_test 1.24.0.1 ct_property_test(3)