View source for Building an Off-Target Test App

== Introduction ==
This article guides you through building a test application ('''TestApp''') for the purpose of running sample code using the STRIDE [[Installation_Overview#Off-Target_Environment | Off-Target Environment]]. 

It requires an installation of the STRIDE Framework package. If not installed, please see [[Desktop Installation]] for more information.

== Host Toolchain ==
Please verify that your Host system contains one of the following compilers:
* For Windows Microsoft Visual Studio 2005 or later is required. If you don't already have Visual Studio, the free [http://en.wikipedia.org/wiki/Microsoft_Visual_Studio_Express Visual C++ Express] can be used (download [http://www.microsoft.com/express/download/#webInstall here]). 
* For Linux the [http://en.wikipedia.org/wiki/GNU_Compiler_Collection GNU Compiler Collection] (included by default in almost all Linux distros) is required.				


== Building a TestApp ==

=== SDK Makefile ===
The SDK Makefile is set up so that all <tt>.c</tt> <tt>.cpp</tt> and <tt>.h</tt> files found in the directory <tt>SDK/Windows/sample_src</tt> are included in the compile and link of the '''testapp''' target.

Further--as a pre-compilation step--any <tt>.h</tt> files found in <tt>sample_src</tt> are submitted to the [[STRIDE Build Tools]]. This will result in 
* the detection of [[Test_Unit_Pragmas| test pragmas]] used to declare Test Units in these <tt>.h</tt> files
* the detection of [[Scl_function | function pragmas]] used to declare remoting of functions also found in <tt>.h</tt> files
* the inclusion of metadata into the <tt>sidb</tt> file created
* the generation of an [[Intercept Module]] required for executing tests

=== Build Steps ===
To begin, be sure that TestApp is not running then perform the following steps:
  
====Linux====
<ol>
<li>Build the test app
<source lang="bash">
cd $STRIDE_DIR/SDK/Linux/src
make testapp
</source>
</li>
<li>The file <tt>$STRIDE_DIR/SDK/Linux/out/bin/TestApp</tt> will be produced
</li>
<li>Note also that the STRIDE database file <tt>$STRIDE_DIR/SDK/Linux/out/TestApp.sidb</tt> is also produced
</li>
</ol>

====Windows====
NOTE: ''If you have [http://en.wikipedia.org/wiki/Cygwin Cygwin] installed and its <tt>bin</tt>  directory is on your path, see [[Troubleshooting Build Problems]].''

<ol>
<li>If using Microsoft Visual Studio, open a Visual Studio command prompt<ref>To open a Visual Studio Command prompt: Click the Start button, point to All Programs, Microsoft Visual Studio 200X, Visual Studio Tools, and then click Visual Studio 200X Command Prompt.</ref> to ensure that the compiler and linker are on your PATH.
</li>
<li>Build the test app using the supplied GNU make. (You will get Makefile errors if you use the default make.)
<source lang="dos">
cd %STRIDE_DIR%\SDK\Windows\src
..\bin\make testapp
</source>
</li>
<li>The file <tt>%STRIDE_DIR%\SDK\Windows\out\bin\TestApp.exe</tt> will be produced 
</li>
<li>Note that the STRIDE database file <tt>%STRIDE_DIR%\SDK\Windows\out\TestApp.sidb</tt> is also produced
</li>
</ol>

'''Note:''' If you prefer to use Visual Studio to build/debug/run your testapp, we provide instructions [[Using_STRIDE_Rules_for_Visual_Studio|here]] about how to accomplish this.

== Diagnostics ==

A set of diagnostic tests are always built into the generated TestApp executable. If desired (we recommend you to do so) you could run them by doing the following:

<ol>
<li>Invoke the TestApp. In order to see TestApp's output, we recommend that you manually open a new console (or Windows equivalent): 
;Linux
<source lang="bash">
$STRIDE_DIR/SDK/Linux/out/bin/TestApp
</source>
;Windows
<source lang="dos">
%STRIDE_DIR%\SDK\Windows\out\bin\TestApp
</source>
(...or launch from the file explorer)

<li> Note TestApp's output upon startup.
<pre>
--------------------------------------------------
STRIDE Test Console Application.
Enter 'Q' to Quit.
--------------------------------------------------
starting up...
Listening on TCP port 8000
"_srThread" thread started.
"stride" thread started.
</pre>
</li>
<li>From a console window, invoke <tt>[[STRIDE_Runner|stride]]</tt> as follows, to verify connectivity with the target app (or Windows equivalent):
<br/>
;Linux
<source lang="bash">
stride --diagnostics --database=$STRIDE_DIR/SDK/Linux/out/TestApp.sidb --device=TCP:localhost:8000 --run="*"
</source>
;Windows
<source lang="dos">
stride --diagnostics --database=%STRIDE_DIR%\SDK\Windows\out\TestApp.sidb --device=TCP:localhost:8000 --run="*"
</source>

As the tests run you will see output in both the TestApp (target) and stride (host) console windows.

The host console window output is shown here:
<pre>
Loading database...
Connecting to device...
  runtime version: 4.3.0x 
Executing diagnostics...
  test unit "Link"
    Loopback ............
    Payload Fragmentation
    Stub-Proxy Deadlock
    Target Characteristics
    > 4 passed, 0 failed, 0 in progress, 0 not in use.
  test unit "Stat"
    > 2 passed, 0 failed, 0 in progress, 0 not in use.
  test unit "Time"
    > 2 passed, 0 failed, 0 in progress, 0 not in use.
  --------------------------------------------------------------------- 
  Summary: 8 passed, 0 failed, 0 in progress, 0 not in use.

Disconnecting from device...
Saving result file...
</pre>
</li>
<li>Note the Summary results shown in the host output; all in use tests should pass.
</li>
<li>To exit TestApp, give the target window focus and enter Ctrl-C (or 'q' under Windows).
</ol>


== TestIntro Sample ==

The initial desktop installation of STRIDE does not set up any source code (with the exception of a set of system diagnostic tests) for automatic inclusion in a test application. The [[Desktop Installation | desktop framework]] distribution, however, comes with a set of [[Samples_Overview | Samples]]. 

In this step, will will add a set of sample tests that provide an overview of STRIDE testing techniques. The [[Test Intro Sample]] tests are described in the linked article. For an overview from a C++ perspective, please see [[Test Intro Cpp Sample]].

To begin, be sure that TestApp is not running, then copy the <tt>.c</tt> and <tt>.h</tt> files found in <tt>Samples/test_in_c_cpp/TestIntro</tt> to <tt>SDK/Windows/sample_src</tt> (or <tt>SDK/Linux/sample_src</tt> for Linux). 

Once the files have been copied to <tt>sample_src</tt>, simply build TestApp as described above. Note if you had previous copied other sample source to this directory, you should decide whether to remove those files first. When you complete the test app build, any source that is in this directory at the time of build will be included in the test app.

=== Running the Tests ===
Here we will run all tests in the <tt>TestApp.sidb</tt> database.<ref>Note that the S2 diagnostic tests are treated separately, and are not run unless the <tt>--diagnostics</tt> option is specified to <tt>stride</tt>.</ref>

# Run the build above TestApp in a console window.
# Invoke <tt>stride</tt> in a separate console window (different from the running TestApp) -- as shown below and verify Summary results.

Here are the command line parameters that we will submit to <tt>stride</tt>

<pre>
--database ./out/TestApp.sidb 
--device TCP:localhost:8000
</pre>

A couple of things to note:
* If you setup an [[STRIDE_Runner#Environment_Variables | environment variable]] for the '''device''' option than it is not required in the option file. Note: Command line options override environment variables.  
* You may want to create a text file named ''RunTestIntro.txt'' in the <tt>SDK\Windows</tt> (or <tt>SDK/Linux</tt> for Linux) directory as an option file to submit to <tt>stride</tt>.
* ''stride --help'' provides [[STRIDE_Runner#Options | options information]]

If you haven't done so already, start <tt>TestApp</tt> running in a separate console window.

Now run stride as follows (starting from the <tt>SDK\Windows</tt> or <tt>SDK/Linux</tt> directory):

<source lang="bash">
stride -O RunTestIntro.txt --run="*"
</source>

The output should look like this:
<pre>
Loading database...
Connecting to device...
Executing...
  test unit "s2_testintro_flist"
    > 2 passed, 1 failed, 0 in progress, 0 not in use.
  test unit "s2_testintro_cclass"
    > 1 passed, 1 failed, 0 in progress, 0 not in use.
  test unit "s2_testintro_testdoubles"
    > 3 passed, 0 failed, 0 in progress, 0 not in use.
  test unit "s2_testintro_testpoints"
    > 3 passed, 0 failed, 0 in progress, 0 not in use.
  test unit "s2_testintro_parameters"
    > 2 passed, 0 failed, 0 in progress, 0 not in use.
  --------------------------------------------------------------------- 
  Summary: 11 passed, 2 failed, 0 in progress, 0 not in use.

Disconnecting from device...
Saving result file...
</pre>

=== Interpreting Results ===
If you're interested in the details of the tests, please see to the test documentation contained in the test report. Open <tt>TestApp.xml</tt> in your browser; this file is created in the directory from which you ran <tt>stride</tt>. If you were connected to the Internet when you ran the tests, the TestApp.xsl file is also generated in the directory. By opening TestApp.xml in a web browser, the xsl is automatically applied to create html in the browser.

==Notes==
<references/>


[[Category:Installation]]