← 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/ct_master_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/ct_master_chapter.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2006</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>Using Common Test for Large Scale Testing</title>
 
27
    <prepared>Peter Andersson</prepared>
 
28
    <docno></docno>
 
29
    <date></date>
 
30
    <rev></rev>
 
31
  </header>
 
32
 
 
33
  <section>
 
34
    <title>General</title>
 
35
    <p>Large scale automated testing requires running multiple independent 
 
36
      test sessions in parallel. This is accomplished by running
 
37
      a number of Common Test nodes on one or more hosts, testing
 
38
      different target systems. Configuring, starting and controlling the
 
39
      test nodes independently can be a cumbersome operation. To aid
 
40
      this kind of automated large scale testing, CT offers a master test 
 
41
      node component, CT Master, that handles central configuration and control
 
42
      in a system of distributed CT nodes.</p>
 
43
 
 
44
    <p>The CT Master server runs on one dedicated Erlang node and uses distributed
 
45
      Erlang to communicate with any number of CT test nodes, each hosting a regular
 
46
      CT server. Test specifications are used as input to specify what to test on which 
 
47
      test nodes, using what configuration.</p> 
 
48
 
 
49
    <p>The CT Master server writes progress information to HTML log files similarly 
 
50
      to the regular CT server. The logs contain test statistics and links to the 
 
51
      log files written by each independent CT server.</p>
 
52
 
 
53
    <p>The CT master API is exported by the <c>ct_master</c> module.</p>
 
54
  </section>
 
55
  <section>
 
56
    <title>Usage</title>
 
57
    <p>CT Master requires all test nodes to be on the same network and share a common 
 
58
      file system. As of this date, CT Master can not start test nodes
 
59
      automatically. The nodes must have been started in advance for CT Master to be 
 
60
      able to start test sessions on them.</p>
 
61
      
 
62
    <p>Tests are started by calling:</p>
 
63
    
 
64
    <p><c>ct_master:run(TestSpecs)</c> or 
 
65
       <c>ct_master:run(TestSpecs, InclNodes, ExclNodes)</c></p>
 
66
    
 
67
    <p><c>TestSpecs</c> is either the name of a test specification file (string) or a list 
 
68
      of test specifications. In case of a list, the specifications will be handled (and
 
69
      the corresponding tests executed) in sequence. An element in a <c>TestSpecs</c> list 
 
70
      can also be list of test specifications. The specifications in such a list will be 
 
71
      merged into one combined specification prior to test execution. For example:</p>
 
72
      
 
73
    <p><c>ct_master:run(["ts1","ts2",["ts3","ts4"]])</c></p>
 
74
 
 
75
    <p>means first the tests specified by "ts1" will run, then the tests specified by "ts2" 
 
76
      and finally the tests specified by both "ts3" and "ts4".</p>
 
77
 
 
78
    <p>The <c>InclNodes</c> argument to <c>run/3</c> is a list of node names. The <c>run/3</c> 
 
79
      function runs the tests in <c>TestSpecs</c> just like <c>run/1</c> but will also 
 
80
      take any test in <c>TestSpecs</c> that's not explicitly tagged with a particular 
 
81
      node name and execute it on the nodes listed in <c>InclNodes</c>. By using <c>run/3</c> 
 
82
      this way it is possible to use any test specification, with or without node information, 
 
83
      in a large scale test environment! <c>ExclNodes</c> is a list of nodes that should be
 
84
      excluded from the test. I.e. tests that have been specified in the test specification 
 
85
      to run on a particular node will not be performed if that node is at runtime
 
86
      listed in <c>ExclNodes</c>.</p>
 
87
 
 
88
      <p>If CT Master fails initially to connect to any of the test nodes specified in a 
 
89
      test specification or in the <c>InclNodes</c> list, the operator will be prompted with 
 
90
      the option to either start over again (after manually checking the status of the 
 
91
      node(s) in question), to run without the missing nodes, or to abort the operation.</p>
 
92
 
 
93
      <p>When tests start, CT Master prints information to console about the nodes that are 
 
94
      involved. CT Master also reports when tests finish, successfully or unsuccessfully. If
 
95
      connection is lost to a node, the test on that node is considered finished. CT Master 
 
96
      will not attempt to reestablish contact with the failing node. At any time to get the
 
97
      current status of the test nodes, call the function:</p>
 
98
 
 
99
      <p><c>ct_master:progress()</c></p>
 
100
 
 
101
      <p>To stop one or more tests, use:</p>
 
102
 
 
103
      <p><c>ct_master:abort()</c> (stop all) or <c>ct_master:abort(Nodes)</c></p>
 
104
 
 
105
      <p>For detailed information about the <c>ct_master</c> API, please see the 
 
106
      manual page for this module.</p>
 
107
  </section>
 
108
  <section>
 
109
    <title>Test Specifications</title>
 
110
    <p>The test specifications used as input to CT Master are fully compatible with the
 
111
    specifications used as input to the regular CT server. The syntax is described in the 
 
112
    <seealso marker="run_test_chapter#test_specifications">Running Test Suites</seealso>
 
113
    chapter.</p>
 
114
 
 
115
    <p>All test specification terms can have a <c>NodeRefs</c> element. This element
 
116
    specifies which node or nodes a configuration operation or a test is to be executed 
 
117
    on. <c>NodeRefs</c> is defined as:</p>
 
118
    
 
119
    <p><c>NodeRefs = all_nodes | [NodeRef] | NodeRef</c></p>
 
120
    
 
121
    <p>where</p>
 
122
 
 
123
    <p><c>NodeRef = NodeAlias | node() | master</c></p>
 
124
 
 
125
    <p>A <c>NodeAlias</c> (<c>atom()</c>) is used in a test specification as a 
 
126
    reference to a node name (so the actual node name only needs to be declared once). 
 
127
    The alias is declared with a <c>node</c> term:</p>
 
128
 
 
129
    <p><c>{node, NodeAlias, NodeName}</c></p>
 
130
 
 
131
    <p>If <c>NodeRefs</c> has the value <c>all_nodes</c>, the operation or test will
 
132
    be performed on all given test nodes. (Declaring a term without a <c>NodeRefs</c> 
 
133
    element actually has the same effect). If <c>NodeRefs</c> has the value 
 
134
    <c>master</c>, the operation is only performed on the CT Master node (namely set 
 
135
    the log directory or install an event handler).</p>
 
136
 
 
137
    <p>Consider the example in the 
 
138
    <seealso marker="run_test_chapter#test_specifications">Running Test Suites</seealso>
 
139
    chapter, now extended with node information and intended to be executed by the
 
140
    CT Master:</p>
 
141
 
 
142
    <pre>
 
143
      {node, node1, ct_node@host_x}.
 
144
      {node, node2, ct_node@host_y}.
 
145
 
 
146
      {logdir, master, "/home/test/master_logs"}.
 
147
      {logdir, "/home/test/logs"}.
 
148
      
 
149
      {config, node1, "/home/test/t1/cfg/config.cfg"}.
 
150
      {config, node2, "/home/test/t2/cfg/config.cfg"}.
 
151
      {config, "/home/test/t3/cfg/config.cfg"}.
 
152
      
 
153
      {alias, t1, "/home/test/t1"}.
 
154
      {alias, t2, "/home/test/t2"}.
 
155
      {alias, t3, "/home/test/t3"}.
 
156
      
 
157
      {suites, node1, t1, all}.
 
158
      {skip_suites, node1, t1, [t1B_SUITE,t1D_SUITE], "Not implemented"}.
 
159
      {skip_cases, node1, t1, t1A_SUITE, [test3,test4], "Irrelevant"}.
 
160
      {skip_cases, node1, t1, t1C_SUITE, [test1], "Ignore"}.
 
161
      
 
162
      {suites, node2, t2, [t2B_SUITE,t2C_SUITE]}.
 
163
      {cases, node2, t2, t2A_SUITE, [test4,test1,test7]}.
 
164
      
 
165
      {skip_suites, t3, all, "Not implemented"}.
 
166
    </pre>
 
167
 
 
168
    <p>This example specfies the same tests as the original example. But 
 
169
    now if started with a call to <c>ct_master:run(TestSpecName)</c>, the 
 
170
    t1 test will be executed on node <c>ct_node@host_x</c> (node1), the
 
171
    t2 test on <c>ct_node@host_y</c> (node2) and the t3 test on both
 
172
    node1 and node2. The t1 config file will only be read on
 
173
    node1 and the t2 config file only on node2, while the t3 config file
 
174
    will be read on both node1 and node2. Both test nodes will write log 
 
175
    files to the same directory. (The CT Master node will however use a 
 
176
    different log directory than the test nodes).</p>
 
177
 
 
178
    <p>If the test session is instead started with a call to 
 
179
    <c>ct_master:run(TestSpecName, [ct_node@host_z], [ct_node@host_x])</c>, 
 
180
    the result is that the t1 test does not run on 
 
181
    <c>ct_node@host_x</c> (or any other node) while the t3 test runs on
 
182
    <c>ct_node@host_y</c> and <c>ct_node@host_z</c>.</p>
 
183
    
 
184
    <p>A nice feature is that a test specification that includes node 
 
185
      information can still be used as input to the regular Common Test server 
 
186
      (as described in the
 
187
    <seealso marker="run_test_chapter#test_specifications">Running Test Suites</seealso>
 
188
    chapter). The result is that any test specified to run on a node with the same
 
189
    name as the Common Test node in question (typically <c>ct@somehost</c> if started
 
190
    with the <c>run_test</c> script), will be performed. Tests without explicit
 
191
    node association will always be performed too of course!</p>
 
192
 
 
193
    <note><p>It is recommended that absolute paths are used for log directories,
 
194
    config files and test directory aliases in the test specifications so that
 
195
    current working directory settings are not important.</p></note>
 
196
  </section>
 
197
 
 
198
</chapter>
 
199
 
 
200