Difference between revisions of "EDT:EUnit Testing"

From Eclipsepedia

Jump to: navigation, search
 
(12 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
= EUnit Test Framework Overview<br>  =
 
= EUnit Test Framework Overview<br>  =
  
*What is EUnit<br>
+
== What is EUnit?  ==
  
EUnit stands for EGL Unit testing framework. It is a simple open source framework to write and run repeatable EGL tests. <br>
+
EUnit stands for EGL Unit testing framework. It is a simple open source framework to write and run repeatable EGL tests.&nbsp; Its features include:<br>  
  
Its features include:<br>
+
*Tooling to generate a test program and run the test cases – Provided by EDT Framework  
 
+
**Manual and automated
*Tooling to generate test runner and run the test cases – Provided by EDT Framework  
+
**Can be run as often as needed (on demand, nightly build, etc.)  
**Manually and Automated
+
**Can be run as often as needed (on demand, nightly build)  
+
 
**GUI and command line interfaces  
 
**GUI and command line interfaces  
**Logging, Reporting, Analyzing
+
**Logging, reporting, analyzing
**Can be used in multiple language environment (java, javascript, etc)<br>
+
**Can be used in a multiple-language environment (Java, JavaScript, etc)<br>
  
*Test Cases - Provided by test writters<br>
+
*Test cases <br>  
*Documentation - Provided by <br>
+
*Test case documentation&nbsp;<br>
**What does each test case test<br>
+
  
== Design<br> ==
+
EUnit tests are written in EGL. You write the tests in a normal EGL project, then use the EUnit tooling to create a "test driver" for each target language you want to test in.&nbsp; The test driver is runnable code (a Java program or a JavaScript RUIHandler) that will execute the tests and create a report of their results.<br>  
  
 
== How to write test cases using EUnit<br>  ==
 
== How to write test cases using EUnit<br>  ==
  
1. Create an EGL Project, for example: eunit.test<br>  
+
1. Create an EGL Project, for example: '''eunit.test'''<br>  
  
*Select "Basic" as the template.<br>
+
*Select '''Basic''' as the template.<br>
*Set the generators:<br>
+
  
&nbsp; &nbsp; 1) If you run the testing on both Java and JavaScript platform, just leave the settings as default. That is, turn on both Java and JavaScript generator.<br>
+
[[Image:Eunit001.JPG]]
  
&nbsp; &nbsp; 2) If you run the testing on a specific platform, select the checkbox "Override generation settings from workspace preferences" and choose a generator.<br>  
+
*Select the generators:<br>
  
2. Create an EGL Library, for example: test.egl, and give a package name "libs".<br>  
+
&nbsp; &nbsp; 1) If you will run the testing on both Java and JavaScript platforms, leave the default settings (both Java and JavaScript generators selected).<br>  
  
3. Open the library with EGL Editor, remove the automatically generated code.<br>  
+
&nbsp; &nbsp; 2) If you will run the testing on a specific platform, select '''Override generation settings from workspace preferences''' and choose a generator.<br>  
  
4. Type the variable declarations and functions(We treat each function as an EUnit test case) in the library, which should contains the annotation @Test. For example:<br>  
+
[[Image:Eunit002.JPG]]
 +
 
 +
2. Create an EGL Library, for example: '''test,''' and provide a package name, such as '''libs'''.<br>
 +
 
 +
[[Image:Eunit003.JPG]]
 +
 
 +
3. Open the library with the EGL Editor, and remove the automatically generated code.<br>
 +
 
 +
4. Type the variable declarations and functions (we treat each function as an EUnit test case) in the library. Functions that perform a test should have the '''@Test''' annotation. For example:<br>  
 
<pre>package libs;
 
<pre>package libs;
import org.eclipse.edt.eunit.runtime.LogResult;
 
 
import org.eclipse.edt.eunit.runtime.LogResult;
 
import org.eclipse.edt.eunit.runtime.LogResult;
 
import org.eclipse.edt.eunit.runtime.Test;
 
import org.eclipse.edt.eunit.runtime.Test;
Line 55: Line 58:
 
end
 
end
 
</pre>  
 
</pre>  
*Tips<br>
+
5. Each @Test function should perform only one test. Use functions of the library '''org.eclipse.edt.eunit.runtime.LogResult''' to record the results of the test. LogResult's functions include:<br>  
 +
<pre>// Report a success.
 +
function passed(str String in)
  
&nbsp;&nbsp;&nbsp; If you want to disable some specific test cases, you can use "targetLang" in the annotation. For example, below is a test case which cannot be generated into JavaScript.<br>  
+
// Report a failure.
 +
function failed(str String in)
 +
 
 +
// Calls passed() if testCondition is true, and calls failed() if it's false.
 +
function assertTrue(message String in, testCondition boolean in)
 +
 
 +
// Write a message to the EUnit report. This is useful for adding extra
 +
// information about failures.
 +
function logStdOut(logmsg String in)
 +
 
 +
// Report that a variation was not run. You might use this when you know
 +
// test will fail but you don't want it to be treated as an error. Known
 +
// bugs would report "skipped" while new bugs would report "failed".
 +
function skipped(str String in)
 +
 
 +
// Compares the 'actual' string with the 'expected' string. Calls passed()
 +
// if they're equal, and calls failed() if they're not equal.
 +
function assertStringEqual(message String in, expected String in, actual String in)
 +
</pre>
 +
LogResult also has functions similar to assertStringEqual that check values of other types: assertBigintEqual, assertDateEqual, assertTimeEqual, etc.
 +
 
 +
==== Tips<br>  ====
 +
 
 +
*Put closely related tests into the same library, and use packages to organize the libraries.
 +
*If an exception is thrown from a @Test function, EUnit will report it as a failure.<br>
 +
*If you want to disable some test cases for certain languages, you can use '''targetLang''' in the annotation. For example, below is a test case which won't be run in JavaScript.<br>
 
<pre>function runAssignmentFunction01(){@Test {targetLang = [JAVA]}}
 
<pre>function runAssignmentFunction01(){@Test {targetLang = [JAVA]}}
 
variation = "constant initialization";
 
variation = "constant initialization";
 
LogResult.assertStringEqual1("Fred Smith", constFlexName);
 
LogResult.assertStringEqual1("Fred Smith", constFlexName);
 
end
 
end
</pre>
+
</pre>  
 +
== Creating the test driver<br>  ==
  
== How to run tests using EUnit<br> ==
+
Right click on your EUnit project and choose '''Generate EGL Test Driver &gt; Java''' or '''Generate EGL Test Driver &gt; JavaScript'''.<br>  
  
*'''Java'''<br>
+
[[Image:Eunit004.JPG]]
  
1. Right click on the project you just created, choose Generate EGL Test Driver =&gt; Java to create the java test driver.<br>  
+
The name of the test driver project will be the name of your EUnit project, plus '''eunit.java''' or '''eunit.javascript'''.<br>  
  
2. Go to project eunit.test.eunit.java =&gt; folder generatedJava =&gt; Run test.RunAllTests_pgm as Java application.
+
You must re-create your test driver if you add or remove @Test functions in the EUnit project. But you don't have to re-create the test driver if you modify an existing @Test function.<br>
  
3. Refresh project eunit.test.eunit.java, you should see a new folder "ResultRoot", expand its subfolder (name is in current timestamp yyyymmdd_hhmmss), till you see file "ResultSummary.trs", double click to open this file. You need to install Eclipse BIRT to view the Test Result Statistics Chart. You can also go through every individual report by clicking the leaf node of the result tree and navigate to the corresponding source file.<br>  
+
==== Tips<br>  ====
 +
 
 +
*You can create a test driver from packages or egl files instead of an entire project. <br>
 +
 
 +
== How to run tests using EUnit<br> ==
  
*Tips<br>
+
=== Java  ===
  
You can also select one or more packages, egl files (must be the same type) to generate test driver, instead of the entire EGL project. <br>  
+
Go to the '''EGLSource''' folder of the test driver project and run '''eunitgen.RunAllTests_pgm.egl''' as an EGL Java Main Application.<br>  
  
*'''JavaScript'''
+
=== JavaScript ===
  
1. Right click on the project you just created, choose Generate EGL Test Driver =&gt; JavaScript to create the JavaScript test driver. <br>
+
There are two ways to execute the test:
  
2. There are two ways to execute the testing:<br>  
+
*Go to the '''EGLSource''' folder of the test driver project, and run '''eunitgen.RunAllTests_rui.egl''' as an EGL Rich UI Application.
 +
*Go to the '''EGLSource''' folder of the test driver project, and deploy the '''eunit_javascript.egldd''' file to a target project. Start the server and then run the HTML file in the browser.<br>
  
*Go to project eunit.test.eunit.javascript =&gt; EGLSource =&gt; eunitgen.RunAllTests_rui.egl, open in EGL Rich UI editor's preview pane, execute it
+
== Viewing the results  ==
*Go to project eunit.test.eunit.javascript =&gt; EGLSource =&gt; deploy eunit_test_eunit_javascript.egldd file to a target project. Start the server and then run the html file in the browser.<br>
+
  
3. Refresh project eunit.test.eunit.javascript, you should see a new folder "ResultRoot", do the same steps as described in the Java section above.<br>  
+
Refresh your test driver project. You should see a new folder,&nbsp; '''ResultRoot'''.&nbsp; It will have a subfolder whose name is a timestamp of the form yyyymmdd_hhmmss. Expand the subfolder and open the file '''ResultSummary.trs'''. You'll see a summary of the results. If you have BIRT installed you'll also see the results in a pie chart.<br>
 +
[[Image:EUnitPie.PNG]] <BR>
 +
You can also go through every individual report by clicking the leaf node of the result tree and navigating to the corresponding source file.
  
 
<br>  
 
<br>  

Latest revision as of 12:00, 19 December 2012

Contents

[edit] EUnit Test Framework Overview

[edit] What is EUnit?

EUnit stands for EGL Unit testing framework. It is a simple open source framework to write and run repeatable EGL tests.  Its features include:

  • Tooling to generate a test program and run the test cases – Provided by EDT Framework
    • Manual and automated
    • Can be run as often as needed (on demand, nightly build, etc.)
    • GUI and command line interfaces
    • Logging, reporting, analyzing
    • Can be used in a multiple-language environment (Java, JavaScript, etc)
  • Test cases
  • Test case documentation 

EUnit tests are written in EGL. You write the tests in a normal EGL project, then use the EUnit tooling to create a "test driver" for each target language you want to test in.  The test driver is runnable code (a Java program or a JavaScript RUIHandler) that will execute the tests and create a report of their results.

[edit] How to write test cases using EUnit

1. Create an EGL Project, for example: eunit.test

  • Select Basic as the template.

Eunit001.JPG

  • Select the generators:

    1) If you will run the testing on both Java and JavaScript platforms, leave the default settings (both Java and JavaScript generators selected).

    2) If you will run the testing on a specific platform, select Override generation settings from workspace preferences and choose a generator.

Eunit002.JPG

2. Create an EGL Library, for example: test, and provide a package name, such as libs.

Eunit003.JPG

3. Open the library with the EGL Editor, and remove the automatically generated code.

4. Type the variable declarations and functions (we treat each function as an EUnit test case) in the library. Functions that perform a test should have the @Test annotation. For example:

package libs;
import org.eclipse.edt.eunit.runtime.LogResult;
import org.eclipse.edt.eunit.runtime.Test;

// basic library
library test
	
	const constFlexName string = "Fred Smith";
	varFlexName string;
	variation string;
	
	function runAssignmentFunction01(){@Test {}}
		variation = "constant initialization";
		LogResult.assertStringEqual1("Fred Smith", constFlexName);
	end
	
end

5. Each @Test function should perform only one test. Use functions of the library org.eclipse.edt.eunit.runtime.LogResult to record the results of the test. LogResult's functions include:

// Report a success.
function passed(str String in)

// Report a failure.
function failed(str String in)

// Calls passed() if testCondition is true, and calls failed() if it's false.
function assertTrue(message String in, testCondition boolean in)

// Write a message to the EUnit report. This is useful for adding extra
// information about failures.
function logStdOut(logmsg String in)

// Report that a variation was not run. You might use this when you know
// test will fail but you don't want it to be treated as an error. Known 
// bugs would report "skipped" while new bugs would report "failed".
function skipped(str String in)

// Compares the 'actual' string with the 'expected' string. Calls passed()
// if they're equal, and calls failed() if they're not equal.
function assertStringEqual(message String in, expected String in, actual String in)

LogResult also has functions similar to assertStringEqual that check values of other types: assertBigintEqual, assertDateEqual, assertTimeEqual, etc.

[edit] Tips

  • Put closely related tests into the same library, and use packages to organize the libraries.
  • If an exception is thrown from a @Test function, EUnit will report it as a failure.
  • If you want to disable some test cases for certain languages, you can use targetLang in the annotation. For example, below is a test case which won't be run in JavaScript.
function runAssignmentFunction01(){@Test {targetLang = [JAVA]}}
	variation = "constant initialization";
	LogResult.assertStringEqual1("Fred Smith", constFlexName);
end

[edit] Creating the test driver

Right click on your EUnit project and choose Generate EGL Test Driver > Java or Generate EGL Test Driver > JavaScript.

Eunit004.JPG

The name of the test driver project will be the name of your EUnit project, plus eunit.java or eunit.javascript.

You must re-create your test driver if you add or remove @Test functions in the EUnit project. But you don't have to re-create the test driver if you modify an existing @Test function.

[edit] Tips

  • You can create a test driver from packages or egl files instead of an entire project.

[edit] How to run tests using EUnit

[edit] Java

Go to the EGLSource folder of the test driver project and run eunitgen.RunAllTests_pgm.egl as an EGL Java Main Application.

[edit] JavaScript

There are two ways to execute the test:

  • Go to the EGLSource folder of the test driver project, and run eunitgen.RunAllTests_rui.egl as an EGL Rich UI Application.
  • Go to the EGLSource folder of the test driver project, and deploy the eunit_javascript.egldd file to a target project. Start the server and then run the HTML file in the browser.

[edit] Viewing the results

Refresh your test driver project. You should see a new folder,  ResultRoot.  It will have a subfolder whose name is a timestamp of the form yyyymmdd_hhmmss. Expand the subfolder and open the file ResultSummary.trs. You'll see a summary of the results. If you have BIRT installed you'll also see the results in a pie chart.
EUnitPie.PNG
You can also go through every individual report by clicking the leaf node of the result tree and navigating to the corresponding source file.