← Back to branch summary

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

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (1.1.13 upstream)
  • mto: (3.3.1 squeeze)
  • mto: This revision was merged to the branch mainline in revision 17.
  • Revision ID: james.westby@ubuntu.com-20090215164252-dxpjjuq108nz4noa
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/test_server/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>2002</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>Test Server Basics</title>
 
27
    <prepared>Siri Hansen</prepared>
 
28
    <docno></docno>
 
29
    <date></date>
 
30
    <rev></rev>
 
31
  </header>
 
32
 
 
33
  <section>
 
34
    <title>Introduction</title>
 
35
    <p><em>Test Server</em> is a portable test tool for automated
 
36
    testing of Erlang programs and OTP applications. It provides an
 
37
    interface for running test programs directly with Test Server 
 
38
    as well as an interface for integrating Test Server
 
39
    with a framework application. The latter makes it possible to use
 
40
    Test Server as the engine of a higher level test tool
 
41
    application.</p>
 
42
 
 
43
    <p>It is strongly recommended that Test Server be used from inside
 
44
    a framework application, rather than interfaced directly for
 
45
    running test programs. Test Server can be pretty difficult to use
 
46
    since it's a very general and quite extensive and complex
 
47
    application. Furthermore, the <c>test_server_ctrl</c> functions
 
48
    are not meant to be used from within the actual test programs. The
 
49
    framework should handle communication with Test Server and deal
 
50
    with the more complex aspects of this interaction automatically so
 
51
    that a higher level interface may be provided for the tester. For
 
52
    test tool usage to be productive, a simpler, more intuitive and 
 
53
    (if required) more specific interface is required than what Test Server
 
54
    can provide.</p>
 
55
 
 
56
    <p>OTP delivers a general purpose framework for Test Server, called
 
57
    <em>Common Test</em>. This application is a tool well suited for
 
58
    automated black box testing of target systems of <em>any kind</em> 
 
59
    (not necessarily implemented in Erlang). Common Test is also a very
 
60
    useful tool for white box testing of Erlang programs and OTP
 
61
    applications. Unless a more specific functionality and/or user 
 
62
    interface is required (in which case you might need to implement 
 
63
    your own framework), Common Test should do the job for 
 
64
    you. Please read the Common Test User's Guide and reference manual 
 
65
    for more information.</p>
 
66
 
 
67
    <p>Under normal circumstances, knowledge about the Test Server
 
68
    application is not required for using the Common Test framework.
 
69
    However, if you want to use Test Server without a framework,
 
70
    or learn how to integrate it with your own framework, please read on...
 
71
    </p>
 
72
    </section>
 
73
    <section>
 
74
    <title>Getting started</title>
 
75
    <p>Testing when using Test Server is done by running test
 
76
      suites. A test suite is a number of test cases, where each test
 
77
      case tests one or more things. The test case is the smallest unit
 
78
      that the test server deals with. One or more test cases are
 
79
      grouped together into one ordinary Erlang module, which is called
 
80
      a test suite. Several test suite modules can be grouped together
 
81
      in special test specification files representing whole application
 
82
      and/or system test "jobs".
 
83
      </p>
 
84
    <p>The test suite Erlang module must follow a certain interface,
 
85
      which is specified by Test Server. See the section on writing
 
86
      test suites for details about this.
 
87
      </p>
 
88
    <p>Each test case is considered a success if it returns to the
 
89
      caller, no matter what the returned value is. An exception to this
 
90
      is the return value <c>{skip, Reason}</c> which indicates that the
 
91
      test case is skipped. A failure is specified as a crash, no matter
 
92
      what the crash reason is.
 
93
      </p>
 
94
    <p>As a test suite runs, all information (including output to
 
95
      stdout) is recorded in several different log files. A minimum of
 
96
      information is displayed to the user console. This only include
 
97
      start and stop information, plus a note for each failed test case.
 
98
      </p>
 
99
    <p>The result from each test case is recorded in an HTML log file
 
100
      which is created for each test run. Every test case gets one row
 
101
      in a table presenting total time, whether the case was successful
 
102
      or not, if it was skipped, and possibly also a comment. The HTML
 
103
      file has links to each test case's logfile, wich may be viewed
 
104
      from e.g. Netscape or any other HTML capable browser.
 
105
      </p>
 
106
    <p>The Test Server consists of three parts: 
 
107
      </p>
 
108
    <list type="bulleted">
 
109
      <item>The part that executes the test suites on target and
 
110
       provides support for the test suite author is called
 
111
      <c>test_server</c>. This is described in the chapter about
 
112
       writing test cases in this user's guide, and in the reference
 
113
       manual for the <c>test_server</c> module.</item>
 
114
      <item>The controlling part, which provides the low level
 
115
       operator interface, starts and stops the target node (if remote
 
116
       target) and slave nodes and writes log files, is called
 
117
      <c>test_server_ctrl</c>. The Test Server Controller should not
 
118
       be used directly when running tests. Instead a framework built
 
119
       on top of it should be used. More information
 
120
       about how to write your own framework can be found
 
121
       in this user's guide and in the reference manual for the
 
122
      <c>test_server_ctrl</c> module.</item>
 
123
    </list>
 
124
  </section>
 
125
 
 
126
  <section>
 
127
    <title>Definition of terms</title>
 
128
    <taglist>
 
129
      <tag><em>conf(iguration) case</em></tag>
 
130
      <item>This is a group of test cases which need some specific
 
131
       configuration. A conf case contains an initiation function which
 
132
       sets up a specific configuration, one or more test cases using
 
133
       this configuration, and a cleanup function which restores the
 
134
       configuration. A conf case is specified in a test specification
 
135
       like this: <c>{conf,InitFunc,ListOfCases,CleanupFunc}</c></item>
 
136
      <tag><em>datadir</em></tag>
 
137
      <item>Data directory for a test suite. This directory contains
 
138
       any files used by the test suite, e.g. additional erlang
 
139
       modules, c code or data files. If the data directory contains
 
140
       code which must be compiled before the test suite is run, it
 
141
       should also contain a makefile source called Makefile.src
 
142
       defining how to compile.
 
143
      </item>
 
144
      <tag><em>documentation clause</em></tag>
 
145
      <item>One of the function clauses in a test case. This clause
 
146
       shall return a list of strings describing what the test case
 
147
       tests.
 
148
      </item>
 
149
      <tag><em>execution clause</em></tag>
 
150
      <item>One of the function clauses in a test case. This clause
 
151
       implements the actual test case, i.e. calls the functions that
 
152
       shall be tested and checks results. The clause shall crash if it
 
153
       fails.
 
154
      </item>
 
155
      <tag><em>major log file</em></tag>
 
156
      <item>This is the test suites log file.
 
157
      </item>
 
158
      <tag><em>Makefile.src</em></tag>
 
159
      <item>This file is used by the test server framework to generate
 
160
       a makefile for a datadir. It contains some special characters
 
161
       which are replaced according to the platform currently tested.
 
162
      </item>
 
163
      <tag><em>minor log file</em></tag>
 
164
      <item>This is a separate log file for each test case.
 
165
      </item>
 
166
      <tag><em>privdir</em></tag>
 
167
      <item>Private directory for a test suite. This directory should
 
168
       be used when the test suite needs to write to files.
 
169
      </item>
 
170
      <tag><em>skip case</em></tag>
 
171
      <item>A test case which shall be skipped.
 
172
      </item>
 
173
      <tag><em>specification clause</em></tag>
 
174
      <item>One of the function clauses in a test case. This clause
 
175
       shall return an empty list, a test specification or
 
176
      <c>{skip,Reason}</c>. If an empty list is returned, it means
 
177
       that the test case shall be executed, and so it must also have
 
178
       an execution clause. Note that the specification clause is
 
179
       always executed on the controller node, i.e. not on the target
 
180
       node.
 
181
      </item>
 
182
      <tag><em>test case</em></tag>
 
183
      <item>A single test included in a test suite. Typically it tests
 
184
       one function in a module or application. A test case is
 
185
       implemented as a function in a test suite module. The function
 
186
       can have three clauses, the documentation-, specification- and
 
187
       execution clause.
 
188
      </item>
 
189
      <tag><em>test specification</em></tag>
 
190
      <item>A specification of which test suites and test cases to
 
191
       run. There can be test specifications on three different levels
 
192
       in a test. The top level is a test specification file which
 
193
       roughly specifies what to test for a whole application. Then
 
194
       there is a test specification for each test suite returned from
 
195
       the <c>all(suite)</c> function in the suite. And there can also
 
196
       be a test specification returned from the specification clause
 
197
       of a test case.
 
198
      </item>
 
199
      <tag><em>test specification file</em></tag>
 
200
      <item>This is a text file containing the test specification for
 
201
       an application. The file has the extension ".spec" or
 
202
       ".spec.Platform", where Platform is e.g. "vxworks".
 
203
      </item>
 
204
      <tag><em>test suite</em></tag>
 
205
      <item>An erlang module containing a collection of test cases for
 
206
       a specific application or module.
 
207
      </item>
 
208
      <tag><em>topcase</em></tag>
 
209
      <item>The first "command" in a test specification file. This
 
210
       command contains the test specification, like this:
 
211
      <c>{topcase,TestSpecification}</c></item>
 
212
    </taglist>
 
213
  </section>
 
214
</chapter>
 
215