Project

General

Profile

1
<!--
2
  * sitemaps.html
3
  *
4
  *      Authors: Michael Daigle
5
  *    Copyright: 2008 Regents of the University of California and the
6
  *               National Center for Ecological Analysis and Synthesis
7
  *  For Details: http://www.nceas.ucsb.edu/
8
  *      Created: 2008 November 4
9
  *      Version: 
10
  *    File Info: '$ '
11
  * 
12
  * 
13
-->
14
<HTML>
15
<HEAD>
16
<TITLE>Testing Metacat</TITLE>
17
<!-- unfortunately, we have to look for the common css file in the 
18
     user docs directory.  This is because the user docs deploy to 
19
     the top level of the metacat docs on the knb web server -->
20
<link rel="stylesheet" type="text/css" href="../user/common.css">
21
<link rel="stylesheet" type="text/css" href="./default.css">
22
</HEAD> 
23
<BODY>
24
  <table width="100%">
25
    <tr>
26
      <td class="tablehead" colspan="2"><p class="label">Testing Metacat</p></td>
27
      <td class="tablehead" colspan="2" align="right">
28
        <a href="./metacat-eclipse-project.html">Back</a> | <a href="./index.html">Home</a> | 
29
        <!--a href="add next file here when one exists" -->Next<!-- /a -->
30
      </td>
31
    </tr>
32
  </table>
33
      
34
  <div class="header1">Table of Contents</div>
35
  <div class="toc">
36
    <div class="toc1"><a href="#Intro">About Metacat Testing</a></div>
37
      <div class="toc2"><a href="#Overview">Overview</a></div>
38
      <div class="toc2"><a href="#MetacatImplementation">JUnit Implementation in Metacat</a></div>
39
    <div class="toc1"><a href="#WritingTestCase">Writing a Test Case</a></div>
40
      <div class="toc2"><a href="#Basics">Basics</a></div>
41
      <div class="toc2"><a href="#MCTestCase">MCTestCase Base Class</a></div>           
42
      <div class="toc2"><a href="#BestPractices">Best Practices</a></div>
43
    <div class="toc1"><a href="#RunTests">Running Test Cases</a></div>
44
      <div class="toc2"><a href="#AntTask">Ant task</a></div>
45
      <div class="toc2"><a href="#ConfigureMetacat">Configure Metacat For Testing</a></div>
46
      <div class="toc2"><a href="#RunAllTests">Run All Tests</a></div>
47
      <div class="toc2"><a href="#RunOneTest">Run One Test</a></div>
48
      <div class="toc2"><a href="#ViewingOutput">Viewing Test Output</a></div>
49
    <div class="toc1"><a href="#TestDbVersions">Testing Different Database Schema Versions</a></div>
50
      <div class="toc2"><a href="#Scripts">Scripts to Run</a></div>
51
      <div class="toc2"><a href="#CheckoutScripts">Get Scripts Via Checkout</a></div>
52
      <div class="toc2"><a href="#ScriptRepo">Script Repository</a></div>
53
      <div class="toc2"><a href="#ManuallyRunScripts">Manually Run Scripts</a></div>
54
    <div class="toc1"><a href="#UserTesting">User Testing</a></div>
55
      <div class="toc2"><a href="#TestingSkins">Testing Skins</a></div>
56
  </div>  
57
  
58
  <a name="Intro"></a><div class="header1">About Metacat Testing</div>
59
  <a name="Overview"></a><div class="header2">Overview</div>
60
  <p>Metacat uses JUnit tests to test its core functionality.  These tests are
61
  good for testing the internal workings of an application, but don't test the 
62
  layout and appearance.  JUnit tests are meant to be one tool in the developer's 
63
  test arsinal. If you are not familiar with JUnit, you should search out some 
64
  tutorial documentation online.  One such tutorial is at 
65
  <a href="http://clarkware.com/articles/JUnitPrimer.html"> The Clarkware JUnit primer</a></p>
66
  
67
  <p>Metacat test cases will need to be run on the same server as the Metacat
68
  instance that you want to test.  Since Metacat and its test cases share the same
69
  configuration files, there is no way to run the tests remotely.</p>
70

    
71
  <a name="MetacatImplementation"></a><div class="header2">JUnit Implementation in Metacat</div>
72
  <p>Metacat test cases are located in the code at:
73
  <div class="code">&lt;workspace&gt;/metacat/test/edu/ucsb/nceas/metacat*/</div>  
74
  There you will find several java files that define JUnit tests.</p>
75
  
76
  <p> Test cases are run via an ant task, and output from the tests appears in 
77
  a build directory.  More on this to follow.</p>
78

    
79
  <a name="WritingTestCase"></a><div class="header1">Writing a Test Case</div>
80
  <a name="Basics"></a><div class="header2">Basics</div>
81
  <p>All you need to do to get your JUnit test included into the Metacat test 
82
  suite is to create it in one of the &lt;workspace&gt;/test/edu/ucsb/nceas/metacat*/
83
  directories.  The ant test tasks will know that it should be run. </p>
84
  
85
  <p> The following methods are required in a test case class:
86
  <ul>
87
    <li>public &lt;Constructor&gt;(String name) - The constructor for the test class. </li>
88
	<li>public void setUp() - Set up any dependencies for the tests.  This is run before each test case.</li> 
89
	<li>public void tearDown() - Release an resources used by the test.</li> 
90
	<li>public static Test suite() - define the test methods that need to be run.</li>
91
	<li>public void initialize() - define any global initializations that need to be done.</li>
92
  </ul>
93
  
94
  You will test for failure using the many assertion methods available.</p>
95
  
96
  <a name="MCTestCase"></a><div class="header2">MCTestCase Base Class</div>
97
  <p>Metacat test cases extend the MCTestCase base class, which holds common 
98
  methods and variables.  Some of these include:
99
  <ul>
100
    <li>SUCCESS/FALURE - boolean variables holding the values for success and failure. </li>
101
	<li>metacatUrl, username, password - connection variables used for LDAP connectivity</li> 
102
	<li>readDocumentIdWhichEqualsDoc() - method to read a document from Metacat server.</li> 
103
	<li>debug() - method to display debug output to standard error.</li>
104
  </ul>
105
  These are just a few examples to give you an idea of what is in MCTestCase.
106
  </p>
107
  
108
  <a name="BestPractices"></a><div class="header2">Best Practices</div>
109
  <p>The following are a few best practices when writing test cases:
110
  <ul>
111
    <li>Extend MCTestCase - Although strictly speaking, it is possible to bypass MCTestCase
112
    and just extend the JUnit TestCase class, you should not do so.   You should always
113
    extend the MCTestCase class.</li>
114
    <li>Extend Multiple Test Methods - Try to strike a balance between the number of test 
115
    methods and the size of each test.  If a test method starts to get huge, you might see
116
    if you can break it down into mulitple tests based on functionality.  If the number of
117
    tests in the test suite starts to get large, you might see if it makes sense to 
118
    separate them out into different test classes.</li>
119
	<li>Use assertion message - Most assertion methods have an alternate implementation that 
120
	includes a message parameter.  This message will be shown if the assertion fails.  You
121
	should use this version of the assertion method.</li> 
122
	<li>debug() - You should use the debug() method available in the MCTestCase class to
123
	display debug output as opposed to System.err.println().  The test configuration will
124
	allow you to turn off debug output when you use the debug() method.</li>
125
  </ul>
126

    
127
  <a name="RunTests"></a><div class="header1">Running Test Cases</div>
128
  <a name="AntTask"></a><div class="header2">Ant task</div>
129
  <p>As we discussed earlier, the test cases run from within ant tasks.  There is a 
130
  task to run all tests and a task to run individual tests. </p>
131
  <p>You will need to have ant installed on your system.  For downloads and instructions,
132
  visit the <a href="http://ant.apache.org/">Apache Ant site</a>.
133
  </p>
134
  <a name="ConfigureMetacat"></a><div class="header2">Configure Metacat For Testing</div>
135
  <p>The test cases will look at the server's metacat properties file for configuration, 
136
  so there are two places that need to be configured.</p>
137
  <p>First, you need to edit the configuration file at:
138
  <div class="code">&lt;workspace&gt;/metacat/test/test.properties</div>
139
  This should only hold one property: metacat.contextDir.  This should point to 
140
  the context directory for the metacat server you are testing.  For example:
141
  <div class="code">metacat.contextDir=/usr/share/tomcat5.5/webapps/knb</div>
142
  The test classes will use this to determine where to look for the server
143
  metacat.properties file.</p>
144
  
145
  <p>the remainder of the configuration needs to happen in the actual server's 
146
  metacat.properties file located at:
147
  <div class="code">&lt;workspace&gt;/metacat/lib/metacat.properties</div>
148
  You will need to verify that all test.* properties are set correctly:
149
  <ul>
150
    <li>test.printdebug - true if you want debug output, false otherwise </li>
151
    <li>test.metacatUrl - the url for the metacat servlet (i.e. http://localhost:8080/knb/metacat)</li>
152
    <li>test.contextUrl - the url for the metacat web service (i.e. http://localhost:8080/knb)</li>
153
    <li>test.metacatDeployDir - the directory where metacat is physically deployed (i.e. /usr/local/tomcat/webapps/knb)</li>
154
    <li>test.mcUser - the first metacat test user ("uid=kepler,o=unaffiliated,dc=ecoinformatics,dc=org" should be fine)</li>
155
    <li>test.mcPassword - the first metacat test password ("kepler" should be fine)</li>
156
    <li>test.mcAnotherUser - the second metacat test user.  This user must be a member of the knb-usr 
157
        group in ldap. ("uid=test,o=NCEAS,dc=ecoinformatics,dc=org" should be fine)</li>
158
    <li>test.mcAnotherPassword - the second metacat test password ("test" should be fine)</li>
159
    <li>test.piscoUser - the pisco test user ("uid=piscotest,o=PISCO,dc=ecoinformatics,dc=org" should be fine)</li>
160
    <li>test.piscoPassword - the pisco test password ("testPW" should be fine)</li>
161
    <li>test.lterUser - the lter test user ("uid=tmonkey,o=LTER,dc=ecoinformatics,dc=org" should be fine)</li>
162
    <li>test.lterPassword - the lter test password ("T3$tusr" should be fine)</li>
163
    <li>test.testProperty - a property to verify that we can read properties (leave as "testing")</li>
164
  </ul>
165
  </p>
166
  
167
  <p>Note that none of the test users should also be administrative users.  This will mess up 
168
  the access tests since some document modifications will succeed when we expect them to fail.</p>
169
  
170
  <p>Once this is done, you will need to rebuild and redeploy the Metacat server.  Note that
171
  changing these properties does nothing to change the way the Metacat server runs.  Rebuilding
172
  and redeploying merely makes the test properties available to the JUnit tests.</p>
173
  
174
  <a name="RunAllTests"></a><div class="header2">Run All Tests</div>
175
  <p>To run all tests, go to the &lt;workspace&gt;/metacat directory and type</p>
176
  <div class="code">ant clean test</div>
177
  You will see a line to standard output summarizing each test result.
178
  </p>
179
  
180
  <a name="RunOneTest"></a><div class="header2">Run One Test</div>
181
  <p>To run one test, go to the &lt;workspace&gt;/metacat directory and type</p>
182
  <div class="code">ant clean runonetest -Dtesttorun=&lt;test_name&gt;</div>
183
  Where &lt;test_name&gt; is the name of the JUnit test class (without .java on 
184
  the end).  You will see debug information print to standard error.
185
  </p>
186
  
187
  <a name="ViewingOutput"></a><div class="header2">Viewing Test Output</div>
188
  <p>Regardless of whether you ran one test or all tests, you will see output in
189
  the Metacat build directory in your code at:
190
  <div class="code">&lt;workspace&gt;/metacat/build</div>
191
  There will be one output file for each test class.  The files will look like 
192
  <div class="code">TEST-edu.ucsb.nceas.&lt;test_dir&gt;.&lt;test_name&gt;.txt</div>
193
  where &lt;test_dir&gt; is the metacat* directory where the test lives and 
194
  &lt;test_name&gt; is the name of the JUnit test class. These output files will have
195
  all standard error and standard out output as well as information on assertion 
196
  failures in the event of a failed test.
197
  </p>
198
  
199
  <a name="TestDbVersions"></a><div class="header1">Testing Different Database Schema Versions</div>
200
  <p>Now and again it is necessary to restore your test database to an older schema version
201
  either because you need to test upgrade functionality, or you need to test backwords 
202
  compatibility of code.  This section describes how to get your db schema to an older 
203
  version.
204
  
205
  <a name="Scripts"></a><div class="header2">Scripts to Run</div>
206
  <p>It is assumed that you have an empty metacat database up and running with a 
207
  metacat user.
208
  <p>There are two types of scripts that need to be run in order to create a Metacat
209
  schema:</p>
210
  <ul>
211
  <li>xmltables-&lt;dbtype&gt;.sql - where &lt;dbtype&gt; is either oracle or postgres
212
  depending on what type of database you are running against.  This script creates the
213
  necessary tables for Metacat.</li>
214
  <li>loaddtdschema-&lt;dbtype&gt;.sql - where &lt;dbtype&gt; is either oracle or postgres
215
  depending on what type of database you are running against.  This script creates the
216
  necessary seed data for Metacat.</li>
217
  </ul> 
218
  
219
  <a name="CheckoutScripts"></a><div class="header2">Get Scripts Via Checkout</div>
220
  <p>One way to get the scripts you need is to check out the release tag for the version
221
  of metacat that you want to install.  You can then run the two scripts shown above to
222
  create your database.</p>
223
  
224
  <a name="ScriptRepo"></a><div class="header2">Script Repository</div>
225
  <p>For convenience, the scripts to create each version have been extracted and 
226
  checked into:</p>
227
    <div class="code">&lt;metacat_code&gt;/src/scripts/metacat-db-versions</div>
228
  <p>The files look like:</p>
229
  <ul>
230
  <li>&lt;version&gt;_xmltables-&lt;dbtype&gt;.sql - where &lt;version&gt; is the version
231
  of the schema that you want to create and &lt;dbtype&gt; is either oracle or postgres
232
  depending on what type of database you are running against.  This script creates the
233
  necessary tables for Metacat.</li>
234
  <li>&lt;version&gt;_loaddtdschema-&lt;dbtype&gt;.sql - where &lt;version&gt; is the version
235
  of the schema that you want to create and &lt;dbtype&gt; is either oracle or postgres
236
  depending on what type of database you are running against.  This script creates the
237
  necessary seed data for Metacat.</li>
238
  <li>&lt;version&gt;_cleanall-&lt;dbtype&gt;.sql - where &lt;version&gt; is the version
239
  of the schema that you want to create and &lt;dbtype&gt; is either oracle or postgres
240
  depending on what type of database you are running against. This is a convenience script
241
  to clean out the changes for that version.</li>
242
  </ul>
243
  
244
  <a name="ManuallyRunScripts"></a><div class="header2">Manually Run Scripts</div>
245
  <p>For instructions on running database scripts manually, please refer to:
246
  <a href="../user/run-db-scripts.html">how to run database scripts</a></p>
247
    
248
  <a name="UserTesting"></a><div class="header1">User Testing</div>
249
  <p>The following sections describe some basic end user testing to stress
250
  code that might not get tested by unit testing.</p>
251
  
252
  <a name="TestingSkins"></a><div class="header2">Testing Skins</div>  
253
  <p>For each Skin:</p>
254
  <ul>
255
  <li>View main skin page by going to:
256
    <div class="code">http://dev.nceas.ucsb.edu/knb/style/skins/&lt;skin_name&gt;</div>
257
  for each skin, where &lt;skin_name&gt; is in:
258
    <div class="code">default, nceas, esa, knb, kepler, lter, ltss, obfs, nrs, sanparks, saeon</div>
259
  </li>
260
  <li>Test logging in.  Where applicable (available on the skin) log in using an LDAP account.</li>
261
  <li>Test Basic searching
262
     <ul>
263
     <li>Do a basic search with nothing in the search field.  Should return all docs.</li>
264
     <li>Select a distinct word in the title of a doc.  Go back to main page and search for 
265
     that word.</li>
266
     <li>Select the link to the doc and open the metadata.  Choose a distinct word from a 
267
     field that is not Title, Abstract, Keywords or Personnel.  Go back to the main page and 
268
     search all fields (if applicable)</li>
269
     </ul>
270
  </li>   
271
  <li>Test Advanced Searching
272
     <ul>
273
     <li>On the main page, choose advanced search (if applicable)</li>
274
     <li>Test a variety of different search criteria</li>
275
     </ul>
276
  </li>
277
  <li>Test Registry (if applicable)
278
     <ul>
279
     <li>Create a new account</li>
280
     <li>use the "forgot your password" link</li>
281
     <li>change your password</li>
282
     </ul>
283
  </li>
284
  <li>Test Viewing Document
285
     <ul>
286
     <li>Use your search to find a document</li>
287
     <li>Choose the link to a document - you should see document details
288
     <li>In a separate browser, try the shortcut to the doc:
289
       <div class="code">http://dev.nceas.ucsb.edu/knb/metacat/&lt;doc_id&gt;/&lt;skin_name&gt;</div>
290
     You should see the same results as going to the doc via search.</li>
291
     </ul>
292
  </li>
293
  <li>Download Metadata
294
     <ul>
295
     <li>Choose the metadata download</li>
296
     <li>Save the file</li>
297
     <li>view contents for basic validity (contents exist, etc)</li>
298
     </ul>
299
  </li>
300
  <li>Downlaod Data
301
     <ul>
302
     <li>Choose the data download</li>
303
     <li>view the data for basic validity (contents exist, etc)</li>
304
     </ul>
305
  </li>
306
  <li>View Data Table
307
     <ul>
308
     <li>Find a document with a data table</li>
309
     <li>Choose to view the data table</li>
310
     <li>view the data table for basic validity (contents exist, etc)</li>
311
     </ul>
312
  </li>
313
    
314
  <br>
315
  <a href="./metacat-eclipse-project.html">Back</a> | <a href="./index.html">Home</a> | 
316
  <!--a href="add next file here when one exists" -->Next<!-- /a -->
317

    
318
</BODY>
319
</HTML>
(32-32/33)