0.1 - Reporting Bugs

So you found a bug in ApacheDS. Don’t worry this is a good thing! We can fix it but need your help. There are different degrees to your ability to help out. Some of you have developer skills so you might be able to write a test case that pin points that bug.

This wiki page shows you how you can help us to help you.

Creating a testcase project: using the apacheds-archetype-testcase.

We’ve created a simple archetype for you to rapidly create a Maven project that fires up ApacheDS in embedded mode within a JUnit testcase. This test case will start up ApacheDS as a server on any available port above 1024 on your machine. You can then use JNDI or the Apache LDAP API going over the wire on that port above 1024. You can also use the ApacheDS core API to access the data directly.

So you can write client code in your test case immediately. Just add your code, tar gzip the project, and attach it to your JIRA issue on the ApacheDS JIRA here:

https://issues.apache.org/jira/browse/DIRSERVER

We’ll prioritize your bug higher than others and probably fix it rapidly because the problem is isolated thanks to your testcase submission. We will in fact strip out your testcase and add it to our suite of test cases to make sure ApacheDS always passes this integration test you’ve provided.

Installing the apacheds-archetype-testcase

To use the archetype you’ll need to check it out and install it. Here’s how you can do that for the leading edge of 2.0.0:

svn co http://svn.apache.org/repos/asf/directory/documentation/samples/trunk/apacheds-archetype-testcase
cd apacheds-archetype-testcase
mvn install

This will install the archetype onto your local repository. Now you can invoke the archetype.

Invoking (running) the archetype: generating the testcase project

Once you checkout the archetype plugin and install it you can use it like so to generate a foo-test project:

mvn archetype:generate -DarchetypeGroupId=org.apache.directory.samples \
                       -DarchetypeArtifactId=apacheds-archetype-testcase \
                       -DarchetypeVersion=1.5.5-SNAPSHOT \
                       -DgroupId=com.acme -DartifactId=foo-test -Dpackage=com.acme

This will generate the default test case project with the following tree structure:

~/foo-test$ tree
.
|-- pom.xml
|-- src
    |-- main
    |   |-- java
    |       |-- com
    |           |-- acme
    |               |-- Dummy.java
    |-- test
        |-- java
        |    -- com
        |        -- acme
        |           |-- AdvancedTest.java
        |           |-- AdvancedTestApacheDsFactory.java
        |           |-- MinimalTest.java
        |-- resources
            |-- log4j.properties
            |-- sevenSeas_data.ldif
            |-- sevenSeas_schema.ldif

10 directories, 8 files

• Dummy.java - this is just a placeholder file to make sure that Maven works properly.
• MinimalTest - a minimal ApacheDS Integration Test. It contains two test methods to demonstrate usage of JNDI and the ApacheDS core API. Add your own test method here.
• AdvancedTest - an advanced ApacheDS Integration Test in case you need a special configuration for your test. It demonstrates how to add a new partition, how to enable LDAPS, how to enable a disabled schema, how to inject a custom schema, and how to inject custom test data.
• AdvancedTestApacheDsFactory - configures ApacheDS for the advanced test
• pom.xml - the Maven Project Object Model (POM) for your new testcase project (can remain as is).
• log4j.properties - Log4j configuration file that controls ApacheDS logging for your convenience; edit this file to control logging output.
• sevenSeas_data.ldif - sample custom test data used by the advanced test.
• sevenSeas_schema.ldif - sample custom schema used by the advanced test.

Once you do this you can cd into foo-test and just build and test it for fun to see what happens. This will build, and test the sample test cases (they should pass) that comes packaged with the project you just created. CD into foo-test and run the following command:

mvn test

Now you can customize the MinimalTest.java or AdvancedTest.java file to isolate your bug. Open the classes with your favorite editor and goto town. However if you want to pull this project into your IDE and edit it there you can use Maven’s IDEA, Eclipse and Netbeans integration to create IDE project descriptors for them. Then you can import this project into your IDE. Here’s how:

For IDEA

mvn idea:idea

For Eclipse

mvn eclipse:eclipse

For Netbeans

See this page: http://maven.apache.org/guides/mini/guide-ide-netbeans/guide-ide-netbeans.html.

Note about version

Note that this archetype is specific for ApacheDS 1.5.5.

Why a Maven Archetype for Testing?

• Easy and fast to start integration testing ApacheDS.
• We (developers of ApacheDS) can use it ourselves.
• We want users of ApacheDS to help us help them.
• Users need to customize a project with perhaps additional dependencies.
• Users can add many test cases to the project.
• Tests isolating custom bugs can be incorporated into our community test suite for ApacheDS.