Papyrus-RT/JUnit How-To

JUnit Tests

The primary test framework used for automated tests in Papyrus-RT is JUnit. It is convenient because it is supported by both the build system (Tycho/Maven) and the development environment (Eclipse PDE) to make it effortless to run regression tests before pushing changes, and not much more difficult to add new tests to cover new code.

Adding Tests

To add tests, simply add test methods (annotated with @Test in the usual JUnit 4 way) to an existing test class, or create a new test class. There are some guidelines/restrictions to be aware of, which mostly are provided for the developer's convenience:

• do name your test class with a suffix of Test, TestCase, or Tests or with a prefix of Test, but that makes all of your test classes look the same in the explorer, so I can't recommend that
  • e.g., XyzTest, XyzTests, XyzTestCase
  • these are the class name patterns that the Maven build looks for to discover and run your tests
• do feel free to create abstract test classes with any kind of name. Neither Maven nor PDE will attempt to run tests in an abstract class (because it cannot be instantiated, of course)
• don't use the word "Test" in the name of a supporting non-test class such as a rule, utility, bundle activator, or other fixture, in case it matches a pattern that Maven or PDE looks for and these systems try to run it as a test suite

Note, in particular, that the Papyrus-RT project does not use AllTests test suites to aggregate all the tests to be run. Every time you add a test class, you would have to update this, and if you ever forgot, then your tests would not run in the build and you would be sad to find some time later that they were failing for half a year unbeknownst to you. Maven and the PDE launch configurations automatically discover the tests to be run in the source project.

Adding Test Bundles

If you are adding a new bundle, you should probably add a corresponding test bundle for automated test coverage. It is highly recommended to start by copying a similar existing test project. The Oomph "Copy Project" context-menu action is very handy for this, as it takes care of setting the correct project name into the new project and metadata files such as .project, META-INF/MANIFEST.MF, and pom.xml besides copying all of the content.

New test bundles should be located under the tests/ folder of the Git repository in a sub-folder mirroring the location of the tested bundle project under the plugins/ folder.

• do remember to add your new test bundle(s) to the sub-modules of the releng/tests/pom.xml
• do add a launch configuration in the root of the project (rename the one that's already there if you Oomph-copied the project from an existing one)

The launch configuration mentioned above should automatically discover tests by choosing the "Run all tests in the selected project, package, or source folder" option:

• do configure the launch configuration to run all tests in the project's src folder, not the project root. This ensures that, when the day comes that EMF- or otherwise-generated tests are introduced in a src-gen/ folder, they won't be picked up automatically (see next item)
• don't configure the launch configuration to run tests on the UI thread, even if it uses the Eclipse SDK or Platform UI product. Any test that must run on the UI thread should use the UIThreadRule (see below)
• if your test bundle includes EMF-generated tests, be sure to generate them into a src-gen/ folder so that they aren't automatically discovered by PDE and Maven. This is important because if your model has operations or derived features for which tests are generated, these are often left unimplemented in superclasses, but EMF generates tests for them regardless that you shouldn't implement and shouldn't run. Also, EMF generates a test suite class that doesn't match any configured exclusion pattern, so you would end up with PDE and Maven executing all of the tests at least twice
  • do add a test class to in the src/ folder that is a suite simply including the EMF-generated test suite(s) for your model(s), to include them in the Maven and PDE test execution
  • do add an exclusion rule for the EMF-generated tests to your pom.xml to make sure that Maven won't find them (the launch config, as mentioned above, is looking only in the src/ folder, not also src-gen/)

Test Fixtures

The org.eclipse.papyrusrt.junit bundle contains a variety of reusable test fixtures, mostly test-rules and Hamcrest matchers, to ease the development of tests. This is a good place to add any new fixtures that may be of general use in the Papyrus-RT JUnit tests.

Of particular interest may be the UIThreadRule, which lets tests be assured of running in the SWT UI thread if that is something they need (for example, tests using the PapyrusEditorFixture from Papyrus often need this). For additional control, the @UIThread annotation may be used to mark specific tests that need the UI thread if not all tests in a class need it.