From 94c850bcc8f47b6fbe0b3057ed8167a83083ff8d Mon Sep 17 00:00:00 2001 From: Jens Pelzetter Date: Sat, 18 Jul 2020 19:12:05 +0200 Subject: [PATCH] Adjusted README.md to new test structure and added instructions for running a bundle using the wildfly-maven-plugin --- README.md | 106 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 68 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index d470d98c9..b414d0220 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ # LibreCCM -The [https://libreccm.org](LibreCCM) framework and the -[https://librecms.org](LibreCMS) web content management system. +The [https://libreccm.org](LibreCCM) framework and the +[https://librecms.org](LibreCMS) web content management system. -This repository contains the Jakarta EE based, new version of LibreCCM -and LibreCMS. We are now using Maven as build tool. +## Overview + +This repository contains the Jakarta EE based, new version of +[https://libreccm.org](LibreCCM) and [https://librecms.org](LibreCMS). We are +now using Maven as build tool. Some more documentation is provided as Maven project site. To create the site run @@ -15,46 +18,82 @@ and open the ./target/staging/index.html file in your browser. The recreate the site run - mvn clean package site site:stage + mvn package site site:stage again. -To include integration tests into the reports +Note: The ./target/staging folder is left intact when cleaning. If you +want to remove the folder you have delete it manually. - mvn clean package test site site:stage -P$profile-name +To include integration tests into the reports run -Note: If there are test failures the package goal fails and the site is not + mvn clean verifiy site site:stage -P${profileName} + +Note: If there are test failures the build fails and the site is not build. The build the site anywhy use mvn clean package site site:stage -Dmaven.test.failure.ignore=true -or with a profile +or with the integration tests included - mvn clean package site site:stage -Dmaven.test.failure.ignore=true -Pwildfly-remote-h2-mem + mvn clean verify site site:stage -Dmaven.test.failure.ignore=true -P${profileName} -The available profiles are listed in the documentation. All modules should -provide a profile called wildfly-remote-h2-mem. This profile uses a remote -Wildfly application server and its integrated H2 in-memory database for -running the tests. Before you can run the integration tests you must download -Wildfly from http://www.wildfly.org. Unzip the downloaded archive and start -the server using the bin/standalone.sh file. Then go to another terminal, -navigate to the CCM NG directory and run +## Running integration tests - mvn clean package test site site:stage -Pwildfly-remote-h2-mem +Some of the modules provide integration tests which use +[Arquillian](http://arquillian.org/) to run tests inside an application server. +If a module provides integration tests it should have at least four profiles +for running them (at the time of writing): + +* `run-its-with-wildfly-h2mem`: This profile uses the + [wildfly-maven-plugin](https://docs.jboss.org/wildfly/plugins/maven/latest/) + to start a Wildfly and run the integration tests. The H2 database which is + integrated with Wildfly is used for run the tests. No configuration + is necessary. +* `run-its-with-wildfly-pgsql`: This profile uses the + [wildfly-maven-plugin](https://docs.jboss.org/wildfly/plugins/maven/latest/) + to start a Wildfly and run the integration tests. A PostgreSQL database is + used to run the tests. The connection parameters are configured using + the `it-pgsql-datasources.properties` file in the project root. Make sure + to create a database for all modules and configure them before using + this profile. +* `run-its-in-remote-wildfly-h2mem`: This profile uses a remote Wildfly and + the H2 database for + running the tests. The user it responsible for starting the Wildfly container + and for creating the required databases. +* `run-its-in-remote-wildfly-pgsql`: This profile uses a remote Wildfly and + PostgreSQL databases for + running the tests. The user it responsible for starting the Wildfly container + and for creating the required databases. + +To run the integration tests select a profile - we recommend to use the profiles +which use the wildfly-maven-plugin` to manage to Wildfly application server - +and run + + mvn verify site site:stage -P${profileName} + +## Running LibreCCM (development environment) + +Before running a bundle the WAR file has the be generated using + + mvn package To run LibreCCM choose the bundle to run, for instance -ccm-bundle-devel-wildfly. Depending on the bundle and the selected profile -you may have to configure a datasource in the Wildfly server and create a -database. Also you need to configure an environement variable which points to -your Wildfly installation. Then you can run LibreCCM using +`ccm-bundle-devel-wildfly`. You can run the bundle - mvn package wildfly:run -DskipTests -pl ccm-bundle-devel-wildfly -am -Pgeneric + mvn wildfly:run -pl ${bundleName} -am -The above example skips all tests to speed up the start process. The generic -profile used in this example uses an existing Wildfly installation. The -JBOSS_HOME environment variable must either be configured or must be provided. -Alternativly you can provide the location of your Wildfly installation using -the -D switch: mvn -Djboss-as.home=/path/to/wildfly/ +This will start a Wildfly server running the selected bundle. Before running +the bundle the Wildfly container has the be configured. For these purpose, run + + mvn wildfly:run -pl ${bundleName} -am -Psetup-runtime + +This will start the Wildfly server, deploy the bundle WAR, and create a +datasource. At the moment only PostgreSQL is supported as database. The +datasource configuration is provided by the `datasource.properties` file in the +bundle directory. To create one copy the example file and adjust the settings. + +## Archetypes To install the archetypes in your local Maven repository run @@ -64,15 +103,6 @@ for example mvn clean install -pl ccm-cms-archetypes-contenttype -am -Using the managed profiles (example is for testing): - -mvn clean test -Djboss.home=/path/to/wildfly/ -DstartupTimeoutInSeconds=180 -Pwildfly-managed-h2-mem - -You might need to increase the timeout. - -For convience, we also provide a small Bash script which makes calling some Maven tasks easier. For more information please refer to the help of the ccm.sh script: - - ccm.sh --help - +