This article will go through the steps required to set up a provided test project to test your custom XPages controls.

In this tutorial we will be using an example control project: com.example.greenbox, but same steps can be applied to other controls.
To follow this tutorial, import the com.example.greenbox project which can be found in the article's Attachments list.
This is a shorter, less detailed version of the article Testing XPages with JUnit Test Framework.
This article is part of the XPages Extensibility API Developers Guide.

Preparing Designer Development Environment

First step is to launch Domino Designer and switch to Java Perspective.
From the menu select Window -> Open Perspective -> Java

(Note, if you don't see that screenshot, try refreshing your browser.)

Next, we download an ExtLib openNTF release from http://extlib.openntf.org/.
Extract srcOpenNTF.zip file.
Navigate to eclipse\plugins folder. Import com.ibm.xsp.test.framework project to Domino Designer.
Click File -> Import


Select General -> Existing Projects into Workspace

Click Next. Navigate to the folder where com.ibm.xsp.test.framework was extracted and import the project.

Download the two attachments(com.example.junit.tests.zip and com.example.greenbox.zip) provided in the article.
Extract the zip files and import the projects using the steps as above.

You will have three projects imported that look like so:


com.example.junit.tests will have 3 compilation errors. This is because it is referencing an old plugin library.
We will be replacing old references to point to our own plugin library(com.example.greenbox).

Configuring Test Project

In the MANIFEST.MF in the test project(com.example.junit.tests), remove dependency on the com.example.xsp project
Add a new dependency for your library plugin (in our case it's com.example.greenbox) so it looks like so:



In the com.example.junit.tests project open WEB-INF/xsp.properties file with the Properties File Editor


Change the dependency from com.example.library to your own (in our case it's com.example.greenbox.library)
The library id is being returned by getLibraryId method from GreenboxLibrary Java Class.
It should look like so:Open config.properties in the com.example.junit.tests test project package com.ibm.xsp.test.framework
Change the target.library and NamingConvention.package.prefix to your own control
(in our case it's com.example.greenbox.library and com.example.greenbox respectively). It should look like so:In the com.example.junit.tests test project, open pages/simpleTestOfExampleControl.xsp
From Java perspective, the graphical editor is not available for XPages. Just click OK. It will open the source of the XPage.

Change the XPage(prefix, namespace, tag) to use your own control. In our case it should look like so:

In the test project(com.example.junit.tests), open ExamplePrintTagNamesAndProps.java from the xsp.example.test.version package.
Somewhere around line #22 change the following code to use your own control (in our case it's Greenbox Library).
Change from:
You might need to organize your imports (Right-click on the file. Source -> Organize Imports) to remove unused references to the old control.


Run the tests:
Right-click on the ExampleTestSuite Java Class in xsp.example.test package
Select Run As -> JUnit Test


This will result in JUnit fails, but ignore this for the moment.
Refresh the test project (com.example.junit.tests). gen folder should now contain generated Java Classes for the corresponding XPage above.

Renaming The Test Project

The sample test project was named to use with the example control. In this section we will go through the steps to rename the test project to use with our control.
For the tutorial purpose, we will be renaming the project to our Greenbox example control but same steps can applied to your own control.
We will start with renaming the project name and proceed to packages after.

Right click on the com.example.junit.tests project. Refactor -> Rename


Name the project to be com.example.greenbox.junit.tests


Now the project is renamed, but it still has the old project name on the file system.
Remove the project from the workspace:
Right-click on the com.example.greenbox.junit.tests. Select Delete.
Make sure you don't check Delete project contents on disk (cannot be undone) checkbox!


Navigate to the com.example.greenbox.junit.tests project's location on the file system.
It will still have the old project name: com.example.junit.tests. Again, rename the folder to com.example.greenbox.junit.tests.
Import the project back to your Domino Designer workspace.

We are going to rename the packages in the test project com.example.greenbox.junit.tests.

Right click on the xsp.example.test package. Refactor -> Rename


Name the package to be xsp.example.greenbox.test
Make sure the two checkboxes are selected: Update references and Rename subpackages


More likely, you will get a warning dialog. Click Continue.



Now your test project structure should look like so:


The com.ibm.xsp.test.framework package should not be renamed as the name is required by the test framework.

Now we are going to rename Java Classes to reflect the the use of our control.
Right click on ExampleTestSuite.java in the com.example.greenbox.test package. Refactor -> Rename


Name it to be GreenboxTestSuite like so


Follow the same pattern for the remaining Java Classes: replacing Example[...] with Greenbox[...].
So that the test project structure looks like so:

Running Test Framework and Fixing Fails

Here we will run JUnit and fix failures one by one.

Running JUnit tests

Same as in previous steps, run the JUnit test framework:
Right-click on the GreenboxTestSuite Java Class from xsp.eample.greenbox.test package
Select Run As -> JUnit Test


The result will have 6 failures. Next, we are going to address the failures one at the time. So by the end of this tutorial, we will have a fully working test project.

GreenboxGroupReuseTest

This test fails with the following message:


Basically, this message is saying that there is an unused skip. Skips are used to ignore some failures which are not needed for the control to function.
As you can see the two messages are nearly identical.
This is because we were renaming the test project, but it still has references to the old project.

1. Copy the error message by right-clicking on the contents of the Failure Trace pane and selecting Copy Trace like so:

2. Paste the error message somewhere in a text file and copy just the second line:


3. Since the test that failed is GreenboxGroupReuseTest, double-click on the failure: xsp.example.greenbox.test.registry.GreenboxGroupReuseTest
It will open the corresponding file.

4. You will see the skips variable of String[] type. It will contain an old skip message. Replace with the one we copied earlier so it looks like so:

5. Rerun JUnit test. There will be one less failure(5 total).

GreenboxControlCategoryKnownTest

Same as with previous test, it fails with the "unused skip" message. So we are going to do the same here.



1. Copy the error message by right-clicking on the contents of the Failure Trace pane and selecting Copy Trace
2. Paste the error message somewhere in a text file and copy just the second line:

3. Since the test that failed is GreenboxControlCategoryKnownTest, double-click on the corresponding failure.
4. You will see the skips variable of String[] type. It will contain an old skip message. Replace with the one we copied earlier so it looks like so:

5. Rerun JUnit test. There will be one less failure(4 total).

GreenboxRoleAccessibilityTest

Again, it is the same type of fail as the two previous test failures.



1. Copy the error message by right-clicking on the contents of the Failure Trace pane and selecting Copy Trace
2. Paste the error message somewhere in a text file and copy just the second line:

3. Since the test that failed is GreenboxRoleAccessibilityTest, double-click on the corresponding failure.
4. You will see the skips variable of String[] type. It will contain an old skip message. Replace with the one we copied earlier so it looks like so:

5. Rerun JUnit test. There will be one less failure(3 total).

GreenboxSinceVersionsSetTest

Under this test, there will be 2 failures:



and



The first failure is about version mismatch. This is because we renamed our test project, but it's still referencing the old control and properties.
1. Right-click on the GreenboxPrintTagNamesAndProps from the xsp.example.greenbox.test.version package and run as Java Application like so:

This will print out an object with your control name and corresponding properties to the console. Like so:

Copy everything from the console output except the first line.
2. Open GreenboxSinceVersionLists Java Class from the xsp.exmaple.greenbox.test.version package.
Replace the already existing object with the one from above. So that it looks like this:

3. Rerun JUnit test. There will be two failures less (1 total).

BaseRenderThemeControlTest

The last failure is a known issue. The XPages team is working to fix this. Please ignore this failure.
To have a fully passing test project, run the Green Test Suite. It will ignore this failure.

Right-click on the GreenGreenboxTestSuite from the xsp.example.greenbox.test. Run As -> JUnit Test


The tests will pass.

For more detailed information and further explanation, see the Testing XPages with JUnit Test Framework article.