← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/common_test/doc/src/basics_chapter.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</year>
 
8
      <year>2008</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
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>Common Test Basics</title>
 
27
    <prepared>Kenneth Lundin, Peter Andersson</prepared>
 
28
    <docno></docno>
 
29
    <date>2003-10-21</date>
 
30
    <rev></rev>
 
31
  </header>
 
32
 
 
33
  <section>
 
34
    <title>Introduction</title>
 
35
 
 
36
    <p>
 
37
      The Common Test framework (CT) is a tool which can support
 
38
      implementation and automated execution of test cases towards different
 
39
      types of target systems. The framework is based on the OTP Test
 
40
      Server. Test cases can be run individually or in batches. Common
 
41
      Test also features a distributed testing mode with central
 
42
      control and logging. This feature makes it possible to test
 
43
      multiple systems independently in one common session. This
 
44
      can be very useful e.g. for running automated large-scale regression 
 
45
      tests.
 
46
    </p>
 
47
 
 
48
    <p>
 
49
      The SUT (system under test) may consist of one or several target
 
50
      nodes.  CT contains a generic test server which together with
 
51
      other test utilities is used to perform test case execution. 
 
52
      It is possible to start the tests from the CT GUI or from an OS- or
 
53
      Erlang shell prompt. <em>Test suites</em> are files (Erlang
 
54
      modules) that contain the <em>test cases</em> (Erlang functions)
 
55
      to be executed. <em>Support modules</em> provide functions
 
56
      that the test cases utilize in order to carry out the tests.
 
57
    </p>
 
58
    
 
59
    <p>
 
60
      The main idea is that CT based test programs connect to
 
61
      the target system(s) via standard O&amp;M interfaces. CT
 
62
      provides implementations and wrappers of some of these O&amp;M
 
63
      interfaces and will be extended with more interfaces later. 
 
64
      There are a number of target independent interfaces
 
65
      supported in CT such as Generic Telnet, FTP etc. which can be
 
66
      specialized or used directly for controlling instruments, 
 
67
      traffic generators etc.</p> 
 
68
    
 
69
    <p>For white-box testing of Erlang code, the test programs can of 
 
70
      course call Erlang API functions directly. Black-box testing of 
 
71
      Erlang code can use Erlang RPC as well as standard O&amp;M interfaces 
 
72
      if desired.
 
73
    </p>
 
74
    
 
75
    <p>A test case can handle several connections towards one or
 
76
      several target systems, instruments and traffic generators in
 
77
      parallel in order to perform the necessary actions for a
 
78
      test. The handling of many connections in parallel is one of
 
79
      the major strengths of CT!      
 
80
    </p>
 
81
  </section>
 
82
 
 
83
  <section>
 
84
    <title>Test Suite Organisation</title>
 
85
    <p>
 
86
      The test suites are organized in test directories and each test suite
 
87
      may have a separate data directory. Typically, these files and directories
 
88
      are version controlled similarly to other forms of source code (possibly by
 
89
      means of some CVS-like tool). However, CT does not itself put any requirements 
 
90
      on (or has any form of awareness of) possible file and directory versions.
 
91
    </p>
 
92
  </section>
 
93
 
 
94
  <section>
 
95
    <title>Support Libraries</title>
 
96
    <p>
 
97
      Support libraries are functions that are useful for all test suites
 
98
      or for test suites in a specific functional area or subsystem.
 
99
      So as well as the general support libraries provided by the
 
100
      CT framework there might be a need for customized support libraries 
 
101
      on a subsystem level.
 
102
    </p>
 
103
  </section>
 
104
 
 
105
  <section>
 
106
    <title>Scripting Suite and Test Cases</title>
 
107
    <p>
 
108
      Testing is performed by running test suites (a set of test cases) or 
 
109
      individual test cases. A test suite is implemented as an Erlang module named 
 
110
      <c><![CDATA[<suite_name>_SUITE.erl]]></c> which contains a number of test cases.
 
111
      A test case is an Erlang function which tests one or more things. 
 
112
      The test case is the smallest unit that the CT test server deals with.
 
113
    </p>
 
114
    
 
115
    <p>
 
116
      The test suite file must conform to a certain interface which is specified 
 
117
      by the CT test server. See the section on writing test suites for more information.
 
118
    </p>
 
119
 
 
120
    <p>
 
121
      A test case is considered successful if it returns to the caller, no matter 
 
122
      what the returned value is. A few return values have special meaning however
 
123
      (such as <c>{skip,Reason}</c> which indicates that the test case is skipped,
 
124
      <c>{comment,Comment}</c> which prints a comment in the log for the test case and 
 
125
      <c>{save_config,Config}</c> which makes the CT test server pass <c>Config</c> to 
 
126
      the next test case). 
 
127
      A test case failure is specified as a runtime error (a crash), no matter what 
 
128
      the reason for termination is. If you use Erlang pattern matching effectively,
 
129
      you can take advantage of this property. The result will be concise and 
 
130
      readable test case functions that look much more like scripts than actual programs. 
 
131
      Simple example:
 
132
    </p>
 
133
    <pre>
 
134
      session(_Config) ->
 
135
          {started,ServerId} = my_server:start(),
 
136
          {clients,[]} = my_server:get_clients(ServerId),
 
137
          MyId = self(),
 
138
          connected = my_server:connect(ServerId, MyId),
 
139
          {clients,[MyId]} = my_server:get_clients(ServerId),
 
140
          disconnected = my_server:disconnect(ServerId, MyId),
 
141
          {clients,[]} = my_server:get_clients(ServerId),
 
142
          stopped = my_server:stop(ServerId).
 
143
    </pre>
 
144
    <p>
 
145
      As a test suite runs, all information (including output to <c>stdout</c>) is 
 
146
      recorded in several different log files. A minimum of information is displayed 
 
147
      in the user console (only start and stop information, plus a note 
 
148
      for each failed test case).
 
149
    </p>
 
150
 
 
151
    <p>
 
152
      The result from each test case is recorded in an HTML log file which is created 
 
153
      for the particular test run. Each test case is represented by a row in a table that shows 
 
154
      the total execution time, whether the case was successful or if it failed or was skipped,
 
155
      plus a possible user comment. For a failed test case, the reason for termination is printed.
 
156
      The HTML file has a link to the logfile for each test case (which may also be viewed
 
157
      with an HTML browser).
 
158
    </p>
 
159
    </section>
 
160
 
 
161
  <section>
 
162
    <title>External Interfaces</title>
 
163
    
 
164
    <p>
 
165
      The CT test server requires some default functions in a 
 
166
      test suite. Each suite module should define and export the 
 
167
      following functions (most are however optional):
 
168
    </p>
 
169
    
 
170
    <taglist>
 
171
      <tag>all()</tag><item>Returns a list of all test cases in the suite. (Mandatory)</item>
 
172
      <tag>suite()</tag><item>Default suite configuration. (Optional)</item>
 
173
      <tag>sequences()</tag>
 
174
      <item>Specifies dependencies between test cases. (Optional)</item>
 
175
      <tag>init_per_suite(Conf)</tag>
 
176
      <item>Executed before the first test case in a suite. (Optional)</item>
 
177
      <tag>end_per_suite(Conf)</tag>
 
178
      <item>Executed after the last test case in a suite. (Optional)</item>
 
179
      <tag>init_per_testcase(TC, Conf)</tag>
 
180
      <item>Executed before each test case in the suite. (Optional)</item>
 
181
      <tag>end_per_testcase(TC, Conf)</tag>
 
182
      <item>Executed after each test case in the suite. (Optional)</item> 
 
183
    </taglist>
 
184
      <p>
 
185
        For each test case the CT test server needs these functions:
 
186
      </p>
 
187
      <taglist>
 
188
        <tag>Testcasename()</tag>
 
189
        <item>Returns a key-value list of test case configuration/information. (Optional)</item>
 
190
        <tag>Testcasename(Config)</tag> 
 
191
        <item>The actual test case function.</item> 
 
192
      </taglist>
 
193
    </section>
 
194
</chapter>