TCDev Plugin
Terracotta has built a custom Eclipse plugin for running unit tests within the IDE.
The context menu option: "Run as Terracotta Test" extends the standard JUnit plugin and essentially verifies the state of the build, running tcbuild check_prep if necessary. Just as with JUnit you have the option to run in debug mode. The tests are saved with the arguments automatically set (you will no longer need to edit arguments in the run menu). Clicking the green run icon to re-run a test will bypass the Terracotta plugin and run the standard JUnit plugin. The idea is that you should only run against the build system for the first iteration within a project. Running a test in a different project will require that you clean all projects, build-all and re-run "Run as Terracotta Test". This annoyance will go away once our migration to Maven is complete.
Installation
Before installation
- Install Eclipse 3.2.1 (we don't yet support Eclipse 3.3). We take advantage of a new feature which allows project specific JRE compilation. This is tested to work on Eclipse version 3.2.1.
- Make sure you are running Eclipse itself in a 1.5 JVM, the plugin requires this.
- To check this go to "Help / About Eclipse" and select the "Configuration details" button. This will show you the system properties and you can check the java.vm.version property for 1.5
- Make sure you have a true 1.4 JVM as the default for the J2SE-1.4 execution environment
- From the Eclipse preference panel, navigate to "Java / Installed JREs / Execution Environments"
- Highlight "J2SE-1.4", you should see a list of 1.4 compatible JVMs
- Make sure that there is a check mark next to a "true" 1.4 JVM; 1.5 is compatible but tcbuild requires that a actual 1.4 JDK be used (this is important for boot JARs)
- Highlight "J2SE-1.5" and make sure there is a check mark next to a "true" 1.5 JVM
Running Container Tests
- In order to run container tests using this plugin you will need to create/modify the file code/base/build-config.local with the following line:
tc.tests.configuration.appserver.home=<THE VALUE OF $TC_CONTAINER_HOME>
- This will ensure that a default container is available to the unit test's VM.
Install via the update site
- You can install/update the plugin by using this Eclipse update site: http://download.terracotta.org/tcdev-updatesite
- Go to "Help / Software Update / Find and Install..."
- Select "Search for new features" and choose "Next"
- Choose "New Remote Site" and enter a name of your choosing, and the URL http://download.terracotta.org/tcdev-updatesite - then choose "Ok"
- Make sure your new update site is checked, then choose "Finish"
- The wizard should walk you through the license agreement and install the plugin for you, requiring you to restart Eclipse
Post installation
If you do not see a new menu item called "TCDev" then you are probably not running Eclipse with a 1.5 JVM, please see the pre-installation section above. You should now be able to right-click on a test case, choose "Run as" or "Debug as" and choose "Terracotta test" from the sub-menu. Eclipse will appear to hang as tcbuild is run in the background, give it a little time and the build output will appear in the Eclipse console and your test will begin to run.
The plugin does interact with the build system; if things ever misbehave clean the "common" project and tcbuild will be re-run on your next test run (it does not run if it doesn't need to).
The line: "Running: tcCheckPrep()" is printed in the "TCDev" console when the "Run as Terracotta test" is called, and the output of the tcbuild command should print to the Terracotta console window.
Keeping it up to date
You can periodically check the update site for updates (any important or notable updates will probably be prefaced with an announcement on the Eng mailing list) to the plugin by going to "Help / Software Updates / Manage configuration", highlighting "Terracotta development x.x.x" and choosing "Scan for updates." Any new updates will automatically be installed by Eclipse; you should restart Eclipse after this if there were in fact updates.
