How to Create New CETK Tests

You can use the User-Defined Test Wizard to add a custom test module to the Windows Embedded CE 6.0 Test Kit (CETK).
_Note: If you created a custom test for the CETK tool that was included with a previous version of Windows Embedded CE, you must recompile the test, and then add the test to the CETK with the User-Defined Test Wizard. _

To add a custom test to the CETK:
1. Build a module for your custom test. For information about building a module for your custom test, see Building a Tux DLL with Platform Builder or Building a Tux DLL from the Command Line.
2. In the Windows Embedded CE 6.0 Test Kit (CETK) window, from the Tests menu, choose User defined.
3. Choose Next.
4. Choose Add a New Test, and then choose Next.
5. From the Test Kit box, choose the test kit to which you want to add your custom test.
6. In the Name of Test box, type the name for your custom test as you want the name to appear in the CETK window.
7. In the TUX Module (DLL) box, type the file name of the module for your custom test OR Choose Browse, navigate to the file for the module, and then choose Open.
8. In the Command Line box, type the default command line for your custom test.
9. In the Processor box, choose the CPU architecture that your test supports, and then choose Next.
10. If your custom test requires files in addition to the DLL that you specified, complete the following steps:
* Select the Test requires additional support files check box, and then choose Next.
* For each file that your custom test requires, choose Add, navigate to and then select the file, and then choose Open.
11. Choose Next.
12. To copy the files for the custom test to <Platform Builder installation path>\Cepb\Wcetk\User\<CPU>, choose Copy the files to the directory for user-defined tests OR To leave the files for the custom test at the current location, choose Leave the files at the current location.
13. Choose Next, choose Next, and then choose Finish.
14. In the tree-view control in the CETK window, right-click on the target device name, and then choose Redetect Peripherals.
Your custom test appears under the User Tests node.

Tux Test Harness

The Tux test harness (Tux) is a 32-bit client/server test harness that executes test modules stored in dynamic-link library (.dll) files. Tux groups tests, maintains statistics, and provides a user interface. With Tux, you can write clean, short, and platform-independent test cases without the overhead required to write a complete application.
You can administer and execute tests on both a local and remote development workstation because Tux is a client/server application. The Tux client can run in stand-alone mode with no server required, which allows you to execute test cases and test scripts from the command line.

Tux Architecture

The Tux client (Tux.exe) communicates with the Windows Embedded CE 6.0 Test Kit (CETK) server (CeTest.exe). The Tux client is the Tux engine, while the CETK server acts as a remote UI and administration tool. The Tux client is a console application that loads and executes Tux test modules. The CETK server remotely controls one or more Tux clients. With the CETK Server, you can load and unload Tux test modules, select test cases to run from each loaded test module, execute selected tests, and tally results.
The following list describes the advantages of this client/server architecture:
* The CETK server can control multiple Tux clients.
* Separate address spaces for the test engine and the UI minimize the possibility of conflicting code and errors.
* Separate address spaces allow the CETK server to keep running and provide results, even when the client causes a crash.
* The test engine has a small memory footprint and working set size.
* Tests do not compete with the test harness for the UI, because the entire UI for the harness is on the CETK server.
* You can remotely monitor the status of full-screen tests.
* You can port the Tux client to any platform that supports a minimal set of Microsoft® Win32® and Winsock APIs while taking advantage of the UI on the CETK server.
* You can run the Tux client without the CETK server in stand-alone mode, which is useful for batch testing.

Tux Command Line Parameters

The Tux client provides much of the functionality for Tux. You can run the Tux client in stand-alone mode or in conjunction with the Windows Embedded CE 6.0 Test Kit (CETK) server.

Syntax:

		 tux [-b] [-e] [-s file_name | -d test_dll] [-c parameters] [-r seed] [-x test_case] [-l | -lv] [-t address] [-n] [-h] [-k address] [-m] [-o] [-f file_name] [-a] [-z timeout]

Parameters:

-b	Breaks after each Tux DLL loads.
-e	Disables exception handling.
- s filename	Specifies the Tux suite file to load and execute.
-d test_dll	Specifies the Tux DLL to load and execute.
-c parameters	Command line to pass to the Tux DLL.
-r seed	Specifies the integer starting random seed.
-x test_case	Specifies which test cases to run. You can specify a single test case or a range of test cases
-l	Lists the test cases in the Tux DLL specified by the -d parameter.
-lv	With greater verbosity, lists the test cases in the Tux DLL specified by the -d parameter.
-t address	Specifies the name of the computer running the CETK server. Use -t with no arguments to specify a local server.
-n	Runs tests in kernel mode.
-h	Displays the list of command line parameters for Tux.

The following discusses the Tux parameters that are enabled when Kato.dll is present.

		 -k  address

Specifies the name of the computer running the CETK server. Use -k with no arguments to specify a local server.

-m

Logs all Kato output as XML.

-o

Logs all Kato output to the debugger.

		 -f  filename

Logs all Kato output to output file filename.

-a

Appends data to the output file. Use this parameter with the -f parameter.

The following discusses a Tux parameter that is enabled when Toolhelp.dll is present.

		 -z  timeout

Cancels an existing run of the Tux DLL that is specified by the ""-""d parameter. If you specify ""-""z with no arguments, Tux exits after the current test case in the specified Tux DLL ends. If you specify a timeout value, Tux waits for as long as the specified number of seconds for the test case to end. If the test case does not end after the specified wait time, Tux exits. For example, if Tux is running the Gdiapi.dll test module and you run the command ""tux -d gdiapi.dll -z05"", Tux waits 5 seconds for the current test case in Gdiapi.dll to end, and then exits. Note that there is no space between the -z flag and the timeout number.

These parameters are discussed further below.

-b

This parameter is often useful for debugging a Tux test DLL. Some debuggers require that a test module be physically loaded into memory before a breakpoint can be set in that test module. Because the Tux client dynamically loads test modules at run time, it can be difficult to set a valid breakpoint in your test module. The -b parameter forces the Tux client to break to the debugger after your test module has been fully loaded, but before any messages have been sent to your ShellProc function. This behavior gives you an opportunity to set a breakpoint in your test module and then resume execution.

-e

This parameter turns off the default exception handling built into the Tux client. By default, the Tux client traps all exceptions that occur while running in your module, reports them back to you and then continues running with the next test. The -e parameter is useful when debugging a Tux test module.

		 -s  filename

This parameter allows the Tux client to load a test suite file. A test suite file is a script of test DLL modules and test cases to run within each test module. If you use this parameter while running the CETK server with the ""-""t parameter, the script loads but does not execute until directed to do so by the server. If you use this parameter in stand-alone mode without the ""-""t parameter, the Tux client loads the script and immediately executes it. For Windows Embedded CE, suite files can reside on the Windows Embedded ""CE-based"" device across the CESH connection remotely. Tux first attempts to find the files on your development workstation. If Tux fails to find the files on the development workstation, Tux searches the Windows Embedded CE""-""based device for the files. If you want to force Tux to search for files only on the target device, you can prefix the path with cesh:. The following command line shows the syntax for this option.

		 tux -s cesh:test.tux

You can also specify paths relative to the CESH directory on the target device, as shown in the following command line.

		 tux -s cesh:..\suites\test.tux

		 -d  test_dll

This parameter allows the Tux client to load one or more default test modules. You can use this parameter more than once for a given command line to load multiple Tux test modules. If you use this parameter while running the CETK server with the""-""t parameter, the test modules load but do not execute until directed to do so by the server. If you use this parameter in stand""-""alone mode with no ""-""t parameter, the Tux client loads the test modules and immediately begins to execute the specified tests for each test module. For more information, see the descriptions for the ""–""x and ""–""l parameters.

		 -c  param_str

This parameter allows you to pass a parameter string to the Tux test DLL itself. The parameter string that you pass is associated with the DLL most recently specified with the ""-""d parameter. This behavior allows you to specify different parameters for each Tux test DLL. If the string that you specify contains spaces or other special characters, then you should surround the string with quotation marks.

		 -r  seed

This parameter allows you to specify a starting random seed. The seed you pass is associated with the DLL most recently specified with the -d parameter. This behavior allows you to specify a different random seed for each Tux DLL.

		 -x  test_case

This parameter allows you to specify a test case or a range of test cases to run. You must specify the appropriate identifier for each test case, which may be obtained by using the ""–""l parameter. The values you pass are associated with the DLL most recently specified on the command line with the ""-""d parameter. This behavior allows you to specify different test cases for each Tux test DLL. You can specify this parameter multiple times for a single DLL, as shown in the following command line.

		 tux -x10 –x15-20

You can also combine the ranges into a single parameter, as shown in the following command line.

		 tux -x10,15-20

If you use this parameter while running the CETK server with the ""-""t parameter, the test cases specified are selected but do not execute until directed to do so by the server. If you use this parameter in stand-alone mode with no ""-""t parameter, then the Tux client load the test modules and immediately begins executing the specified tests for each test DLL module. If no ""–""x parameter is specified for a given DLL, the default behavior is to run all tests when the Tux client runs in stand-alone mode.

-l

This parameter causes the Tux client to display the contents of all Tux test DLLs specified with the ""–""d parameter. The listing also shows the identifiers associated with each test case. You can use these identifiers with the ""–""x parameter. When you use the ""–""l parameter, all arguments other than ""–""d are ignored. This parameter provides information and does not run any test cases.

-n

This parameter causes tests to be run in kernel mode using ktux.dll. This flag requires the user to have sufficient privilege to load in the kernel.

_Note: Processes running under kernel mode cannot be terminated through target control, so the kp command in target control will not be able to terminate the process. _

		 -t  address

This parameter specifies the location of the CETK server. The address parameter can be a computer name or an IP address. If you do not use the ""-""t parameter, Tux assumes stand-alone mode. You must specify either the ""-""s parameter to load and execute a test suite or the -d parameter to load and execute a test module. If no address is given with the ""-""t parameter, the Tux client uses the IP address of the development workstation.

-h

This parameter generates a list of Tux parameters.

		 -k  address

This parameter specifies the location of the CETK server. The address parameter can be a computer name or an IP address. If no address is given with the ""-""t parameter, the Tux client uses the IP address of the development workstation. This parameter sends all Kato output to the CETK server. This output is in addition to the output to a file and the debugger, if you specify the ""-""f and ""-""o parameters.

-m

This parameter sends all output to an XML file.

-o

This parameter sends all Kato output to the debugger. This output is in addition to the output to the CETK server and a file, if you specify the ""-""k and ""-""f parameters.

		 -f  filename

This parameter saves all Kato output to a file. This output is in addition to the output to the CETK server and the debugger, if you specify the ""-""k and ""-""o parameters. The default behavior is to overwrite any existing file of the same name. To override the default behavior and append information to the file, use the ""-""a parameter along with the ""-""f parameter. For Windows Embedded CE, you can prefix the file name with cesh: if you want to create the file on a target device through the CESH connection. The following command line shows this technique.

		 tux -d test.dll -f cesh:test.txt

You can also specify paths relative to the CESH directory on the target device, as shown by the following command line.

		 tux -d test.dll -f cesh:..\logs\test.txt

If cesh: is not specified, the file is created on the target device.

-a

This parameter can be used with the -f parameter to append data to a log file rather than overwriting the existing log file.

		 -z  timeout

This parameter stops a running Tux DLL. This parameter has an effect only if Toolhelp.dll is present. Use the ""-""d parameter to specify the Tux DLL to stop.
If you specify ""-""z with no arguments, Tux exits after the current test case in the specified Tux DLL ends. If you specify a timeout value, Tux waits for as long as the specified number of seconds for the test case to end. If the test case does not end after the specified wait time, Tux exits. For example, if Tux is running the Gdiapi.dll test module and you run the command tux ""-d gdiapi.dll -z05"", Tux waits 5 seconds for the current test case in Gdiapi.dll to end, and then exits. Put the timeout number immediately after the ""-""z flag, with no space between them.

Remarks

The ""-""n parameter launches the specified library in the kernel process via the intermediary ktux.dll.
The ""-k, -m, -o, -f, and -a"" parameters are available only if Kato.dll is present. Kato.dll is the Kato Logging Engine used by most Tux test modules. Tux does not require Kato, but Kato is the recommended logging engine if you want to include logging in your test modules. For more information, see Kato Logging Engine.

A space is not required between a command line parameter and its argument. For example, the following two command lines are equivalent.

		 tux -t tuxdemo.dll

You must specify each command line parameter separately. For example, the following command line is valid.

		 tux -b -e

However, the following command line is invalid.

		 tux –be

Implementing a Tux Test Suite with TuxSkel

The files in the TuxSkel directory provide a code framework that you can use to implement a Tux test.
To use TuxSkel to create a new test:
1. Copy all files from the %_WINCEROOT%\Others\WCETK\Tux\Tuxskel directory to an empty directory.
2. Change the TargetName= field in the sources file to the name of the new test.
3. Rename the Tuxskel.def file to the name of the new test, keeping the .def file extension.
4. Add test procedures in the Test.cpp file. Use TestProc as a model when you add test procedures.
5. Export test procedures to the function table in the Ft.h file. Add a line for each test procedure to the Test.cpp file to export, using TestProc as a model.

Building a Tux DLL with Platform Builder

A Tux DLL is a module that defines the characteristics of a test for the Windows Embedded CE 6.0 Test Kit (CETK). For information about functions, messages, and structures that you can include in a Tux DLL, see Tux Test Module Reference.

You can build a Tux DLL using Platform Builder. You can also build a Tux DLL from the command line. For information about building a Tux DLL from the command line, see Building a Tux DLL from the Command Line.

Building a Tux DLL with Platform Builder includes three steps: Preparing an operating system (OS) design for the Tux DLL, creating a project for the Tux DLL, and building the Tux DLL.
Once you have prepared an OS design, you can create a project for the Tux DLL. After creating the project, you can build a sample Tux DLL from that framework, or you can add your own code and then build the project to create a custom test for the CETK.

After you have built the Tux DLL, you can add the new test to the CETK. For information about adding your Tux DLL to the CETK, see Adding a Custom Test to the CETK.

Preparing an OS design for the Tux DLL:
1. From the File menu, choose New, then Project.
2. In the New Project window, select Platform Builder for CE 6.0 and use the OS Design template. Click OK and follow the wizard to design your OS.

Creating a project for the Tux DLL:
1. From the File menu, choose New Project or File.
2. Choose the Projects tab, and then select WCE TUX Dynamic-Link Library.
3. In the Project name box, type a name for the project.

For example, in the Project name box, type TuxDll.
4. Choose Workspace project, and then choose OK.
5. Choose Next, and then choose Finish.

Building the Tux DLL:
1. In the Workspace window, choose the FileView tab.
2. Expand Projects, and then select your project.
3. From the Build Project menu, choose Build Current Project.

Building a Tux DLL from the Command Line

You can build a Tux DLL from the command line. You can also build a Tux DLL using Platform Builder. For more information, see Building a Tux DLL with Platform Builder.

To build a Tux DLL from the command line:
1. Create a new OS design using Platform Builder. For more information, see Building a Tux DLL with Platform Builder.
2. From the Build OS menu of the Platform Builder window, choose Set Active Configuration.
3. In the Configurations list, select a Release configuration, and then choose OK.
4. From the Build OS menu, choose Sysgen.
5. Copy the files from the %_WINCEROOT%\Others\Wcetk\Tux\Tuxskel directory to the directory for the project.
6. From the Build OS menu, choose Open Release Directory.
7. In the console window, change directory to the directory for your project.
8. Type build –c.

After you build the Tux DLL, you can add the test to the Windows Embedded CE 6.0 Test Kit (CETK). For information about adding the Tux DLL to the CETK, see Adding a Custom Test to the CETK.

Tux Test Module Reference

A Tux test module must contain the following items to run correctly.
* A function table to define all test cases in the test module.
* A ShellProc function to handle Tux-related messages.
* One or more TestProc test case functions, located in the function table.

This section provides an overview of the structures, messages, and functions used by a Tux test DLL module. A sample test named Tuxdemo illustrates how to write a Tux test module. The topics for the structures, messages, and functions reference the source files for Tuxdemo, which you can use as a template for creating your own test DLL.

Function Table

A Tux test DLL module uses the function table to export the test cases for the test module to Tux. A test DLL module typically creates a static array of FUNCTIONTABLEENTRY structures, filling in each of the fields with relevant information. Each structure in the function table represents a single test or group of tests in the test DLL module.

Tux Functions

Programming element	Description
ShellProc	This function allows for communication between Tux and the test module. Messages are passed to the ShellProc function to notify or query the test module.
TestProc	This function is a prototype that is used for all test cases listed in the function table for the test module.

ShellProc Messages

Programming element	Description
SPMLOADDLL	This message is sent once to the DLL immediately after the DLL loads.
SPMUNLOADDLL	This message is sent once to the DLL immediately before the DLL unloads.
SPMSHELLINFO	This message is sent once to the DLL immediately following the SPMLOADDLL message to give the DLL information about Tux.
SPMREGISTER \|\|This message is sent once to the DLL immediately following the SPMSHELL_INFO message to query the DLL for its function table.
SPMSTARTSCRIPT	This message is sent to the DLL immediately before a script starts. This message is sent to all loaded DLLs, including loaded DLLs that are not in the script.
SPMSTOPSCRIPT	This message is sent to the DLL after the script stops. This message is sent when the script reaches its end or when you stop the script.
SPMBEGINGROUP	This message is sent to the DLL before a single test or group of tests from that DLL executes.
SPMENDGROUP	This message is sent to the DLL after a group of tests from that DLL finishes running. This message gives the DLL time to clean up after it runs.
SPMBEGINTEST	This message is sent to the DLL immediately before a single test executes.
SPMENDTEST	This message is sent to the DLL after a single test case from the DLL executes.
SPM_EXCEPTION	This message is sent to the DLL whenever code execution in the DLL causes an exception fault.

Tux Functions

FUNCTIONTABLEENTRY

This structure is used to hold information about a Tux test DLL module test case or test group.

Syntax
typedef struct FUNCTIONTABLE_ENTRY {

		  LPCTSTR lpDescription;
		  UINT uDepth;
		  DWORD [dwUserData;]
		  DWORD dwUniqueID;
		  TESTPROC [lpTestProc;]

} FUNCTIONTABLEENTRY, *LPFUNCTIONTABLEENTRY;

Members

lpDescription

This member is used to describe the test case or test group that the current structure represents. This is the string that is displayed to identify the particular test case or test group within Tux. lpDescription can point to an ANSI or UNICODE string, depending on how your test module builds.

uDepth

This member is used to provide test modules with a mechanism to build hierarchies of test groups and test cases. A value of 0 implies that this is a root level test or group. A value of n would imply that this group or test belongs to the most recent prior entry in the table that has a depth of n-1.

dwUserData

This member contains a user-defined value that is not used by Tux. This value is passed into the TestProc function pointed to by lpTestProc at execution time. It is often used to pass a structure pointer or flag to a single test function that can perform more than one operation. A single test function may appear in the function table more than once, but perform a different task depending on the value in dwUserData.

dwUniqueID

This member contains a user-defined value that is used to uniquely identify the given test case. Tux uses this value to identify a particular test case when saving and loading suites. When defining dwUniqueID, no two test cases can have the same value. This value is obtainable at run time from within the TestProc procedure pointed to by lpTestProc.

lpTestProc

This member contains a function pointer that is used to point to the actual test function for a given entry. If the entry is being used as a test group, this member must be NULL.

ShellProc Structures

Programming element	Description
SPSLOADDLL	This structure is pointed to by the spParam parameter for the ShellProc function. This structure can be used to query the Tux DLL for build information.
SPSSHELLINFO	This structure is pointed to by the spParam parameter for the ShellProc function. This structure can be used to pass information about the Tux shell to the Tux DLL.
SPS_REGISTER	This structure stores a pointer to the Tux DLL function table.
SPSBEGINTEST	This structure contains the function table entry and other information for the next test to execute.
SPSENDTEST	This structure contains the function table entry and other information for the test that previously executed.
SPS_EXCEPTION	This structure contains information about the exception that was generated.

TestProc Structures

Programming element	Description
TPS_EXECUTE	This structure is used to inform the test case of the current thread's number, the maximum thread number, and the thread's random seed.
TPSQUERYTHREAD_COUNT	This structure indicates the number of threads and is filled in by the TestProc function.

Device Driver Loader and Tux Extender

The Device Driver Loader and Tux Extender (DDLX), Ddlx.dll, is a set of tools that extend the capabilities of the Tux test harness. DDLX allows the dynamic-link library (DLL) for your test to operate in either an application or a Device.exe address space.
When using Tux alone, your test DLL loads into the address space for Tux. However, when using DDLX in combination with Tux, Ddlx.dll loads into the address space for Tux. Ddlx.dll registers your test DLL as a device driver in the Device.exe address space and provides an interface to your test DLL. This approach allows your test DLL to run in the Device.exe address space while also taking advantage of the functionality that Tux provides.
When your test DLL executes and returns values to DDLX, DDLX accepts the return codes and translates them into valid return codes for Tux. DDLX provides a way for Tux and your test DLL to communicate across different address spaces.

The following command line shows the syntax for running a test using Ddlx.dll.

		 tux –d ddlx –c "-d test_dll –i device_index -c parameters "

In this command line, testdll is the name of the test library, deviceindex is the index of the device, and parameters represents additional parameters. The -d ddlx –c parameters outside of the quotation marks are parameters for Tux. These parameters instruct Tux to load Ddlx.dll into the process space for Tux and then pass the entire string enclosed in quotation marks to Ddlx.dll.
The list of parameters for Ddlx.dll enclosed in quotation marks does not require a space, a command line option, and its argument. However, you must insert a space between each command line option. The following command line lacks spaces between the elements, and so is not acceptable.
tux -d ddlx -c "-dtest.dll-i2" (NOT ACCEPTABLE)
The following table shows the parameters for DDLX.

Parameter	Description
-d test_dll	File to register. If you do not specify this option, DDLX attempts to load Generic.dll.
-I device_index	Device index for the driver. If you do not specify this option, DDLX uses a value of 1.
-c parameters	Additional parameters for test_dll to pass on to the device driver being tested.

The following command line shows the syntax for a sample test.

		 tux –o –d ddlx –c "-d test.dll –i 2 –c 1 2 3"

In this example, the device driver being tested receives the "1 2 3" string as a command line.

If you do not need to specify a device index or any additional command line parameters, you can omit the quotation marks and the –d parameter. The following command line shows the syntax for this scenario.