----------------
            Testing LibreCCM
            ----------------
             Jens Pelzetter
            ----------------
              2015-06-29
            ----------------

Testing LibreCCM

    For testing the LibreCCM uses JUnit 4 and Arquillian. Arquillian is a 
    testing platform developed by JBoss/RedHat for testing Java EE applications
    <<inside>> an Application Server. Arquillian integrates with JUnit using
    a <<<TestRunner>>>. 

    This page only describes the special aspects of testing LibreCCM. For an
    introduction to Arquillian please refer to the webpage and documentation
    of Arquillian.

* Controlling which tests to are executed

    All tests are annotated with a category using the category feature from
    JUnit. Test which are annotated with

--------------------------------------------------------------------------------
@Category(UnitTest.class)
--------------------------------------------------------------------------------

    are executed in every case. Tests which are annotated with 

--------------------------------------------------------------------------------
@Category(IntegrationTest.class)
--------------------------------------------------------------------------------

    are only executed when special Maven profiles are used. These profiles are
    used to control which Application server Arquillan should use to run the  
    integration tests. 

* Available profiles

    At the moment the following profiles are provided:

    [wildfly8-remote-h2-mem] Uses a remote Wildfly 8 application server and
    a in memory H2 database

    [wildfly8-remote-pgsql] Uses a remote Wildfly 8 application server and
    a PostgreSQL database.

    Please note that the profiles must be defined separately in each module.
    Therefore maybe not all modules will provide all modules (but they should).

* Planned profiles

    The following profiles are planned to be added:

    [wildfly8-remote-oracle] Will use a remote Wildfly 8 server and a Oracle 
    database.
    
    [tomee17-remote-pgsql] Will use a remote TomEE application server and a 
    PostgreSQL database.

* Structure of the profiles

    For each profile their is separate resource directory in the 
    <<<src/test>>> directory of the module which at least 
    contains these files: 
    
    [arquillian.xml] Configuration file for Arquillian.

    [test-persistence.xml] JPA configuration file. Will be renamed to 
    <<<persistence.xml>>> and placed into the test archive by the deploy method
    of the test. On important difference to the production <<<persistence.xml>>>
    is that the <<<test-persistence.xml>>> configures Hibernate to automatically
    drop the database and recreate the schema. The production 
    <<<persistence.xml>>> is configured to only verify the schema. Schema
    creation and migrations are done by LibreCCM using the Flyway framework.

* Preparing the remote Application Servers

** Wildfly 8.2.x

    For using the remote profiles you have to install a 
    {{{http://wildfly.org/}Wildfly application server}}
    on the system you want to run the tests on. At them moment we recommend to 
    use version 8.2.1. The installation is 
    described in the {{{https://docs.jboss.org/author/display/WFLY8/Getting+Started+Guide}Wildfly documentation}}.

    If you want to use the <<<wildfly8-remote-h2-mem>>> profile you have to 
    create a new datasource in Wildfly. The easiest way to do that is the use
    Admin UI of Wildfly. Open the Admin UI in your browser, go the 
    <<<Configuration>>>, <<<Connector>>>, <<<Datasource>>> and create a new 
    datasource with these properties:
    
    [JNDI name] <<<java:/comp/env/jdbc/org/libreccm/ccm-core/h2-mem>>>

    [Name] <<<ccm-core-h2-mem-testdb>>>

    [Connection URL] <<<jdbc:h2:mem:ccc-testdb>>>

    [Username] <<<sa>>>

    [Password] can be empty

    This uses the the H2 database engine which bundled with Wildfly. The 
    database is an in memory database which exists only in the RAM.

    If you want to use the <<<wildfly8-remote-pgsql>>> some more steps are 
    necessary. First you need a working PostgreSQL installation. We recommend
    version 9.4. Create a new database user <<<ccm>>> with a password and a new
    database <<<ccm-testdb>>> which is owned by the user you just created.

    Download the {{{https://jdbc.postgresql.org/}JDBC driver for PostgreSQL}}. 
    Open the Admin UI of your Wildfly installation and and to <<<Deployments>>>.
    Click the <<<Add>> button and select the file of the PostgreSQL JDBC driver.
    Click next and check the <<<Enable>>> checkbox of the next page, then click 
    <<<Save>>>. You should now see the deployed driver in the list of 
    deployments.

    Then go to <<<Configuration>>>, <<<Connector>>>, <<<Datasource>>> and create a new 
    datasource with these properties:
    
    [JNDI name] <<<java:/comp/env/jdbc/org/libreccm/ccm-core/pgsql>>>

    [Name] <<<ccm-core-pgsql-testdb>>>

    [Connection URL] <<<jdbc:postgresql://your-pgsql-server/ccm-testdb>>>

    [Username] <<<ccm>>>

    [Password] <<<your-password>>>

    Please note that the database is recreated after each test. Therefore
    you should not use a production database.