← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/common_test/doc/src/ct_hooks.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/common_test/doc/src/ct_hooks.xml
 
1
<?xml version="1.0" encoding="UTF-8" ?>
 
2
 
 
3
<!DOCTYPE erlref SYSTEM "erlref.dtd">
 
4
 
 
5
<erlref>
 
6
  <header>
 
7
    <copyright>
 
8
      <year>2010</year><year>2011</year>
 
9
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
      The contents of this file are subject to the Erlang Public License,
 
13
      Version 1.1, (the "License"); you may not use this file except in
 
14
      compliance with the License. You should have received a copy of the
 
15
      Erlang Public License along with this software. If not, it can be
 
16
      retrieved online at http://www.erlang.org/.
 
17
 
 
18
      Software distributed under the License is distributed on an "AS IS"
 
19
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
      the License for the specific language governing rights and limitations
 
21
      under the License.
 
22
 
 
23
    </legalnotice>
 
24
 
 
25
    <title>Common Test Hooks</title>
 
26
    <prepared>Lukas Larsson</prepared>
 
27
    <responsible>Lukas Larsson</responsible>
 
28
    <docno></docno>
 
29
    <approved></approved>
 
30
    <checked></checked>
 
31
    <date>2010-12-02</date>
 
32
    <rev>PA1</rev>
 
33
    <file>ct_hooks.sgml</file>
 
34
  </header>
 
35
  <module>ct_hooks</module> 
 
36
  <modulesummary>A callback interface on top of Common Test</modulesummary>
 
37
 
 
38
  <description>
 
39
 
 
40
    <warning><p>This feature is in alpha release right now. This means that the 
 
41
        interface may change in the future and that there may be bugs. We 
 
42
        encourage you to use this feature, but be prepared 
 
43
        that there might be bugs and that the interface might change
 
44
        inbetween releases.</p></warning>
 
45
 
 
46
    <p>The <em>Common Test Hook</em> (henceforth called CTH) framework allows 
 
47
      extensions of the default behaviour of Common Test by means of callbacks 
 
48
      before and after all test suite calls. It is meant for advanced users of
 
49
      Common Test which want to abstract out behaviour which is common to
 
50
      multiple test suites. </p>
 
51
 
 
52
    <p>In brief, Common Test Hooks allows you to:</p>
 
53
 
 
54
    <list>
 
55
      <item>Manipulate the runtime config before each suite 
 
56
      configuration call</item>
 
57
      <item>Manipulate the return of all suite configuration calls and in 
 
58
      extension the result of the test themselves.</item>
 
59
    </list>
 
60
    
 
61
    <p>The following sections describe the mandatory and optional CTH
 
62
    functions Common Test will call during test execution. For more details
 
63
    see <seealso marker="ct_hooks_chapter">Common Test Hooks</seealso> in 
 
64
    the User's Guide.</p>
 
65
 
 
66
    <p>For information about how to add a CTH to your suite see 
 
67
    <seealso marker="ct_hooks_chapter#installing">Installing a CTH
 
68
    </seealso> in the User's Guide.</p>
 
69
 
 
70
    <note><p>See the
 
71
        <seealso marker="ct_hooks_chapter#example">Example CTH</seealso>
 
72
        in the User's Guide for a minimal example of a CTH. </p></note>
 
73
    
 
74
  </description>
 
75
 
 
76
  <section>
 
77
    <title>CALLBACK FUNCTIONS</title>
 
78
    <p>The following functions define the callback interface
 
79
      for a Common Test Hook.</p>
 
80
  </section>
 
81
  
 
82
  <funcs>
 
83
    <func>
 
84
      <name>Module:init(Id, Opts) -&gt; State</name>
 
85
      <fsummary>Initiates the Common Test Hook</fsummary>
 
86
      <type>
 
87
        <v>Id = reference() | term()</v>
 
88
        <v>Opts = term()</v>
 
89
        <v>State = term()</v>
 
90
      </type>
 
91
      
 
92
      <desc>    
 
93
        <p> MANDATORY </p>
 
94
 
 
95
        <p>Always called before any other callback function. 
 
96
          Use this to initiate any common state. 
 
97
          It should return a state for this CTH.</p>
 
98
 
 
99
        <p><c>Id</c> is the return value of 
 
100
          <seealso marker="#Module:id-1">id/1</seealso>, or a <c>reference</c>
 
101
          (created using 
 
102
          <seealso marker="erts:erlang#make_ref-0">make_ref/0</seealso>)
 
103
          if <seealso marker="#Module:id-1">id/1</seealso> is not implemented.
 
104
        </p>
 
105
 
 
106
        <p>For details about when init is called see
 
107
          <seealso marker="ct_hooks_chapter#scope">scope</seealso>
 
108
          in the User's Guide.</p>
 
109
              
 
110
      </desc>
 
111
    </func>
 
112
 
 
113
    <func>
 
114
      <name>Module:pre_init_per_suite(SuiteName, Config, CTHState) -&gt; 
 
115
              Result</name>
 
116
      <fsummary>Called before init_per_suite</fsummary>
 
117
      <type>
 
118
        <v>SuiteName = atom()</v>
 
119
        <v>Config = NewConfig = [{Key,Value}]</v>
 
120
        <v>CTHState = NewCTHState = term()</v>
 
121
        <v>Result = {Return, NewCTHState}</v>
 
122
        <v>Return = NewConfig | SkipOrFail</v>
 
123
        <v>SkipOrFail = {fail, Reason} | {skip, Reason}</v>
 
124
        <v>Key = atom()</v>
 
125
        <v>Value = term()</v>
 
126
        <v>Reason = term()</v>
 
127
      </type>
 
128
      
 
129
      <desc>    
 
130
        <p> OPTIONAL </p>
 
131
 
 
132
        <p>This function is called before 
 
133
        <seealso marker="common_test#Module:init_per_suite-1">
 
134
          init_per_suite</seealso> if it exists. 
 
135
        It typically contains initialization/logging which needs to be done 
 
136
        before init_per_suite is called. 
 
137
        If <c>{skip,Reason}</c> or <c>{fail,Reason}</c> is returned, 
 
138
        init_per_suite and all test cases of the suite will be skipped and
 
139
        Reason printed in the overview log of the suite.</p>
 
140
        
 
141
        <p><c>SuiteName</c> is the name of the suite to be run.</p>
 
142
 
 
143
        <p><c>Config</c> is the original config list of the test suite.</p>
 
144
 
 
145
        <p><c>CTHState</c> is the current internal state of the CTH.</p>
 
146
 
 
147
        <p><c>Return</c> is the result of the init_per_suite function.
 
148
        If it is <c>{skip,Reason}</c> or <c>{fail,Reason}</c> 
 
149
        <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
 
150
        </seealso> will never be called, instead the initiation is considered 
 
151
        to be skipped/failed respectively. If a <c>NewConfig</c> list
 
152
        is returned, <seealso marker="common_test#Module:init_per_suite-1">
 
153
        init_per_suite</seealso> will be called with that <c>NewConfig</c> list.
 
154
        See <seealso marker="ct_hooks_chapter#pre">
 
155
        Pre Hooks</seealso> in the User's Guide for more details.</p>
 
156
        
 
157
        
 
158
        <p>Note that this function is only called if the CTH has been added 
 
159
        before init_per_suite is run, see 
 
160
        <seealso marker="ct_hooks_chapter#scope">CTH Scoping</seealso> 
 
161
        in the User's Guide for details.</p>
 
162
      </desc>
 
163
    </func>
 
164
    
 
165
    <func>
 
166
      <name>Module:post_init_per_suite(SuiteName, Config, Return, CTHState) -&gt; 
 
167
              Result</name>
 
168
      <fsummary>Called after init_per_suite</fsummary>
 
169
      <type>
 
170
        <v>SuiteName = atom()</v>
 
171
        <v>Config = [{Key,Value}]</v>
 
172
        <v>Return = NewReturn = Config | SkipOrFail | term()</v>
 
173
        <v>SkipOrFail = {fail, Reason} | {skip, Reason} | term()</v>
 
174
        <v>CTHState = NewCTHState = term()</v>
 
175
        <v>Result = {NewReturn, NewCTHState}</v>
 
176
        <v>Key = atom()</v>
 
177
        <v>Value = term()</v>
 
178
        <v>Reason = term()</v>
 
179
      </type>
 
180
      
 
181
      <desc>    
 
182
        <p> OPTIONAL </p>
 
183
 
 
184
        <p>This function is called after
 
185
        <seealso marker="common_test#Module:init_per_suite-1">
 
186
          init_per_suite</seealso> if it exists. It typically contains extra 
 
187
        checks to make sure that all the correct dependencies have
 
188
        been started correctly.</p>
 
189
        
 
190
        <p><c>Return</c> is what 
 
191
        <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
 
192
        </seealso> returned, i.e. {fail,Reason}, {skip,Reason}, a <c>Config</c>
 
193
        list or a term describing how 
 
194
        <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
 
195
        </seealso> failed.</p>
 
196
 
 
197
        <p><c>NewReturn</c> is the possibly modified return value of
 
198
        <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
 
199
        </seealso>. It is here possible to recover from a failure in 
 
200
        <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
 
201
        </seealso> by returning the <c>ConfigList</c> with the <c>tc_status</c>
 
202
        element removed. See <seealso marker="ct_hooks_chapter#post">
 
203
        Post Hooks</seealso> in the User's Guide for more details.</p>
 
204
 
 
205
        <p><c>CTHState</c> is the current internal state of the CTH.</p>
 
206
 
 
207
        <p>Note that this function is only called if the CTH has been added 
 
208
        before or in init_per_suite, see 
 
209
        <seealso marker="ct_hooks_chapter#scope">CTH Scoping</seealso> 
 
210
        in the User's Guide for details.</p>
 
211
      </desc>
 
212
    </func>
 
213
    
 
214
    <func>
 
215
      <name>Module:pre_init_per_group(GroupName, Config, CTHState) -&gt; 
 
216
              Result</name>
 
217
      <fsummary>Called before init_per_group</fsummary>
 
218
      <type>
 
219
        <v>GroupName = atom()</v>
 
220
        <v>Config = NewConfig = [{Key,Value}]</v>
 
221
        <v>CTHState = NewCTHState = term()</v>
 
222
        <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
 
223
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
224
        <v>Key = atom()</v>
 
225
        <v>Value = term()</v>
 
226
        <v>Reason = term()</v>
 
227
      </type>
 
228
      
 
229
      <desc>    
 
230
        <p> OPTIONAL </p>
 
231
        
 
232
        <p>This function is called before
 
233
        <seealso marker="common_test#Module:init_per_group-2">
 
234
          init_per_group</seealso> if it exists. It behaves the same way as 
 
235
        <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
 
236
        pre_init_per_suite</seealso>, but for the
 
237
        <seealso marker="common_test#Module:init_per_group-2">
 
238
        init_per_group</seealso> instead.</p>
 
239
      </desc>
 
240
    </func>
 
241
    
 
242
    <func>
 
243
      <name>Module:post_init_per_group(GroupName, Config, Return, CTHState) -&gt; 
 
244
              Result</name>
 
245
      <fsummary>Called after init_per_group</fsummary>
 
246
      <type>
 
247
        <v>GroupName = atom()</v>
 
248
        <v>Config = [{Key,Value}]</v>
 
249
        <v>Return = NewReturn = Config | SkipOrFail | term()</v>
 
250
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
251
        <v>CTHState = NewCTHState = term()</v>
 
252
        <v>Result = {NewReturn, NewCTHState}</v>
 
253
        <v>Key = atom()</v>
 
254
        <v>Value = term()</v>
 
255
        <v>Reason = term()</v>
 
256
      </type>
 
257
      
 
258
      <desc>    
 
259
        <p> OPTIONAL </p>
 
260
 
 
261
        <p>This function is called after
 
262
        <seealso marker="common_test#Module:init_per_group-2">
 
263
          init_per_group</seealso> if it exists. It behaves the same way as 
 
264
        <seealso marker="ct_hooks#Module:post_init_per_suite-4">
 
265
        post_init_per_suite</seealso>, but for the
 
266
        <seealso marker="common_test#Module:init_per_group-2">
 
267
        init_per_group</seealso> instead.</p>
 
268
      </desc>
 
269
    </func>
 
270
 
 
271
    <func>
 
272
      <name>Module:pre_init_per_testcase(TestcaseName, Config, CTHState) -&gt; 
 
273
              Result</name>
 
274
      <fsummary>Called before init_per_testcase</fsummary>
 
275
      <type>
 
276
        <v>TestcaseName = atom()</v>
 
277
        <v>Config = NewConfig = [{Key,Value}]</v>
 
278
        <v>CTHState = NewCTHState = term()</v>
 
279
        <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
 
280
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
281
        <v>Key = atom()</v>
 
282
        <v>Value = term()</v>
 
283
        <v>Reason = term()</v>
 
284
      </type>
 
285
      
 
286
      <desc>    
 
287
        <p> OPTIONAL </p>
 
288
 
 
289
        <p>This function is called before
 
290
        <seealso marker="common_test#Module:init_per_testcase-2">
 
291
          init_per_testcase</seealso> if it exists. It behaves the same way as 
 
292
        <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
 
293
        pre_init_per_suite</seealso>, but for the
 
294
        <seealso marker="common_test#Module:init_per_testcase-2">
 
295
        init_per_testcase</seealso> function instead.</p>
 
296
 
 
297
        <p>Note that it is not possible to add CTH's here right now, 
 
298
        that feature might be added later, 
 
299
        but it would right now break backwards compatability.</p>
 
300
      </desc>
 
301
    </func>
 
302
 
 
303
    <func>
 
304
      <name>Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState)
 
305
               -&gt; Result</name>
 
306
      <fsummary>Called after end_per_testcase</fsummary>
 
307
      <type>
 
308
        <v>TestcaseName = atom()</v>
 
309
        <v>Config = [{Key,Value}]</v>
 
310
        <v>Return = NewReturn = Config | SkipOrFail | term()</v>
 
311
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
312
        <v>CTHState = NewCTHState = term()</v>
 
313
        <v>Result = {NewReturn, NewCTHState}</v>
 
314
        <v>Key = atom()</v>
 
315
        <v>Value = term()</v>
 
316
        <v>Reason = term()</v>
 
317
      </type>
 
318
      
 
319
      <desc>    
 
320
        <p> OPTIONAL </p>
 
321
 
 
322
        <p>This function is called after
 
323
        <seealso marker="common_test#Module:end_per_testcase-2">
 
324
          end_per_testcase</seealso> if it exists. It behaves the same way as 
 
325
        <seealso marker="ct_hooks#Module:post_init_per_suite-4">
 
326
        post_init_per_suite</seealso>, but for the
 
327
        <seealso marker="common_test#Module:end_per_testcase-2">
 
328
        end_per_testcase</seealso> function instead.</p>
 
329
      </desc>
 
330
    </func>
 
331
 
 
332
    <func>
 
333
      <name>Module:pre_end_per_group(GroupName, Config, CTHState) -&gt; 
 
334
              Result</name>
 
335
      <fsummary>Called before end_per_group</fsummary>
 
336
      <type>
 
337
        <v>GroupName = atom()</v>
 
338
        <v>Config = NewConfig = [{Key,Value}]</v>
 
339
        <v>CTHState = NewCTHState = term()</v>
 
340
        <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
 
341
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
342
        <v>Key = atom()</v>
 
343
        <v>Value = term()</v>
 
344
        <v>Reason = term()</v>
 
345
      </type>
 
346
      
 
347
      <desc>    
 
348
        <p> OPTIONAL </p>
 
349
        
 
350
        <p>This function is called before
 
351
        <seealso marker="common_test#Module:end_per_group-2">
 
352
        end_per_group</seealso> if it exists. It behaves the same way as 
 
353
        <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
 
354
        pre_init_per_suite</seealso>, but for the
 
355
        <seealso marker="common_test#Module:end_per_group-2">
 
356
        end_per_group</seealso> function instead.</p>
 
357
      </desc>
 
358
    </func>
 
359
 
 
360
    <func>
 
361
      <name>Module:post_end_per_group(GroupName, Config, Return, CTHState) -&gt; 
 
362
              Result</name>
 
363
      <fsummary>Called after end_per_group</fsummary>
 
364
      <type>
 
365
        <v>GroupName = atom()</v>
 
366
        <v>Config = [{Key,Value}]</v>
 
367
        <v>Return = NewReturn = Config | SkipOrFail | term()</v>
 
368
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
369
        <v>CTHState = NewCTHState = term()</v>
 
370
        <v>Result = {NewReturn, NewCTHState}</v>
 
371
        <v>Key = atom()</v>
 
372
        <v>Value = term()</v>
 
373
        <v>Reason = term()</v>
 
374
      </type>
 
375
      
 
376
      <desc>    
 
377
        <p> OPTIONAL </p>
 
378
 
 
379
        <p>This function is called after
 
380
        <seealso marker="common_test#Module:end_per_group-2">
 
381
          end_per_group</seealso> if it exists. It behaves the same way as 
 
382
        <seealso marker="ct_hooks#Module:post_init_per_suite-4">
 
383
        post_init_per_suite</seealso>, but for the
 
384
        <seealso marker="common_test#Module:end_per_group-2">
 
385
        end_per_group</seealso> function instead.</p>
 
386
      </desc>
 
387
    </func>
 
388
 
 
389
    <func>
 
390
      <name>Module:pre_end_per_suite(SuiteName, Config, CTHState) -&gt; 
 
391
              Result</name>
 
392
      <fsummary>Called before end_per_suite</fsummary>
 
393
      <type>
 
394
        <v>SuiteName = atom()</v>
 
395
        <v>Config = NewConfig = [{Key,Value}]</v>
 
396
        <v>CTHState = NewCTHState = term()</v>
 
397
        <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
 
398
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
399
        <v>Key = atom()</v>
 
400
        <v>Value = term()</v>
 
401
        <v>Reason = term()</v>
 
402
      </type>
 
403
      
 
404
      <desc>    
 
405
        <p> OPTIONAL </p>
 
406
 
 
407
        <p>This function is called before
 
408
        <seealso marker="common_test#Module:end_per_suite-1">
 
409
          end_per_suite</seealso> if it exists. It behaves the same way as 
 
410
        <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
 
411
        pre_init_per_suite</seealso>, but for the
 
412
        <seealso marker="common_test#Module:end_per_suite-1">
 
413
        end_per_suite</seealso> function instead.</p>
 
414
      </desc>
 
415
    </func>
 
416
 
 
417
    <func>
 
418
      <name>Module:post_end_per_suite(SuiteName, Config, Return, CTHState) -&gt; 
 
419
              Result</name>
 
420
      <fsummary>Called after end_per_suite</fsummary>
 
421
      <type>
 
422
        <v>SuiteName = atom()</v>
 
423
        <v>Config = [{Key,Value}]</v>
 
424
        <v>Return = NewReturn = Config | SkipOrFail | term()</v>
 
425
        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
 
426
        <v>CTHState = NewCTHState = term()</v>
 
427
        <v>Result = {NewReturn, NewCTHState}</v>
 
428
        <v>Key = atom()</v>
 
429
        <v>Value = term()</v>
 
430
        <v>Reason = term()</v>
 
431
      </type>
 
432
      
 
433
      <desc>    
 
434
        <p> OPTIONAL </p>
 
435
 
 
436
        <p>This function is called after
 
437
        <seealso marker="common_test#Module:end_per_suite-1">
 
438
          end_per_suite</seealso> if it exists. It behaves the same way as 
 
439
        <seealso marker="ct_hooks#Module:post_init_per_suite-4">
 
440
        post_init_per_suite</seealso>, but for the
 
441
        <seealso marker="common_test#Module:end_per_suite-1">
 
442
        end_per_suite</seealso> function instead.</p>
 
443
      </desc>
 
444
    </func>
 
445
 
 
446
    <func>
 
447
      <name>Module:on_tc_fail(TestcaseName, Reason, CTHState) -&gt; 
 
448
              NewCTHState</name>
 
449
      <fsummary>Called after the CTH scope ends</fsummary>
 
450
      <type>
 
451
        <v>TestcaseName = init_per_suite | end_per_suite | 
 
452
                          init_per_group | end_per_group | atom()</v>
 
453
        <v>Reason = term()</v>
 
454
        <v>CTHState = NewCTHState = term()</v>
 
455
      </type>
 
456
      
 
457
      <desc>    
 
458
        <p> OPTIONAL </p>
 
459
 
 
460
        <p>This function is called whenever a testcase fails. 
 
461
        It is called after the post function has been called for 
 
462
        the testcase which failed. i.e. 
 
463
        if init_per_suite fails this function is called after 
 
464
        <seealso marker="#Module:post_init_per_suite-4">
 
465
          post_init_per_suite</seealso>, and if a testcase fails it is called 
 
466
          after <seealso marker="#Module:post_end_per_testcase-4">
 
467
          post_end_per_testcase</seealso>.</p>
 
468
 
 
469
        <p>The data which comes with the Reason follows the same format as the
 
470
        <seealso marker="event_handler_chapter#failreason">FailReason
 
471
        </seealso> in the <seealso marker="event_handler_chapter#tc_done">tc_done</seealso> event.
 
472
        See <seealso marker="event_handler_chapter#events">Event Handling
 
473
        </seealso> in the User's Guide for details.</p>
 
474
      </desc>
 
475
    </func>
 
476
 
 
477
    <func>
 
478
      <name>Module:on_tc_skip(TestcaseName, Reason, CTHState) -&gt; 
 
479
              NewCTHState</name>
 
480
      <fsummary>Called after the CTH scope ends</fsummary>
 
481
      <type>
 
482
        <v>TestcaseName = end_per_suite | init_per_group | 
 
483
                          end_per_group | atom()</v>
 
484
        <v>Reason = {tc_auto_skip | tc_user_skip, term()}</v>
 
485
        <v>CTHState = NewCTHState = term()</v>
 
486
      </type>
 
487
      
 
488
      <desc>    
 
489
        <p> OPTIONAL </p>
 
490
 
 
491
        <p>This function is called whenever a testcase is skipped. 
 
492
        It is called after the post function has been called for the 
 
493
        testcase which was skipped. 
 
494
        i.e. if init_per_group is skipped this function is called after 
 
495
        <seealso marker="#Module:post_init_per_suite-4">post_init_per_group
 
496
        </seealso>, and if a testcase is skipped it is called after 
 
497
        <seealso marker="#Module:post_end_per_testcase-4">post_end_per_testcase
 
498
        </seealso>.</p>
 
499
 
 
500
        <p>The data which comes with the Reason follows the same format as 
 
501
        <seealso marker="event_handler_chapter#tc_auto_skip">tc_auto_skip
 
502
        </seealso> and <seealso marker="event_handler_chapter#tc_user_skip">
 
503
        tc_user_skip</seealso> events.
 
504
        See <seealso marker="event_handler_chapter#events">Event Handling
 
505
        </seealso> in the User's Guide for details.</p>
 
506
      </desc>
 
507
    </func>
 
508
 
 
509
    <func>
 
510
      <name>Module:terminate(CTHState)</name>
 
511
      <fsummary>Called after the CTH scope ends</fsummary>
 
512
      <type>
 
513
        <v>CTHState = term()</v>
 
514
      </type>
 
515
      
 
516
      <desc>    
 
517
        <p> OPTIONAL </p>
 
518
 
 
519
        <p>This function is called at the end of a CTH's 
 
520
        <seealso marker="ct_hooks_chapter#scope">scope</seealso>. 
 
521
        </p>
 
522
      </desc>
 
523
    </func>
 
524
 
 
525
    <func>
 
526
      <name>Module:id(Opts) -&gt; Id</name>
 
527
      <fsummary>Called before the init function of a CTH</fsummary>
 
528
      <type>
 
529
        <v>Opts = term()</v>
 
530
        <v>Id = term()</v>
 
531
      </type>
 
532
      
 
533
      <desc>
 
534
        <p> OPTIONAL </p>
 
535
        
 
536
        <p>The <c>Id</c> is used to uniquely identify a CTH instance, 
 
537
        if two CTH's return the same <c>Id</c> the second CTH is ignored
 
538
        and subsequent calls to the CTH will only be made to the first
 
539
        instance. For more information see 
 
540
        <seealso marker="ct_hooks_chapter#installing">Installing a CTH
 
541
        </seealso> in the User's Guide.
 
542
        </p>
 
543
 
 
544
        <p>This function should NOT have any side effects as it might 
 
545
        be called multiple times by Common Test.</p>
 
546
        
 
547
        <p>If not implemented the CTH will act as if this function returned a
 
548
          call to <c>make_ref/0</c>.</p>
 
549
      </desc>
 
550
    </func>
 
551
 
 
552
  </funcs>
 
553
 
 
554
</erlref>
 
555
 
 
556