UnitTests

= Unit Tests = Ideally, CSS code is developed in a test-driven manner, and tests are executed as part of an integration build.

---

'''The following is currently under discussion. It's not finalized.'''

Please add comments for improvements and more elegant solutions on anything and try to run the configurations. Lots of tests cannot be properly loaded, or be initialized, they might run forever, or freeze the test process completely. Certainly many tests fail due to site specific settings. And of course many tests just fail.

== General == Tests should have the following features:

• Automatically executable AND terminating without any user interaction or user supervision.
• Not taking an exceptional long time, if it is not necessary for the test.
  • E.g. check for database connections in the test setup once. Do not wait for connection timeout for any test to figure out that the test eventually fails.
• Do not use excessive logging (there's no need if no one's watching), concentrate on important test debug info.
• Use a Logger, not the standard console, if possible.

We distinguish between different types of tests, which are identified by the filename and/or annotations

• Plain JUnit tests: {{{*UnitTest.java}}}
• JUnit Plug-in tests that need the Eclipse runtime: {{{*UiPluginTest.java}}}
• JUnit Plug-in tests that need the runtime but no GUI: {{{*HeadlessTest.java}}}
• A demo that requires user input or other interaction. Not a real test, but happens to be implemented with JUnit: {{{*Demo.java}}}

There is a plugin org.platform.testsuite that implements a testsuite that is configured by different launch configurations:

• !AllTests.launch (any *!Test.class) started vs the common css product with a lot of perm gen space
• !HeadlessTests.launch (any *!HeadlessTest.class) started vs the headless application
• !UnitTests.launch (any *!UnitTest.class) started vs the headless application
• !UiPluginTests.launch (any *!UiPluginTest.class) started vs the common css product

Any of these configurations starts a JUnit Plugin test that is supposed to load all classes from all plugins present and analyse them for being a test.

Valid bundle roots are currently:

• org.csstudio
• org.remotercp
• de.desy

Blacklisted bundles (not considered):

• org.csstudio.platform.libs (is supposed to contain loads of classes from 3rd parties)

Blacklisted packages (as they are part of valid bundles):

• !org.apache

Any loaded class is analysed to be either an extension of junit.framework.!TestCase or containing public methods annotated with @org.junit.Test, if so and it is a member of a valid bundle, the class is added to the test suite. If the class is a test, but does not end on {{{*Test.class}}}, a warning is logged, as this class is not added to the testsuite. If the class is not a test, but ends on *Test.class, another warning is logged (often observed for demo applications).

== Test configuration and test data for different sites ==

Many tests require different configurations and expected data to function properly on different sites. For instance the org.csstudio.rack.sns.SNSRackDataTest depends on the hard coded jdbc connections specific to the sns product and environment. If other developers would like to run this test, they have to refactor the test to be configured for their use.

A first solution is provided by the org.csstudio.platform.test.!TestDataProvider.

An example can be found in a allegedly obsolete test class (org.csstudio.archive.rdb.!TestSetup). Here, the site specific properties and parameters have been extracted into snsTestConfiguration.ini and desyTestConfiguration.ini files. Any test class requiring these site specific properties can include the following code: {{{ private static TestDataProvider PROV; static { try { ... PROV = TestDataProvider.getInstance(Activator.ID); } catch ... } }}} Once started the test runs with these properties, making database connections, configuring specific search queries, and comparing specific return values. The properties are just loaded once per bundle, even when this code snippet is put in many test classes of a bundle.

=== How does the plugin including the tests know which of the test configuration files shall be loaded? === Go to the Eclipse menu, Windows->Preferences->Java->Installed JREs. Choose any installed JRE and edit the jvm args to contain: -DsiteId=DESY or -DsiteId=SNS or -DsiteId=ITERorwhatever

The valid values for this siteId parameter can be found in org.csstudio.platform.test.SiteKey. There a configuration file prefix is defined for any site:

• DESY : desy => desyTestConfiguration.ini
• SNS : sns => snsTestConfiguration.ini
• WHATEVER : blubb => blubbTestConfiguration.ini

Until now, only three keys (DESY, SNS, ITER) have been added. Please add or modify the list for your needs. A bit tedious with the jvm arg, I just did not find a better and quick way to implement the site switch outside the test code.