Merge pull request #2 from bbortt/fix/add-sample-to-build

add sample project

pom.xml

@@ -104,6 +104,7 @@
   <modules>
     <module>citrus-remote-server</module>
     <module>citrus-remote-maven-plugin</module>
+    <module>sample</module>
   </modules>
 
   <dependencyManagement>

sample/README.adoc

@@ -0,0 +1,98 @@
+:listing-caption: Listing
+:experimental:
+
+= Citrus Playground
+:toc:
+
+== What it is
+A small sample project, containing a file:///./service:[`service`] module (representing the system under test) and a file:///./citrus:[`citrus`] module, containing the citrus tests for the service.
+
+== Prerequisite
+
+The project uses Java 17, so a Java 17 JDK should be installed.
+
+The services are deployed with `docker compose`, hence a working docker setup is recommended. For the deploymeht via `docker compose` we need internet connection to load the base image used.
+
+When deployed,
+
+* the `service` is exposed under `http://localhost:8080`, and has opened debug port `5006` (also forwarded to `localhost`)
+* `citrus` is exposed under `http://localhost:4567`, and has opened debug port `5007` (again, also forwarded to `localhost`).
+
+Citrus tests are not started automatically, but must be triggered explicitly.
+
+The citrus tests are written with https://testng.org/doc/:[testng].
+
+== Building and deploying the project via `docker-compose`
+From the project root, build the project with the profile `build-test-jar` active:
+
+.Build the project
+[source,bash]
+----
+$ mvnw -Pbuild-test-jar package
+----
+
+When the build is completed, start the compose environment:
+
+.Start docker compose environment
+[source, bash]
+----
+$ cd local-deployment
+$ docker compose up -d
+----
+
+We verify that both services are running:
+
+.Verification that both the `service` and `citrus` are running in docker
+[source,bash]
+----
+$ curl http://localhost:8080/q/health/ready
+{
+    "status": "UP",
+    "checks": [
+    ]
+}%
+$ curl http://localhost:4567/health
+{ "status": "UP" }%
+----
+
+== Triggering the tests
+
+=== From the local machine
+We just need to execute the goal `verify` on module `citrus`:
+
+.Triggering the tests from the local machen
+[source,bash]
+----
+$ ./mvnw -pl citrus verify
+----
+
+=== Through remote execution
+In this scenario, we trigger the citrus container, running in docker, to execute the tests.
+
+==== Via `citrus-maven-remote-plugin`
+We execute the `verify`goal on module `citrus` with profile `trigger-citrus-remote` activated:
+
+.Triggering citrus tests via `citrus-maven-remote-plugin`
+[source,bash]
+----
+$ ./mvnw -Ptrigger-citrus-remote -pl citrus verify
+----
+
+==== Via `cURL`
+We execute the following `curl` command to trigger the tests without the `citrus-maven-remote-plugin`:
+
+.Triggering citrus tests via `cURL`
+[source,bash]
+----
+$ curl -H 'Content-Type: application/json' -d '{ "engine": "testng" }' -X PUT -v http://localhost:4567/run
+----
+
+== Cleanup
+To clean up, we shutdown the docker containers:
+
+.Shutting down the containers
+[source,bash]
+----
+$ cd local-deployment
+$ docker compose down
+----

sample/citrus/.dockerignore

@@ -0,0 +1,2 @@
+target/*.jar
+!target/*-citrus-tests.jar