Difference between revisions of "EDT:EUnit Testing"

From Eclipsepedia

Jump to: navigation, search
(tdr edits)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= EUnit Test Framework Overview<br>  =
 
= EUnit Test Framework Overview<br>  =
  
== What is EUnit? ==
+
== What is EUnit? ==
  
 
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>  
 
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>  
Line 14: Line 14:
 
*Test cases <br>  
 
*Test cases <br>  
 
*Test case documentation&nbsp;<br>
 
*Test case documentation&nbsp;<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>  ==
Line 37: Line 39:
 
3. Open the library with the EGL Editor, and remove the automatically generated code.<br>  
 
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, which should contain the annotation '''@Test'''. For example:<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;
Line 56: 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";
Line 64: Line 93:
 
end
 
end
 
</pre>  
 
</pre>  
== How to run tests using EUnit<br>  ==
+
== Creating the test driver<br>  ==
  
=== Java ===
+
Right click on your EUnit project and choose '''Generate EGL Test Driver &gt; Java''' or '''Generate EGL Test Driver &gt; JavaScript'''.<br>  
 
+
1. Right click on the project you just created, and choose '''Generate EGL Test Driver &gt; Java''' to create the Java test driver.<br>  
+
  
 
[[Image:Eunit004.JPG]]  
 
[[Image:Eunit004.JPG]]  
  
2. Go to '''project eunit.test.eunit.java &gt; folder generatedJava &gt; Run test.RunAllTests_pgm as Java application'''.  
+
The name of the test driver project will be the name of your EUnit project, plus '''eunit.java''' or '''eunit.javascript'''.<br>
  
3. Refresh '''project eunit.test.eunit.java'''.&nbsp; You should see a new folder,&nbsp; '''ResultRoot'''.&nbsp; Expand its subfolder (the name is in current timestamp yyyymmdd_hhmmss), until you see file '''ResultSummary.trs'''.&nbsp; Double click to open this file. You will 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 navigating to the corresponding source file.<br>  
+
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>  
  
[[Image:Eunit005.JPG]]
+
==== 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 (they must be the same type) to generate the 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, and choose '''Generate EGL Test Driver &gt; JavaScrip'''t to create the JavaScript test driver. <br>
+
There are two ways to execute the test:
  
2. 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.<br>
  
*Go to '''project eunit.test.eunit.javascript &gt; EGLSource &gt; eunitgen.RunAllTests_rui.egl''', open it in EGL Rich UI editor's preview pane, and 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'''.&nbsp; You should see a new folder, '''ResultRoot'''.&nbsp; Then 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.