Project

General

Profile

« Previous | Next » 

Revision 4529

Added by daigle about 16 years ago

renamed to testing-metacat.html

View differences:

docs/dev/testmetacat.html
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 
<link rel="stylesheet" type="text/css" href="../common/common.css">
18 
<link rel="stylesheet" type="text/css" href="./default.css">
19 
</HEAD>
20 
<BODY>
21 
  <table width="100%">
22 
    <tr>
23 
      <td class="tablehead" colspan="2"><p class="label">Testing Metacat</p></td>
24 
      <td class="tablehead" colspan="2" align="right">
25 
        <a href="./pagedreturn.html">Back</a> | <a href="./metacattour.html">Home</a> |
26 
        <a href="./unimplem.html">Next</a>
27 
      </td>
28 
    </tr>
29 
  </table>
30
31 
  <div class="header1">Table of Contents</div>
32 
  <div class="toc">
33 
    <div class="toc1"><a href="#Intro">About Metacat Testing</a></div>
34 
      <div class="toc2"><a href="#Overview">Overview</a></div>
35 
      <div class="toc2"><a href="#MetacatImplementation">JUnit Implementation in Metacat</a></div>
36 
    <div class="toc1"><a href="#WritingTestCase">Writing a Test Case</a></div>
37 
      <div class="toc2"><a href="#Basics">Basics</a></div>
38 
      <div class="toc2"><a href="#MCTestCase">MCTestCase Base Class</a></div>
39 
      <div class="toc2"><a href="#BestPractices">Best Practices</a></div>
40 
    <div class="toc1"><a href="#RunTests">Running Test Cases</a></div>
41 
      <div class="toc2"><a href="#AntTask">Ant task</a></div>
42 
      <div class="toc2"><a href="#ConfigureMetacat">Configure Metacat For Testing</a></div>
43 
      <div class="toc2"><a href="#RunAllTests">Run All Tests</a></div>
44 
      <div class="toc2"><a href="#RunOneTest">Run One Test</a></div>
45 
      <div class="toc2"><a href="#ViewingOutput">Viewing Test Output</a></div>
46 
  </div>
47
48 
  <a name="Intro"></a><div class="header1">About Metacat Testing</div>
49 
  <a name="Overview"></a><div class="header2">Overview</div>
50 
  <p>Metacat uses JUnit tests to test its core functionality.  These tests are
51 
  good for testing the internal workings of an application, but don't test the
52 
  layout and appearance.  JUnit tests are meant to be one tool in the developer's
53 
  test arsinal. If you are not familiar with JUnit, you should search out some
54 
  tutorial documentation online.  One such tutorial is at
55 
  <a href="http://clarkware.com/articles/JUnitPrimer.html"> The Clarkware JUnit primer</a></p>
56
57 
  <p>Metacat test cases will need to be run on the same server as the Metacat
58 
  instance that you want to test.  Since Metacat and its test cases share the same
59 
  configuration files, there is no way to run the tests remotely.</p>
60 

  		




  61
  
  
    
  <a name="MetacatImplementation"></a><div class="header2">JUnit Implementation in Metacat</div>


  		




  62
  
  
    
  <p>Metacat test cases are located in the code at:


  		




  63
  
  
    
  <div class="code">&lt;workspace&gt;/metacat/test/edu/ucsb/nceas/metacat*/</div>  


  		




  64
  
  
    
  There you will find several java files that define JUnit tests.</p>


  		




  65
  
  
    
  


  		




  66
  
  
    
  <p> Test cases are run via an ant task, and output from the tests appears in 


  		




  67
  
  
    
  a build directory.  More on this to follow.</p>


  		




  68
  
  
    

  		




  69
  
  
    
  <a name="WritingTestCase"></a><div class="header1">Writing a Test Case</div>


  		




  70
  
  
    
  <a name="Basics"></a><div class="header2">Basics</div>


  		




  71
  
  
    
  <p>All you need to do to get your JUnit test included into the Metacat test 


  		




  72
  
  
    
  suite is to create it in one of the &lt;workspace&gt;/test/edu/ucsb/nceas/metacat*/


  		




  73
  
  
    
  directories.  The ant test tasks will know that it should be run. </p>


  		




  74
  
  
    
  


  		




  75
  
  
    
  <p> The following methods are required in a test case class:


  		




  76
  
  
    
  <ul>


  		




  77
  
  
    
    <li>public &lt;Constructor&gt;(String name) - The constructor for the test class. </li>


  		




  78
  
  
    
	<li>public void setUp() - Set up any dependencies for the tests.  This is run before each test case.</li> 


  		




  79
  
  
    
	<li>public void tearDown() - Release an resources used by the test.</li> 


  		




  80
  
  
    
	<li>public static Test suite() - define the test methods that need to be run.</li>


  		




  81
  
  
    
	<li>public void initialize() - define any global initializations that need to be done.</li>


  		




  82
  
  
    
  </ul>


  		




  83
  
  
    
  


  		




  84
  
  
    
  You will test for failure using the many assertion methods available.</p>


  		




  85
  
  
    
  


  		




  86
  
  
    
  <a name="MCTestCase"></a><div class="header2">MCTestCase Base Class</div>


  		




  87
  
  
    
  <p>Metacat test cases extend the MCTestCase base class, which holds common 


  		




  88
  
  
    
  methods and variables.  Some of these include:


  		




  89
  
  
    
  <ul>


  		




  90
  
  
    
    <li>SUCCESS/FALURE - boolean variables holding the values for success and failure. </li>


  		




  91
  
  
    
	<li>metacatUrl, username, password - connection variables used for LDAP connectivity</li> 


  		




  92
  
  
    
	<li>readDocumentIdWhichEqualsDoc() - method to read a document from Metacat server.</li> 


  		




  93
  
  
    
	<li>debug() - method to display debug output to standard error.</li>


  		




  94
  
  
    
  </ul>


  		




  95
  
  
    
  These are just a few examples to give you an idea of what is in MCTestCase.


  		




  96
  
  
    
  </p>


  		




  97
  
  
    
  


  		




  98
  
  
    
  <a name="BestPractices"></a><div class="header2">Best Practices</div>


  		




  99
  
  
    
  <p>The following are a few best practices when writing test cases:


  		




  100
  
  
    
  <ul>


  		




  101
  
  
    
    <li>Extend MCTestCase - Although strictly speaking, it is possible to bypass MCTestCase


  		




  102
  
  
    
    and just extend the JUnit TestCase class, you should not do so.   You should always


  		




  103
  
  
    
    extend the MCTestCase class.</li>


  		




  104
  
  
    
    <li>Extend Multiple Test Methods - Try to strike a balance between the number of test 


  		




  105
  
  
    
    methods and the size of each test.  If a test method starts to get huge, you might see


  		




  106
  
  
    
    if you can break it down into mulitple tests based on functionality.  If the number of


  		




  107
  
  
    
    tests in the test suite starts to get large, you might see if it makes sense to 


  		




  108
  
  
    
    separate them out into different test classes.</li>


  		




  109
  
  
    
	<li>Use assertion message - Most assertion methods have an alternate implementation that 


  		




  110
  
  
    
	includes a message parameter.  This message will be shown if the assertion fails.  You


  		




  111
  
  
    
	should use this version of the assertion method.</li> 


  		




  112
  
  
    
	<li>debug() - You should use the debug() method available in the MCTestCase class to


  		




  113
  
  
    
	display debug output as opposed to System.err.println().  The test configuration will


  		




  114
  
  
    
	allow you to turn off debug output when you use the debug() method.</li>


  		




  115
  
  
    
  </ul>


  		




  116
  
  
    

  		




  117
  
  
    
  <a name="RunTests"></a><div class="header1">Running Test Cases</div>


  		




  118
  
  
    
  <a name="AntTask"></a><div class="header2">Ant task</div>


  		




  119
  
  
    
  <p>As we discussed earlier, the test cases run from within ant tasks.  There is a 


  		




  120
  
  
    
  task to run all tests and a task to run individual tests. </p>


  		




  121
  
  
    
  <p>You will need to have ant installed on your system.  For downloads and instructions,


  		




  122
  
  
    
  visit the <a href="http://ant.apache.org/">Apache Ant site</a>.


  		




  123
  
  
    
  </p>


  		




  124
  
  
    
  <a name="ConfigureMetacat"></a><div class="header2">Configure Metacat For Testing</div>


  		




  125
  
  
    
  <p>The test cases will look at the server's metacat properties file for configuration, 


  		




  126
  
  
    
  so there are two places that need to be configured.</p>


  		




  127
  
  
    
  <p>First, you need to edit the configuration file at:


  		




  128
  
  
    
  <div class="code">&lt;workspace&gt;/metacat/test/test.properties</div>


  		




  129
  
  
    
  This should only hold one property: metacat.contextDir.  This should point to 


  		




  130
  
  
    
  the context directory for the metacat server you are testing.  For example:


  		




  131
  
  
    
  <div class="code">metacat.contextDir=/usr/share/tomcat5.5/webapps/knb</div>


  		




  132
  
  
    
  The test classes will use this to determine where to look for the server


  		




  133
  
  
    
  metacat.properties file.</p>


  		




  134
  
  
    
  


  		




  135
  
  
    
  <p>the remainder of the configuration needs to happen in the actual server's 


  		




  136
  
  
    
  metacat.properties file located at:


  		




  137
  
  
    
  <div class="code">&lt;workspace&gt;/metacat/lib/metacat.properties</div>


  		




  138
  
  
    
  You will need to verify that all test.* properties are set correctly:


  		




  139
  
  
    
  <ul>


  		




  140
  
  
    
    <li>test.printdebug - true if you want debug output, false otherwise </li>


  		




  141
  
  
    
    <li>test.metacatUrl - the url for the metacat servlet (i.e. http://localhost:8080/knb/metacat)</li>


  		




  142
  
  
    
    <li>test.contextUrl - the url for the metacat web service (i.e. http://localhost:8080/knb)</li>


  		




  143
  
  
    
    <li>test.metacatDeployDir - the directory where metacat is physically deployed (i.e. /usr/local/tomcat/webapps/knb)</li>


  		




  144
  
  
    
    <li>test.mcUser - the first metacat test user ("uid=kepler,o=unaffiliated,dc=ecoinformatics,dc=org" should be fine)</li>


  		




  145
  
  
    
    <li>test.mcPassword - the first metacat test password ("kepler" should be fine)</li>


  		




  146
  
  
    
    <li>test.mcAnotherUser - the second metacat test user.  This user must be a member of the knb-usr 


  		




  147
  
  
    
        group in ldap. ("uid=test,o=NCEAS,dc=ecoinformatics,dc=org" should be fine)</li>


  		




  148
  
  
    
    <li>test.mcAnotherPassword - the second metacat test password ("test" should be fine)</li>


  		




  149
  
  
    
    <li>test.piscoUser - the pisco test user ("uid=piscotest,o=PISCO,dc=ecoinformatics,dc=org" should be fine)</li>


  		




  150
  
  
    
    <li>test.piscoPassword - the pisco test password ("testPW" should be fine)</li>


  		




  151
  
  
    
    <li>test.lterUser - the lter test user ("uid=tmonkey,o=LTER,dc=ecoinformatics,dc=org" should be fine)</li>


  		




  152
  
  
    
    <li>test.lterPassword - the lter test password ("T3$tusr" should be fine)</li>


  		




  153
  
  
    
    <li>test.testProperty - a property to verify that we can read properties (leave as "testing")</li>


  		




  154
  
  
    
  </ul>


  		




  155
  
  
    
  </p>


  		




  156
  
  
    
  


  		




  157
  
  
    
  <p>Note that none of the test users should also be administrative users.  This will mess up 


  		




  158
  
  
    
  the access tests since some document modifications will succeed when we expect them to fail.</p>


  		




  159
  
  
    
  


  		




  160
  
  
    
  <p>Once this is done, you will need to rebuild and redeploy the Metacat server.  Note that


  		




  161
  
  
    
  changing these properties does nothing to change the way the Metacat server runs.  Rebuilding


  		




  162
  
  
    
  and redeploying merely makes the test properties available to the JUnit tests.</p>


  		




  163
  
  
    
  


  		




  164
  
  
    
  <a name="RunAllTests"></a><div class="header2">Run All Tests</div>


  		




  165
  
  
    
  <p>To run all tests, go to the &lt;workspace&gt;/metacat directory and type</p>


  		




  166
  
  
    
  <div class="code">ant clean test</div>


  		




  167
  
  
    
  You will see a line to standard output summarizing each test result.


  		




  168
  
  
    
  </p>


  		




  169
  
  
    
  


  		




  170
  
  
    
  <a name="RunOneTest"></a><div class="header2">Run One Test</div>


  		




  171
  
  
    
  <p>To run one test, go to the &lt;workspace&gt;/metacat directory and type</p>


  		




  172
  
  
    
  <div class="code">ant clean runonetest -Dtesttorun=&lt;test_name&gt;</div>


  		




  173
  
  
    
  Where &lt;test_name&gt; is the name of the JUnit test class (without .java on 


  		




  174
  
  
    
  the end).  You will see debug information print to standard error.


  		




  175
  
  
    
  </p>


  		




  176
  
  
    
  


  		




  177
  
  
    
  <a name="ViewingOutput"></a><div class="header2">Viewing Test Output</div>


  		




  178
  
  
    
  <p>Regardless of whether you ran one test or all tests, you will see output in


  		




  179
  
  
    
  the Metacat build directory in your code at:


  		




  180
  
  
    
  <div class="code">&lt;workspace&gt;/metacat/build</div>


  		




  181
  
  
    
  There will be one output file for each test class.  The files will look like 


  		




  182
  
  
    
  <div class="code">TEST-edu.ucsb.nceas.&lt;test_dir&gt;.&lt;test_name&gt;.txt</div>


  		




  183
  
  
    
  where &lt;test_dir&gt; is the metacat* directory where the test lives and 


  		




  184
  
  
    
  &lt;test_name&gt; is the name of the JUnit test class. These output files will have


  		




  185
  
  
    
  all standard error and standard out output as well as information on assertion 


  		




  186
  
  
    
  failures in the event of a failed test.


  		




  187
  
  
    
  </p>


  		




  188
  
  
    
    


  		




  189
  
  
    
  <br>


  		




  190
  
  
    
  <a href="./pagedreturn.html">Back</a> | <a href="./metacattour.html">Home</a> | 


  		




  191
  
  
    
  <a href="./unimplem.html">Next</a>


  		




  192
  
  
    
  </ul>


  		




  193
  
  
    

  		




  194
  
  
    
</BODY>


  		




  195
  
  
    
</HTML>


  		




  196
  0
  
    

  		












Also available in:  Unified diff