Package com.orchestranetworks.service.extensions

# Class TestHelper

java.lang.Object
com.orchestranetworks.service.extensions.TestHelper

public class TestHelper extends Object
This class can be used to write JUnit tests for EBX®.

Like `BatchLauncher`, it provides a "serverless" environment for executing EBX® (the Java Virtual Machine does not require a running application server). The main difference compared to `BatchLauncher`, is that `TestHelper` does not execute tests on the repository that is specified by 'ebx.properties' file. Each test runs on its own newly created repository.

#### General Configuration:

In order to be used, the environment must conform to the following principles:

- The EBX® root module and all specific modules needed for running the tests must be expanded under the expected directory (see `prepareEnvironment(File, File)`).
- The default EBX® repository, specified in `ebx.properties`, cannot be used (it is not initialized): a sandbox repository must be used instead, it is provided by the method `getNewRepository(File)`.
- The default directory is also not accessible (because it is based on the default repository): a specific user directory must be specified in `ebx.properties`, so that sessions can be authenticated through at least one defined user (see `DirectoryFactory`); a hard-coded directory can be used.

#### Code example:

Here, a JUnit test class performs some updates on the EBX® repository and checks those updates:

public class TestSimple extends junit.framework.TestCase
{
protected void setUp() throws Exception
{
TestHelper.prepareEnvironment(new File(".."), new File("./ebx.properties"));
}
public void testSimple() throws Exception
{
File tempDir = TestHelper.createTemporaryDirectory(this.getClass().getName() + "."
+ this.getName());
Repository repository = TestHelper.getNewRepository(tempDir);
//Directory must specify the following user with admin rights.
Session session = repository.createSessionFromLoginPassword(
"testAdministrator",
"testAdministratorPassword");
AdaptationHome home = this.createWorkingHome(repository, session);
ProgrammaticService ps = ProgrammaticService.createForSession(session, home);
AdaptationReference name = this.createAdaptation(ps);
Adaptation adaptation = home.findAdaptationOrNull(name);
assertNotNull(adaptation);
AdaptationTable aTable = adaptation.getTable(Path.parse("/root/structuresAndTypes/simpleTypesInTable1"));
RequestResult result = aTable.createRequest().execute();
assertTrue(result.isEmpty());
this.createRecords(aTable, ps);
result = aTable.createRequest().execute();
assertEquals(10, result.getSize());
//Needed to clean the repository before other tests
TestHelper.shutdownRepository(true, repository);
}
private void createRecords(
final AdaptationTable aTable,
ProgrammaticService aProgrammaticService)
{
Procedure createRecords = new Procedure()
{
public void execute(ProcedureContext context) throws Exception
{
context.setAllPrivileges(true);
for (int i = 0; i < 10; i++)
{
ValueContextForUpdate vc = context.getContextForNewOccurrence(aTable);
vc.setValue("key" + i, Path.parse("/string"));
context.doCreateOccurrence(vc, aTable);
}
}
};
aProgrammaticService.execute(createRecords);
}
private AdaptationHome createWorkingHome(Repository repository, final Session session)
throws OperationException
{
HomeCreationSpec aSpec = new HomeCreationSpec();
aSpec.setParent(repository.getReferenceBranch());
aSpec.setKey(HomeKey.forBranchName("child"));
aSpec.setOwner(session.getUserReference());
AdaptationHome home = repository.createHome(aSpec, session);
return home;
}
private AdaptationReference createAdaptation(ProgrammaticService aProgrammaticService)
{
final SchemaLocation location = SchemaLocation.forPathInModule(
"/WEB-INF/ebx/schema/sample-many-simple-tables-100.xsd",
"module-sample");
final AdaptationReference name = AdaptationReference.forPersistentName("test");
assertNull(aProgrammaticService.getCurrentHome().findAdaptationOrNull(name));
Procedure createInstance = new Procedure()
{
public void execute(ProcedureContext aContext) throws Exception
{
aContext.doCreateOccurrence(location, name, aContext.getSession().getUserReference());
}
};
aProgrammaticService.execute(createInstance);
return name;
}
}

In order to run such a test, it is necessary for the classpath to include:

- all of the libraries required to run a standard EBX® repository,
- Ant 1.6 or greater.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TestHelper()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static File`
  `createTemporaryDirectory(String aDirectoryPrefix)`
  Creates a new temporary directory.
  `static Repository`
  `getNewRepository(File aTargetDirectory)`
  Creates a new temporary repository for running tests with workflow API disabled.
  `static Repository`
  `getNewRepository(File aTargetDirectory, boolean isWorkflowEnabled)`
  Creates a new temporary repository for running tests.
  `static Repository`
  `getRepositoryCopyOfExistingH2StandaloneDB(File aSourceDirectory, File aTargetDirectory, String aPrefix)`
  Creates a temporary copy of the specified existing repository for running tests with workflow API disabled.
  `static Repository`
  `getRepositoryCopyOfExistingH2StandaloneDB(File aSourceDirectory, File aTargetDirectory, String aPrefix, boolean isWorkflowEnabled)`
  Creates a temporary copy of the specified existing repository for running tests.
  `static Repository`
  `getRepositoryExistingH2StandaloneDB(File aSourceDirectory, String aPrefix)`
  Gets an existing H2 repository to use for running tests with workflow API disabled.
  `static Repository`
  `getRepositoryExistingH2StandaloneDB(File aSourceDirectory, String aPrefix, boolean isWorkflowEnabled)`
  Gets an existing H2 repository to use for running tests.
  `static void`
  `prepareEnvironment(File modulesRootDir, File propertiesFile)`
  Prepares the environment for the test.
  `static void`
  `shutdownRepository(boolean checkConnectionsHaveBeenClosed, Repository aRepository)`
  Shuts down the specified repository.
  `static void`
  `shutdownRepository(Repository aRepository)`
  Shuts down the repository, and checks that all connections to the database have been closed.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### TestHelper

    public TestHelper()

- ## Method Details

  - ### prepareEnvironment

    public static void prepareEnvironment(File modulesRootDir, File propertiesFile) throws Exception
    Prepares the environment for the test. This method must be called prior to any call to the method `getNewRepository(File)`.
    Parameters:
      `modulesRootDir` - indicates the root directory in which to look for EBX® modules to be registered. The search is recursively executed under the specified directory, according to the following regexp: `*/webapps/*`. This means that every required EBX® module, including the root module and the manager module, must be placed in a directory named `webapps`. Additionally, all modules must be expanded (they must not remain packaged as WAR files). Here is an example of a directory tree structure with two modules (predefined `ebx-root-1.0`, `ebx-manager` and specific `module-sample`) and where modulesRootDir is the "Root" directory :

               Root
                  `-- test-project
                                 `-- webapps
                                           |-- ebx-root-1.0
                                           |   |-- META-INF
                                           |   |   `-- MANIFEST.MF
                                           |   |-- WEB-INF
                                           |   |   |-- ebx
                                           |   |   |   |-- ...
                                           |   |   |   |-- module.xml
                                           |   |   |   `-- ...
                                           |   |   |-- lib
                                           |   |   |   `-- ebx-root-1.0.jar
                                           |   |   `-- web.xml
                                           |   `-- www
                                           |       `-- common
                                           |           `-- ...
                                           |-- ebx-manager
                                           |   `-- ...
                                           `-- module-sample
                                               `-- WEB-INF
                                                   |-- ebx
                                                   |   |-- module.xml
                                                   |   `-- schema
                                                   |       `-- sample-many-simple-tables-100.xsd
                                                   `-- web.xml

      `propertiesFile` - the path to the `ebx.properties` file.
    Throws:
      `Exception`

  - ### createTemporaryDirectory

    public static File createTemporaryDirectory(String aDirectoryPrefix) throws Exception
    Creates a new temporary directory.

    The actual location of the directory to be created is:

           ${ebx.temp.directory}/ebx.platform.test/${aDirectoryPrefix}/

    Where the property `ebx.temp.directory` is specified in the `ebx.properties` file. If that directory exists, it is deleted then recreated from scratch.

    Throws:
      `Exception`

  - ### getNewRepository

    public static Repository getNewRepository(File aTargetDirectory)
    Creates a new temporary repository for running tests with workflow API disabled.

    This method is equivalent to:

    > `TestHelper.getNewRepository(aTargetDirectory, false);`

    See Also:
      - `getNewRepository(File, boolean)`

  - ### getNewRepository

    public static Repository getNewRepository(File aTargetDirectory, boolean isWorkflowEnabled)
    Creates a new temporary repository for running tests. This method must be called instead of `Repository.getDefault()`.

    The created repository will be based on a standalone H2 database. The database files will have the following physical location:

           {aTargetDirectory}/h2/repository*

    Warning:

    1. If the database files already exist, all existing tables will be dropped upon the first repository access.
    2. When the test completes, it is required to shut down the repository. Invoking this method a second time without having shut down the first repository has unpredictable effects.
    Parameters:
      `aTargetDirectory` - location of the created H2 database. Tests will run on this database.
      `isWorkflowEnabled` - must be `true` to enable the workflow API. If `false` workflow will be disabled and repository initialization will be faster.
    Since:
      5.7.0 fix A
    See Also:
      - `shutdownRepository(Repository)`

  - ### getRepositoryExistingH2StandaloneDB

    public static Repository getRepositoryExistingH2StandaloneDB(File aSourceDirectory, String aPrefix)
    Gets an existing H2 repository to use for running tests with workflow API disabled.

    This method is equivalent to:

    > `TestHelper.getRepositoryExistingH2StandaloneDB(aSourceDirectory, aPrefix, false);`

    Since:
      5.3.0

  - ### getRepositoryExistingH2StandaloneDB

    public static Repository getRepositoryExistingH2StandaloneDB(File aSourceDirectory, String aPrefix, boolean isWorkflowEnabled)
    Gets an existing H2 repository to use for running tests.

    The H2 database files must exist at the following location:

           {aSourceDirectory}/h2/repository*

    Note: This will modify the existing database directly. To run tests on a copy of an existing database, use `getRepositoryCopyOfExistingH2StandaloneDB(File, File, String)`.

    Parameters:
      `aSourceDirectory` - location of the existing H2 database.
      `isWorkflowEnabled` - must be `true` to enable the workflow API. If `false` workflow will be disabled and repository initialization will be faster.
    Since:
      5.7.0 fix A

  - ### getRepositoryCopyOfExistingH2StandaloneDB

    public static Repository getRepositoryCopyOfExistingH2StandaloneDB(File aSourceDirectory, File aTargetDirectory, String aPrefix)
    Creates a temporary copy of the specified existing repository for running tests with workflow API disabled.

    This method is equivalent to:

    > `TestHelper.getRepositoryCopyOfExistingH2StandaloneDB(aSourceDirectory, aTargetDirectory, aPrefix, false);`

    Since:
      5.3.0

  - ### getRepositoryCopyOfExistingH2StandaloneDB

    public static Repository getRepositoryCopyOfExistingH2StandaloneDB(File aSourceDirectory, File aTargetDirectory, String aPrefix, boolean isWorkflowEnabled)
    Creates a temporary copy of the specified existing repository for running tests.
    Parameters:
      `aSourceDirectory` - location of the existing H2 database.
      `aTargetDirectory` - location to copy the existing H2 database. Tests will run on this database.
      `aPrefix` - prefix used in the provided source H2 database. Can be `null`.
      `isWorkflowEnabled` - must be `true` to enable the workflow API. If `false` workflow will be disabled and repository initialization will be faster.
    Returns:
      a repository using a copy of the specified database.
    Since:
      5.7.0 fix A
    See Also:
      - `shutdownRepository(Repository)`

  - ### shutdownRepository

    public static void shutdownRepository(Repository aRepository)
    Shuts down the repository, and checks that all connections to the database have been closed.

    This method is equivalent to:

    > `TestHelper.shutdownRepository(true, aRepository);`

    See Also:
      - `shutdownRepository(boolean, Repository)`

  - ### shutdownRepository

    public static void shutdownRepository(boolean checkConnectionsHaveBeenClosed, Repository aRepository)
    Shuts down the specified repository.

    This method must be called for any test repository obtained using this class (one of the methods `getNewRepository(File)`, `getRepositoryCopyOfExistingH2StandaloneDB(File, File, String)`, or `getRepositoryExistingH2StandaloneDB(File, String)`).

    Parameters:
      `checkConnectionsHaveBeenClosed` - if `true`, verifies that all connections have been properly closed; if not, an exception is thrown.
      `aRepository` - the test repository to be shut down.
    Throws:
      `IllegalStateException` - if `checkConnectionsHaveBeenClosed` is set to `true` and connections to the database have not been closed properly.
    Since:
      5.3.1
    See Also:
      - `RequestResult.close()`