testdev/ite/src/com.nokia.testfw.sut.help/html/references/write_a_unit_test_using_sut.htm
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/testdev/ite/src/com.nokia.testfw.sut.help/html/references/write_a_unit_test_using_sut.htm Tue Mar 30 14:39:29 2010 +0800
@@ -0,0 +1,165 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<title>Write a unit test using SUT</title>
+<link rel="StyleSheet" href="../../book.css" type="text/css"/>
+</head>
+<body>
+
+<h2>Write a unit test using SUT</h2>
+
+<p>The following code snippet is from the example Racecar, we can download it from<br />
+<a href="https://developer.symbian.org/sfl/MCL/sftools/ana/testfw/testexecfw/symbianunittestfw/sutfw/sutfwexamples">https://developer.symbian.org/sfl/MCL/sftools/ana/testfw/testexecfw/symbianunittestfw/sutfw/sutfwexamples</a>.</p>
+<div><span>1.<span> </span></span>Select Class and methods to be tested</div>
+<div>For instance, we want to test the class CRaceCar in the example. Two of the functions we want to test are AddFuel() and SpeedL().</div>
+<div> </div>
+
+<div><code>#ifndef CRACECAR_H<br />
+#define CRACECAR_H<br />
+<br />
+class CRaceCar : public CBase <br />
+ {<br />
+<span> // some constructors and destructor…<br />
+<br />
+ public: // New functions<br />
+ TUint AddFuel( TUint aFuel );<br />
+ TUint SpeedL();<br />
+<br />
+ // some other methods and attributes…<br />
+ };<br />
+<br />
+#endif // CRACECAR_H</span></code></div>
+<br />
+<div>In order to get enough privillage to access private members in CRaceCar when creating unit test case, we need to define the test class UT_CRaceCar as friend class</div>
+<div><code>class CRaceCar : public CBase</code></div>
+<div> <code>{</code></div>
+<div> <code>// ...</code></div>
+<div> </div>
+<div> <code>private: // Test class</code></div>
+<div> <code>#ifdef SYMBIAN_UNIT_TEST</code></div>
+<div> <code>friend UT_CRaceCar;</code></div>
+<div> <code>#endif // SYMBIAN_UNIT_TEST</code></div>
+<div> <code>};</code></div>
+<div> </div>
+<div>UT_CRaceCar will be introduced to CRaceCar as friend class if the macro SYMBIAN_UNIT_TEST has been defined in test project.</div>
+<div> </div>
+<div><span>2.<span> </span></span>Define Test Class</div>
+<div>Define a test class UT_CRaceCar, it will derive from CSymbianUnitTest,</div>
+<div> </div>
+<div><code>#ifndef UT_RACECAR_H</code></div>
+<div><code>#define UT_RACECAR_H</code></div>
+<div><code> </code></div>
+<div><code>// INCLUDES</code></div>
+<div><code>#include <symbianunittest.h></code></div>
+<div><code> </code></div>
+<div><code>// FORWARD DECLARATIONS</code></div>
+<div><code>class CRaceCar;</code></div>
+<div><code> </code></div>
+<div><code>// CLASS DECLARATION</code></div>
+<div><code>class UT_CRaceCar : public CSymbianUnitTest</code></div>
+<div><code> {</code></div>
+<div><code> // Constructors and destructor…</code></div>
+<div><code> </code></div>
+<div><code> protected: // From CSymbianUnitTest</code></div>
+<div><code> void SetupL(); <br />
+ void Teardown(); </code></div>
+<div><code> </code></div>
+<div><code> protected: // Test functions, others are the same as this one.</code></div>
+<div><code> void UT_AddFuel(); </code><br />
+<span><code> void UT_SpeedL();</code> </span></div>
+<div><code> </code></div>
+<div><code> private: // Data</code></div>
+<div><code> // The object to be tested as a member variable:</code></div>
+<div><code> CRaceCar *iRaceCar; </code></div>
+<div><code> };</code></div>
+<div><code> </code></div>
+<div><code>#endif // UT_RACECAR_H</code></div>
+
+<div> </div>
+<div>Please notice some Symbian C++ essential functions such as NewL() and ConstructL() are ignored in this document.</div>
+<div>Users can provide optional SetupL() and Teardown() functions. They will be called before and after test case execution. SetupL() usually initializes some of the resources, allocates memory, Teardown() usually in charge of some resource destruction so that the test object can reset its state for the next test case execution.</div>
+<div>UT_AddFuel() and UT_SpeedL() are the unit test code to test the corresponding functions defined in the class CRaceCar.</div>
+<div>The iRaceCar is the instance of class under test.</div>
+<div> </div>
+<div><span>3.<span> </span></span>Create Test DLL entry.</div>
+<div>The next file that we should take into consideration is dllentry.cpp which you can find in the example test project dllentry.cpp.</div>
+<div>It only has one global function with the signature EXPORT_C MSymbianUnitTestInterface* CreateTestL(); in this function, it creates and return the test suites, so the SymbianUnitTest framework can load and run test cases. </div>
+<div> </div>
+<div>The example code snippet is shown below:</div>
+<div><code>EXPORT_C MSymbianUnitTestInterface* CreateTestL()</code></div>
+<div><code> {</code></div>
+<div><code> CSymbianUnitTestSuite* testSuite =</code></div>
+<div><code> CSymbianUnitTestSuite::NewLC( _L("ut_racecar") );</code></div>
+<div><code> </code></div>
+<div><code> testSuite->AddL( UT_CRaceCar::NewLC() );</code></div>
+<div><code> CleanupStack::Pop();</code></div>
+<div><code> </code></div>
+<div><code> // Add more tests to the test suite here when testing multiple classes</code></div>
+<div><code> CleanupStack::Pop( testSuite );</code></div>
+<div><code> return testSuite;</code></div>
+<div><code> }</code></div>
+<div><code> </code></div>
+<div><span>4.<span> </span></span>Implement test cases.</div>
+<div>One of the important functions should taken into account is the second phase constructor of the test suite. In this function, we must call the macro BASE_CONSTRUCT at the first line. Then the unit test methods can be added by using the macro ADD_SUT. Please note that SetupL() will be invoked before each test case runs and the Teardown() will be invoked after the test case execution.</div>
+<div>We can specify the SetupL() and Teardown() functions for certain test case simply by using the macro ADD_SUTWITH_SETUP_AND_TEARDOWN.</div>
+<div> </div>
+<div>The example code snippet is shown below:</div>
+<div><code>void UT_CRaceCar::ConstructL()</code></div>
+<div><code> {</code></div>
+<div><code> BASE_CONSTRUCT</code></div>
+<div><code> ADD_SUT( UT_AddFuel )</code></div>
+<div><code> ADD_SUT_WITH_SETUP_AND_TEARDOWN( SetupL, UT_ SpeedL, Teardown )</code></div>
+<div><code> }</code></div>
+<div><code> </code></div>
+<div>Here is an example a a unit test function.</div>
+<div> </div>
+<div><code>void UT_CRaceCar::UT_FuelL()</code></div>
+<div><code> {</code></div>
+<div><code> SUT_ASSERT_EQUALS( 0, iRaceCar->FuelLeft() )</code></div>
+<div><code> SUT_ASSERT_EQUALS( 0, iRaceCar->AddFuel( KInitialFuel ) )</code></div>
+<div><code> SUT_ASSERT_EQUALS( KInitialFuel, iRaceCar->FuelLeft() )</code></div>
+<div><code> SUT_ASSERT_EQUALS( 2, iRaceCar->AddFuel( 1 ) ) </code></div>
+<div><code> SUT_ASSERT_EQUALS( KInitialFuel, iRaceCar->FuelLeft() )</code></div>
+<div><code> }</code></div>
+<div><code> </code></div>
+<div>In this function, we use the macro SUT_ASSERT_EQUALS to assert if the test function's return value is what we expect, more macros will be introduced in later section. It will be marked as failed if the actual return value doesn't match the expected value when using the macro SUT_ASSERT_EQUALS. The rest of the functions should be tested follow the same way as we mentioned in this section.</div>
+<div> </div>
+<div><span>5.<span> </span></span>Create project mmp file.</div>
+<div>In the next step, we will create a project file. Showing below is a snippet of the mmp file:</div>
+<div>1) TARGET ut_racecar.dll</div>
+<div>2) TARGETTYPE dll</div>
+<div>3) UID<span> 0x20022E76 0x0E6A3C34</span></div>
+<div>4) MACRO SYMBIAN_UNIT_TEST</div>
+<div>5) SOURCE racecar.cpp</div>
+<div>6) SOURCE dllEntry.cpp</div>
+<div>7) SOURCE ut_racecar.cpp</div>
+<div>8) SYSTEMINCLUDE /epoc32/include/symbianunittest</div>
+<div>9) LIBRARY symbianunittestfw.lib</div>
+<div> </div>
+<div>The type of the test project is a dll project, so we should indicate the target type of the project, like line 2, we specify dll as the TARGETTYPE.</div>
+<div>At line 1, we set a target file name for the file.</div>
+<div>At line 3, we must specify the UID2 as it is identified for the SymbianUnitTest’s DLL.</div>
+<div>At line 4, we must add the SYMBIAN_UNIT_TEST macro to enable the macros the test framework provided.</div>
+<div>We also need to list the source code under test (in this case, the source file of the testing class is racecar.cpp), so we add it at line 5.</div>
+<div>We added dllEntry.cpp to the mmp file as stated in section "3 -- Write dll entry" at line 6.</div>
+<div>ut_racecar.cpp is test case implementation, we add it at line 7.</div>
+<div>Line 8 and line 9 contain the directory of the header files and the library file of the SymbianUnitTest we need in our test.</div>
+<div> </div>
+<div><span>6.<span> </span></span>Create bld.inf for the test project.</div>
+<div>We also need to add the newly created project mmp file to bld.inf, just like the following shown below:</div>
+<div>PRJ_TESTMMPFILES</div>
+<div>ut_racecar.mmp</div>
+<div> </div>
+<div><span>7.<span> </span></span>Build project and run it.</div>
+<div>In the test project group directory, execute the following command to build it:</div>
+<div>bldmake bldfiles</div>
+<div>abld test clean winscw</div>
+<div>abld test reallyclean winscw</div>
+<div>abld test build winscw udeb</div>
+<div> </div>
+<div>Run "symbianunittest.exe -t=ut_racecar.dll" to execute the test, we should get the test result at "c:\sut".</div>
+
+</body>
+</html>