Testing Conventions Used in the Apache Harmony Class Library

This document describes PROPOSED placement and package naming conventions for different types of Harmony class library tests.

The Harmony class library code is organized into modules that might have their own specifics. This document provides general guidlines and recomendations that might be adapted/modified to reflect module specifics.

Location of the Tests in the Directory Tree

Each Java class belongs to a specific module of the Harmony class library. Tests against classes belonging to a module belong to the same module. Tests, their resources, and support classes are located under:

<modulename>/src/test

Tests that are specific for Harmony, testing Harmony implementation details, and may fail on RI or other compliant implementations are separated from the implementation-independent tests that must pass on RI and all conformant implementations.

<modulename>/src/test/impl - Harmony specific tests
<modulename>/src/test/api - Implementation-independent tests

Special-purpose tests like stress tests or tests that require special configuration are separated from general-purpose tests.

<modulename>/src/test/stress

Tests are not separated by functionality under test, for example, tests against clone() methods are NOT separated from tests against equals() methods. Find more details below.

The test code is placed in directories as suggested by Apache Maven project conventions:

<modulename>/src/test/api/java - Java code
<modulename>/src/test/api/resources - Test resources

Some modules might have implementation specific tests that are in this case separated on a directory level:

<modulename>/src/test/impl/boot - Package private tests
<modulename>/src/test/impl/linux - Linux specific tests
<modulename>/src/test/impl/windows - Windows specific tests

If one pretends to test implementation independent platform-specific functionality, the test should be placed at <modulename>/src/test/api directory and check platforms from test internals.

Package and Class Names for Different Types of the Tests

If the test is designed to be run from bootclasspath, then its package is the same as the package of the class under the test.

If the test is designed to be run from classpath then:

If the package under test belongs to a public package, for example, it is a part of the API specification, then the test's package is:

org.apache.harmony.<modulename>.tests.<package under test>

Example

org.apache.harmony.luni.tests.java.lang
org.apache.harmony.crypto.tests.javax.crypto
org.apache.harmony.auth.tests.org.ietf.jgss

If the package under test belongs to org.apache.harmony namespace so that class's package is:
```
org.apache.harmony.<modulename>.<rest of the package name>
```
then the test's package is:
```
org.apache.harmony.<modulename>.tests.<rest of the package name>
```
Example

org.apache.harmony.luni.internal.net.www.protocol - package under test
org.apache.harmony.luni.tests.internal.net.www.protocol - package for the test

To avoid collision of test results for various type of tests, reflect a test type in a test name.

Example

To separate the impl test results from the api ones, the impl test names end with _ImplTest:

org.apache.harmony.javax.crypto.tests.javax.crypto.CipherTest - Implementation independent test for javax.crypto.Cipher
org.apache.harmony.javax.crypto.tests.javax.crypto.Cipher_ImplTest - Implementation specific test for javax.crypto.Cipher