Difference between revisions of "OSEE/Developer Guidelines"

From Eclipsepedia

Jump to: navigation, search
(Import OSEE Team Preferences)
Line 1: Line 1:
__NOTOC__
+
 
 
= Before Committing Code =
 
= Before Committing Code =
  
Line 76: Line 76:
  
 
== Monitor OSEE Bugs using Mylyn ==
 
== Monitor OSEE Bugs using Mylyn ==
 +
 +
== Coding Standards ==
 +
 +
=== Utility Classes ===
 +
 +
In order to optimize reuse of code, OSEE developers have adopted a set of standards.
 +
 +
Utility classes should:
 +
# Be named xxxUtil.  This allows for each searching and location by looking for *Util.  This excludes stand-alone utility classes like HashCollection or CountingMap.
 +
# As much as possible, be located in a package postfix'd with .util. eg. org.eclipse.osee.ats.util
 +
# Should contain static methods
 +
 +
==== Cleanup of existing utility methods ====
 +
 +
The following needs to be done:
 +
# Create set of common utility class names
 +
# Move utilities to their respective places
 +
# Either deprecate or replace uses of old locations
 +
 +
=== Comments ===
 +
Most comments offer more clutter than information, especially <tt>non-Javadoc</tt> comments which can be removed using the following regular expression <code>\R&#91; \t&#93;*/\*\s+&#91;\* &#93;*\(non-Javadoc\)&#91;^/&#93;+/</code>.
 +
 +
=== OSEE Master Test Suite ===
 +
 +
OSEE uses JUnit 4 for its test suites.  Some links to get started:
 +
* [http://www.cavdar.net/2008/07/21/junit-4-in-60-seconds/ Jnit4 in 60 seconds]
 +
* [http://stackoverflow.com/questions/264680/best-way-to-automagically-migrate-tests-from-junit-3-to-junit-4/677356 Upgrading to JUnit4]
 +
 +
==== Use Cases ====
 +
 +
Requirements of the OSEE test suite:
 +
 +
# Single button press to run all tests
 +
# Minimal number of launch configurations to maintain
 +
# Ability for any user, internal or external, to easily run a suite of tests before commit
 +
# Continuous integration (checkout, build, test, report)
 +
# Use JUnit framework for all testing
 +
# Enable health checks against production database to be part of test suite
 +
# New test cases can be added easily
 +
 +
==== Running the OSEE Test Suite ====
 +
 +
The OSEE test suite uses the <tt>org.eclipse.osee.ats.config.demo</tt> plugin to initialize a demo database, populate it with demo data and run the majority of the OSEE tests against this common data set.
 +
 +
These tests are contributed to the MasterTestSuite groups using Eclipse's extension point framework.  Any Test Suite can implement IOseeTest and extend the OseeTest extension point to be contributed to the appropriate test suite(s).
 +
 +
===== Steps to test =====
 +
# Checkout org.eclipse.osee.ats.config.demo
 +
# Checkout org.eclipse.osee.support.test
 +
# Run the following tests in order and resolve any errors:
 +
## Run the Demo database tests:
 +
### Run the '''OSEE Demo Application Server''' launch config
 +
### Run the '''MasterTestSuite_DemoDbInit''' launch config.  This initializes the postgres database for demo populate and tests
 +
### Run the '''MasterTestSuite_DemoDbPopulate''' launch config.  This loads the database with branches, actions and sets conditions for populate tests.
 +
### Run the '''MasterTestSuite_DemoDbTests''' launch config.  This runs tests against the DemoDb Populated database.
 +
### Stop the '''OSEE Demo Application Server''' if still running
 +
## Run the Production TestDb tests:
 +
### Run the '''OSEE Application Server''' launch config.
 +
### Run the '''MasterTestSuite_TestDbInit''' launch config.  This initializes the postgres database for production testdb tests
 +
### Run the '''MasterTestSuite_TestDbTests''' launch config. - This runs production specific tests using a TestDb.
 +
## Run the Production tests and health checks against the current production release
 +
### Run the '''MasterTestSuite_ProductionTests''' launch config.  This runs tests and health checks against the current production released database.
 +
 +
====Common test utility plugin====
 +
 +
The plugin org.eclipse.osee.support.test.util is in support of our testing framework.  It has a number of common enums and a TestUtil class that should be used by any junit tests.  The intent is to keep this plugin lightweight and without many dependencies cause all the testing fragments "should" include it.  In addition, it should not be included by any production plugins, only test fragments.
 +
 +
==== Adding new Tests to MasterTestSuite ====
 +
 +
==== To create test fragment off plugin to be tested ====
 +
All OSEE JUnit tests should live in a fragment of the plugin to be tested.
 +
# Select plugin to be tested
 +
# Right-click -> New Project -> Plugin Project -> Plugin Fragment
 +
# Enter plugin to be tested as Host plugin
 +
# Complete wizard
 +
# In plugin to be tested (eg org.eclipse.osee.ats)
 +
## Add "Eclipse-ExtensibleAPI: true" to MANIFEST.MF of plugin to be tested.  This allows test suites to see tests in this plugin
 +
# In new fragment (eg org.eclipse.osee.ats.test)
 +
## Add org.junit4 (make sure junit4, not junit) to dependencies
 +
## Add the common test utility plugin org.eclipse.osee.support.test.util plugin to dependencies
 +
## Export packages containing TestCases and TestSuites
 +
# In MasterTestSuite plugin (eg org.eclipse.osee.support.test)
 +
## Add dependency on plugin to be tested (ge org.eclipse.osee.ats)
 +
## Add test cases and suites from fragment to appropriate MasterTestSuite java Test Suites
 +
 +
==== To add a new JUnit TestCase ====
 +
# Write the TestCase to run against a database populated with DemoDbInit and DemoDbPopulate
 +
# Add the TestCase to an existing MasterTestSuite_DemoDbTests test suite
 +
 +
==== Things to consider ====
 +
# Your tests must clean-up after themselves to ensure that the entire test suite can be run. 
 +
# Do not assume order of execution except within your own Test Suite
 +
 +
===To add a new JUnit TestSuite===
 +
# Create a fragment for the plugin (see above)
 +
# Create new JUnit TestCases as above
 +
# Create a new JUnit TestSuite
 +
# Add new TestSuite to one of the MasterTestSuite java test suites
  
 
[[Integrating OSEE and Bugzilla|'''Integrating OSEE and Bugzilla''']]
 
[[Integrating OSEE and Bugzilla|'''Integrating OSEE and Bugzilla''']]
  
 
[[Category:OSEE]]
 
[[Category:OSEE]]

Revision as of 18:40, 19 August 2009

Contents

Before Committing Code

  1. Synchronize and Update
  2. Run Code Quality Checks
  3. Ensure all the tests are green. (Tests projects can be identified by their '*.test' suffix. All tests have to be executed as plug-in unit tests.)
  4. Ensure the reference documentation is up to date (i.e. reflects your changes) (Documentation is maintained in project 'via the OSEE wiki').

Code Quality Tools

Update your eclipse installation with the following tools:

Installation for Find Bugs, PMD, and Check Style:

  1. Launch Eclipse and go to Help->Software Updates->Available Software
  2. Drag the Update Site URLs into the Software Update and Add-ons dialog
  3. Select code style tools to install - for Find Bugs make sure you only select the Eclipse 3.4 or later entry
  4. Click the Install button
  5. Once installation completes, restart eclipse

Installation for Eclipse EMMA:

  1. Download zip file from the following link Eclipse Emma Zip File
  2. Unzip downloaded file into your dropins folder
  3. Restart Eclipse

Code Quality Configuration

Import OSEE Java Code Stype Settings

  1. Right-click on the following link OSEE Java Code Style Format
  2. Select Save Link As
  3. Enter osee_java_style_format.xml and click Save
  4. Launch Eclipse
  5. Select Window->Preferences->Java->Code Style->Formatter
  6. Click on Import..., navigate to the location where you saved osee_java_style_format.xml
  7. Click OK

Check Style Configuration

  1. Select Window->Preferences
  2. Select Checkstyle
  3. Under the General Settings set Rebuild projects if needed to always
  4. Under the Global Check Configurations, click the New button
  5. Select Remote Configuration under the Type drop down
  6. Set name to OSEE Checks (Eclipse)
  7. Copy the following link into the Location entry OSEE Checks (Eclipse)
  8. Set the Cache configuration file checkbox to true
  9. Click OK
  10. Select the OSEE Checks (Eclipse) configuration and click on Set as Default
  11. Click OK to accept settings

Find Bugs Configuration

  1. Select Window->Preferences->Java
  2. Select Find Bugs
  3. Set analysis effort to Default
  4. Click OK to accept settings

PMD Configuration

  1. Right-click on the following link OSEE PMD Rule Set
  2. Select Save Link As
  3. Enter osee_pmd_rule_set.xml and click Save
  4. In Eclipse, select Window->Preferences
  5. Select PMD->Rules Configuration
  6. Click on Import rule set...
  7. Click on Browse, navigate to the location where you saved osee_pmd_rule_set.xml
  8. Set the Import by Copy check box to true
  9. Select OK to import the rule set
  10. Select OK to accept the change and close the Preferences Dialog

Monitor OSEE Bugs using Mylyn

Coding Standards

Utility Classes

In order to optimize reuse of code, OSEE developers have adopted a set of standards.

Utility classes should:

  1. Be named xxxUtil. This allows for each searching and location by looking for *Util. This excludes stand-alone utility classes like HashCollection or CountingMap.
  2. As much as possible, be located in a package postfix'd with .util. eg. org.eclipse.osee.ats.util
  3. Should contain static methods

Cleanup of existing utility methods

The following needs to be done:

  1. Create set of common utility class names
  2. Move utilities to their respective places
  3. Either deprecate or replace uses of old locations

Comments

Most comments offer more clutter than information, especially non-Javadoc comments which can be removed using the following regular expression \R[ \t]*/\*\s+[\* ]*\(non-Javadoc\)[^/]+/.

OSEE Master Test Suite

OSEE uses JUnit 4 for its test suites. Some links to get started:

Use Cases

Requirements of the OSEE test suite:

  1. Single button press to run all tests
  2. Minimal number of launch configurations to maintain
  3. Ability for any user, internal or external, to easily run a suite of tests before commit
  4. Continuous integration (checkout, build, test, report)
  5. Use JUnit framework for all testing
  6. Enable health checks against production database to be part of test suite
  7. New test cases can be added easily

Running the OSEE Test Suite

The OSEE test suite uses the org.eclipse.osee.ats.config.demo plugin to initialize a demo database, populate it with demo data and run the majority of the OSEE tests against this common data set.

These tests are contributed to the MasterTestSuite groups using Eclipse's extension point framework. Any Test Suite can implement IOseeTest and extend the OseeTest extension point to be contributed to the appropriate test suite(s).

Steps to test
  1. Checkout org.eclipse.osee.ats.config.demo
  2. Checkout org.eclipse.osee.support.test
  3. Run the following tests in order and resolve any errors:
    1. Run the Demo database tests:
      1. Run the OSEE Demo Application Server launch config
      2. Run the MasterTestSuite_DemoDbInit launch config. This initializes the postgres database for demo populate and tests
      3. Run the MasterTestSuite_DemoDbPopulate launch config. This loads the database with branches, actions and sets conditions for populate tests.
      4. Run the MasterTestSuite_DemoDbTests launch config. This runs tests against the DemoDb Populated database.
      5. Stop the OSEE Demo Application Server if still running
    2. Run the Production TestDb tests:
      1. Run the OSEE Application Server launch config.
      2. Run the MasterTestSuite_TestDbInit launch config. This initializes the postgres database for production testdb tests
      3. Run the MasterTestSuite_TestDbTests launch config. - This runs production specific tests using a TestDb.
    3. Run the Production tests and health checks against the current production release
      1. Run the MasterTestSuite_ProductionTests launch config. This runs tests and health checks against the current production released database.

Common test utility plugin

The plugin org.eclipse.osee.support.test.util is in support of our testing framework. It has a number of common enums and a TestUtil class that should be used by any junit tests. The intent is to keep this plugin lightweight and without many dependencies cause all the testing fragments "should" include it. In addition, it should not be included by any production plugins, only test fragments.

Adding new Tests to MasterTestSuite

To create test fragment off plugin to be tested

All OSEE JUnit tests should live in a fragment of the plugin to be tested.

  1. Select plugin to be tested
  2. Right-click -> New Project -> Plugin Project -> Plugin Fragment
  3. Enter plugin to be tested as Host plugin
  4. Complete wizard
  5. In plugin to be tested (eg org.eclipse.osee.ats)
    1. Add "Eclipse-ExtensibleAPI: true" to MANIFEST.MF of plugin to be tested. This allows test suites to see tests in this plugin
  6. In new fragment (eg org.eclipse.osee.ats.test)
    1. Add org.junit4 (make sure junit4, not junit) to dependencies
    2. Add the common test utility plugin org.eclipse.osee.support.test.util plugin to dependencies
    3. Export packages containing TestCases and TestSuites
  7. In MasterTestSuite plugin (eg org.eclipse.osee.support.test)
    1. Add dependency on plugin to be tested (ge org.eclipse.osee.ats)
    2. Add test cases and suites from fragment to appropriate MasterTestSuite java Test Suites

To add a new JUnit TestCase

  1. Write the TestCase to run against a database populated with DemoDbInit and DemoDbPopulate
  2. Add the TestCase to an existing MasterTestSuite_DemoDbTests test suite

Things to consider

  1. Your tests must clean-up after themselves to ensure that the entire test suite can be run.
  2. Do not assume order of execution except within your own Test Suite

To add a new JUnit TestSuite

  1. Create a fragment for the plugin (see above)
  2. Create new JUnit TestCases as above
  3. Create a new JUnit TestSuite
  4. Add new TestSuite to one of the MasterTestSuite java test suites

Integrating OSEE and Bugzilla