fix for JAL-2991 - we could do better :/
[jalview.git] / doc / UnitTesting.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
8  * Jalview is free software: you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License 
10  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
18  * The Jalview Authors are detailed in the 'AUTHORS' file.
19 -->
20 <head>
21 <title>Unit testing in Jalview</title>
22 </head>
23 <body>
24 <h1> Unit testing in Jalview </h1>
25
26 <p>
27 In June 2015, the Jalview team adopted <a href=http://testng.org/doc/index.html>TestNG</a> for handling unit tests, and all existing JUnit tests were ported to TestNG.
28
29
30 <h2>Test Groups</h2>
31 <a href=http://testng.org/doc/index.html>TestNG</a> provides the ability to perform sophisticated grouping of tests using method annotations. This enables TestNG to be invoked and asked to include a certain set of groups (or regular expression) while excluding another set. This gives maximum flexibility in how tests are partitioned and doesn't require you to recompile anything if you want to run two different sets of tests back to back.
32
33 <p>The following test groups are available within the Jalview test environment:
34 <ul>
35     <li> Functional - basic unit tests that should always be successfully executed</li> 
36     <li> Network -  depends on network connection to execute successfully</li> 
37     <li> External - depends on external third party resource to execute</li>  
38     <li> Interactive - depends on human interaction to execute successfully</li> 
39 </ul>
40
41 <h2>Writing new tests</h2>
42 To write a new TestNG tests in Jalview, create a new java class and create test methods which are properly annotated with appropriate <a href=http://testng.org/doc/documentation-main.html#annotations>TestNG annotations</a>. Here is a simple example test:
43
44 <pre><code>
45     package jalview.test;
46     
47     import org.testng.annotations.*;
48     
49     public class SimpleTest {
50  
51          @BeforeClass(alwaysRun = true)
52          public void setUp() {
53            // code that will be invoked when this test is instantiated
54          }
55  
56          @Test(groups = { "Functional" })
57          public void aFunctionalTest() {
58            System.out.println("Functional test");
59          }
60  
61          @Test(groups = { "Network" })
62          public void aNetworkDependentTest() {
63             System.out.println("Network dependent test");
64          } 
65
66          @Test(groups = { "External" })
67          public void anExternalDependencyTest() {
68             System.out.println(“Test with external dependence to a third party resource");
69          } 
70
71          @Test(groups = { "Interactive" })
72          public void anInteractiveTest() {
73             System.out.println("Human interactive test");
74          }
75      }
76 </code></pre>
77
78 <h2>Test Execution</h2>
79 The TestNG tests for Jalview can be executed in any of the following ways:
80 <ul>
81   <li><b>From Eclipse IDE:</b>
82         </br> To execute Jalview unit test in eclipse please take the following steps:
83         <ul>
84             <li>Ensure that you have TestNG plugin correctly install for eclipse</li>
85             <li>Ensure that your test classes are error free and properly annotated</li>
86             <li>Create a launch configuration "Select the Run / Run... (or Run / Debug...) menu and create a new TestNG configuration"</li>
87             <li>Run the tests by executing the configuration target created above</li>
88         </ul> 
89         A more detailed guide for installing and executing TestNG in eclipse is available at <a href=http://testng.org/doc/eclipse.html>testng.org/doc/eclipse.html</a> <br>&nbsp;
90   </li>
91   <li><b>From Ant:</b> 
92         </br>The ant task 'testng' will run Jalview's tests. You should:
93         <ul>
94             <li>Ensure that you have ant installed</li>
95             <li>Ensure that your test classes are error free and properly annotated</li>
96             <li>Specify the desired group of tests by passing a comma separated list of one or more groups via -Dtestng-groups=""</li>
97         </ul> 
98         A more detailed guide for executing TestNG from ant is available at <a href=http://testng.org/doc/ant.html>http://testng.org/doc/ant.html</a>
99   </li>
100 </ul>
101
102 <h2>TestNG Tutorial</h2>
103 You can find more up-to-date documentations and tutorials on TestNG from the following recommended links:</br>
104 <a href=http://http://testng.org/doc/documentation-main.html>http://http://testng.org/doc/documentation-main.html</a></br>
105 <a href=http://www.tutorialspoint.com/testng/>http://www.tutorialspoint.com/testng/</a>
106
107
108
109 </body>
110 </html>