← 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/event_handler_chapter.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/event_handler_chapter.xml
4
4
<chapter>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>2006</year><year>2009</year>
 
7
      <year>2006</year><year>2011</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
13
13
      compliance with the License. You should have received a copy of the
14
14
      Erlang Public License along with this software. If not, it can be
15
15
      retrieved online at http://www.erlang.org/.
16
 
    
 
16
 
17
17
      Software distributed under the License is distributed on an "AS IS"
18
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
      the License for the specific language governing rights and limitations
20
20
      under the License.
21
 
    
 
21
 
22
22
    </legalnotice>
23
23
 
24
24
    <title>Event Handling</title>
61
61
    itself.</p>
62
62
  </section>
63
63
  <section>
 
64
    <marker id="usage"></marker>
64
65
    <title>Usage</title>
65
66
    <p>Event handlers may be installed by means of an <c>event_handler</c>
66
 
    start flag (<c>run_test</c>) or option (<c>ct:run_test/1</c>), where the
 
67
    start flag (<c>ct_run</c>) or option (<c>ct:run_test/1</c>), where the
67
68
    argument specifies the names of one or more event handler modules.
68
69
    Example:</p>
69
 
    <p><c>$ run_test -suite test/my_SUITE -event_handler handlers/my_evh1 
 
70
    <p><c>$ ct_run -suite test/my_SUITE -event_handler handlers/my_evh1 
70
71
    handlers/my_evh2 -pa $PWD/handlers</c></p>
 
72
    <p>Use the <c><![CDATA[ct_run -event_handler_init]]></c> option instead of
 
73
      <c><![CDATA[-event_handler]]></c> to pass start arguments to the event handler
 
74
      init function.</p>
71
75
    <p>All event handler modules must have gen_event behaviour. Note also that 
72
76
    these modules must be precompiled, and that their locations must be
73
77
    added explicitly to the Erlang code server search path (like in the
74
78
    example).</p>
75
79
 
76
 
    <p>It is not possible to specify start arguments to the event handlers when
77
 
    using the <c>run_test</c> script. You may however pass along start arguments
78
 
    if you use the <c>ct:run_test/1</c> function. An event_handler tuple in the argument 
79
 
    <c>Opts</c> has the following definition (see also <c>ct:run_test/1</c> in the 
80
 
    reference manual):</p>
 
80
    <p>An event_handler tuple in the argument <c>Opts</c> has the following
 
81
      definition (see also <c>ct:run_test/1</c> in the reference manual):</p>
81
82
 
82
83
    <pre>
83
84
    {event_handler,EventHandlers}
84
85
 
85
86
    EventHandlers = EH | [EH]
86
87
    EH = atom() | {atom(),InitArgs} | {[atom()],InitArgs}
87
 
    InitArgs = [term()] 
88
 
    </pre>
 
88
    InitArgs = [term()]</pre>
89
89
 
90
90
    <p>Example:</p>
91
91
    <pre>
92
 
    1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).
93
 
    </pre>
 
92
    1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).</pre>
94
93
    <p>This will install two event handlers for the <c>my_SUITE</c> test. Event handler
95
94
    <c>my_evh1</c> is started with <c>[]</c> as argument to the init function. Event handler
96
95
    <c>my_evh2</c> is started with the name of the current node in the init argument list.</p>
122
121
    node the event has originated from (only relevant for CT Master event handlers).
123
122
    <c>data</c> is specific for the particular event.</p>
124
123
 
 
124
    <marker id="events"></marker>
125
125
    <p><em>General events:</em></p>
126
126
 
127
127
    <list>
174
174
        are also given.
175
175
        </p></item>
176
176
 
 
177
      <marker id="tc_done"/>
177
178
      <item><c>#event{name = tc_done, data = {Suite,FuncOrGroup,Result}}</c>
178
179
        <p><c>Suite = atom()</c>, name of the suite.</p>
179
180
        <p><c>FuncOrGroup = Func | {Conf,GroupName,GroupProperties}</c></p>
183
184
              (unknown if init- or end function times out).</p>
184
185
        <p><c>GroupProperties = list()</c>, list of execution properties for the group.</p>
185
186
        <p><c>Result = ok | {skipped,SkipReason} | {failed,FailReason}</c>, the result.</p>
 
187
        <marker id="skipreason"/>
186
188
        <p><c>SkipReason = {require_failed,RequireInfo} | 
187
189
                           {require_failed_in_suite0,RequireInfo} | 
188
190
                           {failed,{Suite,init_per_testcase,FailInfo}} | 
189
191
                           UserTerm</c>, 
190
192
              the reason why the case has been skipped.</p>
191
 
        <p><c>FailReason = {error,FailInfo} | 
 
193
        <marker id="failreason"/>
 
194
        <p><c>FailReason = {error,FailInfo} | 
192
195
                           {error,{RunTimeError,StackTrace}} | 
193
196
                           {timetrap_timeout,integer()} | 
194
197
                           {failed,{Suite,end_per_testcase,FailInfo}}</c>, reason for failure.</p>      
211
214
        <c>end_per_testcase</c> for the case failed.
212
215
        </p></item>
213
216
 
 
217
        <marker id="tc_auto_skip"></marker>
214
218
      <item><c>#event{name = tc_auto_skip, data = {Suite,Func,Reason}}</c>
215
219
        <p><c>Suite = atom()</c>, the name of the suite.</p>
216
220
        <p><c>Func = atom()</c>, the name of the test case or configuration function.</p>
236
240
        skipped because of <c>init_per_testcase</c> failing, since that information is carried with
237
241
        the <c>tc_done</c> event.
238
242
        </p></item>
239
 
 
 
243
        
 
244
        <marker id="tc_user_skip"></marker>
240
245
      <item><c>#event{name = tc_user_skip, data = {Suite,TestCase,Comment}}</c>
241
246
        <p><c>Suite = atom()</c>, name of the suite.</p>
242
247
        <p><c>TestCase = atom()</c>, name of the test case.</p>