FAQ #9 - How to configure unit testing an ADF BC project using JUnit in JDeveloper 11g

Introduction

Unit testing an ADF BC project in JDeveloper could be a straightforward task when using the JUnit ADF Business Components Test Suite Wizard. There are a few twists and turns on the way, which once straightened out should make unit testing a routine. Let’s take a closer look.

Main Theme

Prerequisites

Before beginning with unit testing your ADF BC project, the necessary components must be installed in JDeveloper. Start JDeveloper and using the Help | Check for Updates... wizard ensure that both the JUnit Integration and BC4J JUnit Integration library updates are downloaded and installed from the Official Oracle Extensions and Updates site.

Also, you should have created application modules in your BC project before you begin. Lastly, I will also advise you to create a separate application module configuration specifically for unit testing. There are a couple of reasons why you want to do so:

1. For JUnit, a JDBC URL connection string is needed to access the database since a JDBC datasource won't work outside the Java EE container, and
2. In order to overcome an "ORA-01005: null password given; logon denied" database connection error when running the unit tests, we must provide the database schema password ourselves.

To create the unit testing application module configuration, in the Model BC project, right-click on the application module and select Configurations... to bring up the Manage Configurations dialog. Select the Local configuration and click Copy to make a copy of it. Once copied, select the new configuration, click Edit... and change its name. Then, ensure that the Connection Type is set to JDBC URL. Click OK a couple of times to save the new configuration. In the attached example, we have copied the HrAppModuleLocal configuration to HrAppModuleJUnit.

Configure the Unit Tests

To configure unit testing for your ADF BC project, you need to first create a separate Java Project. From the New Gallery dialog - File | New...  - select Projects under the General category and Java Project from the Items list to create a generic Java project.

Name the project, setup the project package and source paths and click Finish to create it.

Once the unit test project is created, select it in the Application Navigator and run the New Gallery wizard once more, this time selecting Business Components Test Suite from the General | Unit Tests category.

In the Configure Tests page specify your Business Components Project, the Application Module and the Configuration to be unit tested. Ensure that you specify the application module configuration that you created earlier specifically for unit testing purposes.

Verify your selections and click Finish. The wizard will generate tests for each view object in the application module. Tests for exported application module methods will also be generated. If the application module does not have exported methods, the wizard will also generate a test for the application module itself.

For the sample project, the generated test files are shown below.

Before running the unit tests, build the unit test project.

Run the Unit Tests

We will run the unit tests as part of an Ant build script. In the ADF BC Model project, bring up the New Gallery dialog, select Ant from the General category and Buildfile from Project from the Items.

In the Create Buildfile from Project dialog accept the defaults and press OK. This will create the build.xml and build.properties Ant files under the Resources folder in the project.

In accordance with the official documentation, all it takes is the addition of an Ant target similar to this:

So, let's modify it accordingly and add it to the build.xml Ant script:

For the name attribute of the <test> tag element, we need to specify the all-tests class generated earlier - AllHrAppModuleTests in the example. The todir attribute of the same tag indicates the location of the unit test output result files: in this example we have defined the junit.output.dir macro to point to the ../JUnit/output directory in build.properties. Ensure that the output directory is created as well.

We should be about ready now. Let's right click on the build.xml Ant script in the Application Navigator, select the JUnit target and run it.

Twists and Turns ... or Adventures in Unit Testing

The first thing you see when you run the unit test target is an Ant error in the Apache Ant - Log console:

The error message is pretty straightforward: Ant does not like the nested <pathelement> tag, so let's remove it and re-run the unit test target.

This time the Log console shows:

This is definitely an improvement! A unit test output file is generated this time, in the ${junit.output.dir} directory. By examining its contents, it is obvious that the all-tests class could not be located by Ant.

In order to solve this issue, we need to add a <pathelement> tag with the location of the unit testing classes for the classpath <path> tag in build.xml as it is shown below:

Running it this time produces the following error:

OK, we are getting closer - the unit test Ant target runs just fine but the unit tests themselves all fail! For some unexplained reason, the database password is not supplied, the connection to the database fails and that makes the unit tests to fail. To bypass this annoyance, we need to supply the database password ourselves. In order to this, we need to create our own custom database transaction implementation and override the connect() method in order to supply the database password - if it is null that is. The process of creating a custom database transaction is explained thoroughly in the official documentation. Briefly:

1. Extend the DBTransactionImpl2 class in order to override the method(s) you need, in this case the connect() method to supply the password.
2. Extend the DatabaseTransactionFactory class, override the create() method and return the custom database transaction (step 1), and
3. Modify the application module configuration to use the custom transaction factory.

These steps are illustrated below:

1. Extend the DBTransactionImpl2 class in order to override the method(s) you need, in this case the connect() method to supply the password:

 2. Extend the DatabaseTransactionFactory class, override the create() method and return the custom database transaction (step 1):

3. Modify the application module configuration to use the custom transaction factory:

Bring-up the application module configuration that you created specifically for unit testing and specify your own custom transaction factory class for the TransactionFactory property.

Now re-build the BC project and re-run the unit tests. Everything should run smoothly and the unit test output file should look similar to this:

That's all folks, you've made it through a unit testing adventure!

[updated on May 26th, 2010]
Since this post was published, Oracle has come up with a series of How-to articles related to JDeveloper. One article in particular, related to JUnit can be found here: Unit Testing Your Application with JUnit.

Conclusion

Once you go through the hurtles of configuration, the process of unit testing your ADF Business Components project should be straightforward, automatic and hopefully routine. Assuming that your test cases make sense, it will prove to be another valuable tool in your toolbox.

Until the next time, keep on JDeveloping!

References

30.8.7 How to Run a JUnit Test Suite as Part of an Ant Build Script
36.8.4.2 Configuring an Application Module to Use a Custom Database Transaction Class

Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo9.rar