Test your plugin

It is strongly recommended to implement tests to validate the behavior that you have developed before deploying it to a Semarchy xDM instance.

This page provides instructions to implement automated tests when developing a Semarchy xDM plugin. It explains how to create a JUnit test case for the enricher plugin that you previously created.

Create a test project

To create a test project:

Select File New Other.
In the Wizards filter, enter fragment.
The list shows the Fragment Project wizard.
Select the wizard and click Next.
In the Project Name, enter the name for your project (e.g., com.acme.phoneStandardizerTests). Leave the other fields as is.
Click Next.
In the Content page, modify the following:
- Version: Version of your test plugin fragment (e.g., 1.0.0)
- Name: Visible Name for your test plugin fragment (e.g., Phone Standardizer Test)
- Provider: Your company’s name (e.g., ACME Corp.)
In the Host Plugin section, use the Browse… button to select the Plugin ID.
In the Select a Plugin filter, enter the name of the Semarchy xDM plugin you want to validate with your tests (e.g., com.acme.phoneStandardizer).
Select the Semarchy xDM plugin from the list (e.g., com.acme.phoneStandardizer).
Click Finish.
A new project is created.
In the project editor, select the Dependencies tab.
In the Required Plugins section, click the Add button.
In the Select a Plugin filter, enter org.junit4.
Select the org.junit4 plugin in the list of matching items and then click OK.
Press Control+S (or Command+S on macOS) to save the editor.

Create a test case

To create a test case:

In the Package Explorer, select the test project (com.acme.phoneStandardizerTests), right-click, and select File New Other.
In the Wizards filter, enter junit.
The list shows the JUnit Test Case wizard.
Select the wizard from the list and click Next.
In the JUnit Test Case wizard, enter the following:
- Package: the name of the package containing the class for your test (e.g., com.acme.phonestandardizer.tests).
- Name: the name of the test class (e.g., TestPhoneFrance).
- Class under test: use the browse button to select the class you want to test with this test case(e.g., com.acme.phonestandardizer.IntlPhoneStandardizer).
Click Next.
Select the methods you want to test (typically, the transform method for an enricher or the isValid method for a validation).
Click Finish.
The code editor for your test case opens.

In addition to the transform and isValid methods, you may also test other methods such as setUp and tearDown to verify the plugin behavior during its entire life cycle.

Implement the test case

The test case checks the transformation of several phone numbers. It checks that the transformation provides expected results with valid, invalid, or null phone numbers.

Download the full source code of the TestPhoneFrance.java test case.

The rest of this section describes the key methods implemented in the test code.

The checkPhoneTransform method tests the behavior of the transformer. It takes three parameters:

The NULLIFYONERROR parameter.
An INPUTPHONE input phone number.
An expected STANDARDIZEDPHONE output phone number.

The method:

Defines the mapped inputs, outputs and parameters for the test case.
Instantiates an rowTransformerExecutor object. This object enables testing a row transformer.
This object is created using:
- The list of mapped inputs and outputs.
- The ID of the enricher/validation set when declaring the endpoint, that is com.acme.phoneStandardizer.intlPhoneStandardizer.
Sets up the plugin using the mapped parameters.
Creates a list containing one input DataRow containing an INPUTPHONE input field value.
Runs the transform method for the rowTransformerExecutor to execute the enricher.
Compares (using the JUnit assertEquals method) the value of the STANDARDIZEDPHONE field of the output IDataRow with the expected standardized phone.
Finally, uses the tearDown method on the rowTransformerExecutor.

private void checkPhoneTransform(Boolean nullifyOnError, String inputPhone, String expectedOutputPhone) {

	// Define the mapped inputs.
	Set<String> mappedInputs = new HashSet<String>();
	mappedInputs.add("INPUTPHONE");

	// Define the mapped outputs.
	Set<String> mappedOuputs = new HashSet<String>();
	mappedOuputs.add("STANDARDIZEDPHONE");

	// Define the mapped parameters
	Map<String,Object> parameters = new HashMap<String, Object>();
	parameters.put("NULLIFYONERROR", nullifyOnError);

	// Create the rowTransformerExecutor
	RowTransformerExecutor rowTransformerExecutor = new RowTransformerExecutor("com.acme.phoneStandardizer.intlPhoneStandardizer",null,mappedInputs,mappedOuputs);

	// Setting up the plugin.
	rowTransformerExecutor.setUp(parameters);

	try{

		// Creating a new data row with the test phone number
		IDataRow inDataRow = new DataRow();
		((DataRow) inDataRow).setValue("INPUTPHONE", inputPhone);

		// Inserting this data row in a list of data rows.
		List<IDataRow> inDataRowList = new ArrayList<IDataRow>();
		inDataRowList.add(inDataRow);

		// Enriching the list of input data rows.
		List<IDataRow> outDataRowList = rowTransformerExecutor.transform(inDataRowList);

		// Testing the resulting phone number.
		assertEquals(expectedOutputPhone, outDataRowList.get(0).getValue("STANDARDIZEDPHONE"));

	} finally {

		// Tearing down the plugin.
		rowTransformerExecutor.tearDown();
	}
}

This method is used in various test cases, as shown below.

@Test public void testTransformNullPhones() {
	checkPhoneTransform(true, null, null);
	checkPhoneTransform(false, null, null);
}

@Test public void testTransformBadPhones() {
	checkPhoneTransform(true, "abcd", null);
	checkPhoneTransform(false, "abcd", "abcd");
	checkPhoneTransform(true, "64169710", null);
	checkPhoneTransform(false, "64169710", "64169710");
	checkPhoneTransform(true, "111164169710", null);
	checkPhoneTransform(false, "111164169710", "111164169710");
	checkPhoneTransform(true, "+44664169710", null);
	checkPhoneTransform(false, "+44664169710", "+44664169710");
	checkPhoneTransform(true, "1664169710", null);
	checkPhoneTransform(false, "1664169710", "1664169710");
}

The unit tests only include French phone numbers, as it is what the transformer supports. Valid French phone numbers have 10 digits, starting with a zero. They may be written with non-numeric characters that will be ignored. They may be prefixed with the +33 country code.

Run the test case

To run the test case:

Save the test case code.
Select the test project, right-click and select Run As JUnit Plugin Test. The JUnit view opens and shows the execution results for the test case.

The test cases should display no error.