This section covers:
Recommendations
Using test projects is recommended in the following situations:
- Testing projects of hierarchical structure where you have root projects with a number of sub projects attached. If you do not use test projects, any testing action performed on an original-root project will be executed only on the resources directly attached to this project; sub projects will not be analyzed (this is the standard Eclipse approach to projects). When a test project is introduced in this kind of development environment, it will serve as a root for all resources to be tested.
- Testing projects with Flexible build support where the build target definition contains resources from "external" projects—projects other than the one which holds the build target definition. If you do not use test projects, C++test will not be able to correctly assign test case contexts to files.
- Testing projects with Flexible build target support when you want to have a control over header files included in the testing scope. Since the flexible build target tree view does not show header files, it is impossible to control the header files selection. On the other hand, test projects allow you to link any type of resources; this makes it easy to control a selection.
Test projects also provide a better separation of testing components (such as test cases and stubs) from the original source code.
Test Projects User Interface
The user interface provided to create and control test projects consists of the following:
Create Test Project Command
The Create Test Project command is available from the shortcut (right-click) menu in Project Navigator. This command is shown only for project nodes that represent build targets (for both Flexible and Standard build support). This command is not displayed for any other project nodes.
You can select multiple build targets to create a test project, but each selection should contain only one type of build target (Flexible or Standard build support build targets). Mixing build target types is not allowed.
The following image shows the Create Test Project command for “Flexible” build support build targets:
The following image shows the Create Test Project command for “Standard” build support build targets:
The Create Test Project command starts the C++test wizard for Test Projects creation. This wizard consists of the following pages
Create Test Project Wizard Page
To complete this page:
- Enter the project name.
- Specify if the test project should be stored in the workspace or in an external location.
- Chose the appropriate compiler family.
- Enter suitable compiler executable names.
- Click Next.
C++test will then try to collect the necessary information from the build, then start the build process for build targets that were selected when you chose the Create Test Project command.
Build commands are prefixed with the C++test utility designed to collect compiler/linker flags and store them in a build data file. For more details this utility, see Creating a Project Using an Existing Build System.
Note
When C++test attempts to collect build information, it starts the build process for all selected build targets and prefixes the compiler/linker/librarian command lines with the C++test utility that records the build flags. As a result, it’s very important to call “clean” on all included build targets before you involve the Create Test Project—or ensure that the make command line template for all included projects (parents for selected build targets) is modified as follows:
make %makeprefix% --no-print-directory
instead of default: %makeprefix% make --no-print-directory
You can make this modification upon project creation, or do it later in the Build command field in the Project Properties> Build Properties> Build Support tab.
C++test can replace %makeprefix% with an arbitrary parameter. In order to obtain all build options from the Workbench build, C++test needs to execute make with the -B parameter. C++test execution of the Workbench build does not actually entail building binary files, since the compiler is replaced by C++test option scanning utility. In order to be able to attach the -B parameter to the make execution, having the build command as make %makeprefix% is most convenient, and does not cause any other changes in the standard Workbench build.
The information collected during the build process scan is saved inside the test project, in a text file named <test_project_name>.bdf. This file is intended to be used only in the local workspace. It should not be shared through the source control because it uses absolute paths.
Create Project from a Build Data File Wizard Page
This wizard page shows a preview of the test project that will be created—based on the information scanned from a build process. All source files that are compiled during the build process should be linked to the test project.
C++test tries to link the parent folder of any source file that was included in the build process. Using this panel, you can modify the automatically-generated test project structure via shortcut (right-click) menus.
Project Contents Settings
This panel allows you to add a variable to define the linked folders location. This is needed when you intend to share the created test project.
Note that when the project is imported to another workspace, the applied variables need to be defined (through the Window> Preferences> General> Workspace> Linked Resources menu). Usually, the workspace location is referenced using a variable.
Refresh Test Project Command
The Refresh Test Project command is available from the right-click (shortcut) menu in the Project Navigator. This command is shown only for test projects nodes. Choosing this command will force the build scanning process to run.
Use this command:
- Whenever the build flags in the original project(s) referenced by the test project have changed.
- When a test project is checked out from source control. Refreshing the project generates a local version of the build data file (build date file should not be stored in source control unless the team follows always uses the same paths to the workspace and workspace resources are the same on each developer’s machine).
Test Project References Property Page
The “Test Project References” property page allows you to change the set of build targets that are initially included when the test project is created. The property page is available through Project Properties > C++test > Test Project References.
The Property page contains a test project references table view with the list of build targets that are referenced by a test project. When you choose the Refresh Test Project command, C++test will try to collect build flag information for all the resources referenced in this list.
- To add new build targets, click Add, select the build target(s) you want to add, then click OK.
- To remove targets, select the entry that you want to remove, then click Remove. The entry will then be deleted. C++test will skip this build target in build flags scanning action next time the test project is refreshed and in all subsequent refreshes.
Test Projects Maintenance
Test project maintenance involves keeping the test project in sync with the original project for which it was created. In most cases, maintenance will require:
- Refreshing the build data file to reflect build option changes made to the original projects.
- Linking additional resources which were added to the original projects
- Unlinking resources which were removed from the original projects
- Adding/removing build targets referenced by a test project
Test Project Refresh
Whenever the build flags in the project referenced by a test project has changed, you should refresh the test project to keep it in sync. This can be done by right-clicking the project’s Navigator node, then choosing C++test> Refresh Test Project from the shortcut menu. The build targets referenced by the test project will be rescanned and build date file will be refreshed.
Linking Additional Resources
When a test project is created, C++test links to it all directories containing source files that were compiled while building the referenced build targets. This is a one-time activity and no additional automatic resource linking is done later, after the project is created. As a result, if you want to link a resource that was added after the original project creation, you need to add that link manually—using the standard Eclipse facilities for adding linked resources (New> File/Folder> Advanced, Link to file/folder in file system).
Note
We strongly recommend using linked resource rather than making copies of existing resources.
Unlinking Resources Removed From Referenced Build Targets
When a test project is created, C++test links to it all directories containing source files that were compiled while building the referenced build targets. This is a one-time activity and no automatic link updating is done later, after the project is created. As a result, if a resource was removed from the referenced build target after the original project creation, you need to remove that link manually—using the standard Eclipse facilities for removing linked resources
Modifying the List of Referenced Build Targets
If the test project is created from more then one build target, you may need to modify the list of referenced build targets by adding or removing a build target from the list. This can be done using a special property page that is accessible from by right-clicking the project’s Navigator node, then choosing Properties> C++test> Test Project References. The changes will take effect the next time the project is refreshed.
Changing Build Specs
It is common practice to work with more than one Wind River Workbench project's build spec for a given project. In such situation, when the active build spec is changed in the original project, you can pick up a new compiler/linker flags by simply refreshing the project. You do not NOT need to create a separate test project for every build spec.
