Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/openliberty/guide-arquillian-managed

A guide on how to develop tests for your microservices with the Arquillian managed container and run the tests on Open Liberty: https://openliberty.io/guides/arquillian-managed.html
https://github.com/openliberty/guide-arquillian-managed

Last synced: 3 months ago
JSON representation

A guide on how to develop tests for your microservices with the Arquillian managed container and run the tests on Open Liberty: https://openliberty.io/guides/arquillian-managed.html

Host: GitHub
URL: https://github.com/openliberty/guide-arquillian-managed
Owner: OpenLiberty
License: other
Created: 2018-04-16T15:16:12.000Z (almost 7 years ago)
Default Branch: prod
Last Pushed: 2024-11-04T19:37:33.000Z (3 months ago)
Last Synced: 2024-11-04T20:32:09.033Z (3 months ago)
Language: Java
Homepage:
Size: 450 KB
Stars: 5
Watchers: 9
Forks: 8
Open Issues: 3
Metadata Files:
- Readme: README.adoc
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

// Copyright (c) 2019, 2024 IBM Corporation and others.
// Licensed under Creative Commons Attribution-NoDerivatives
// 4.0 International (CC BY-ND 4.0)
// https://creativecommons.org/licenses/by-nd/4.0/
//
// Contributors:
// IBM Corporation
//
:page-layout: guide-multipane
:projectid: arquillian-managed
:page-duration: 15 minutes
:page-releasedate: 2019-03-08
:page-majorupdateddate: 2023-11-15
:page-guide-category: none
:page-description: Learn how to test your microservices with the Arquillian managed container and JUnit on Open Liberty.
:guide-author: Open Liberty
:page-tags: ['maven']
:page-related-guides: ['cdi-intro','rest-intro']
:page-permalink: /guides/{projectid}
:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod
:page-seo-title: Testing microservices with Arquillian managed container
:page-seo-description: A tutorial on how to test your microservices with the Arquillian managed container for Open Liberty
= Testing microservices with the Arquillian managed container

[.hidden]
NOTE: This repository contains the guide documentation source. To view the guide in published form, view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website].

Learn how to develop tests for your microservices with the Arquillian managed container and run the tests on Open Liberty.

== What you'll learn

You will learn how to develop tests for your microservices by using the https://github.com/OpenLiberty/liberty-arquillian/tree/master/liberty-managed[Arquillian Liberty Managed container^] and JUnit with Maven on Open Liberty. http://arquillian.org/[Arquillian^] is a testing framework to develop automated functional, integration and acceptance tests for your Java applications. Arquillian sets up the test environment and handles the application server lifecycle for you so you can focus on writing tests.

You will develop Arquillian tests that use JUnit as the runner and build your tests with Maven using the Liberty Maven plug-in. This technique simplifies the process of managing Arquillian dependencies and the setup of your Arquillian managed container.

You will work with an `inventory` microservice, which stores information about various systems. The `inventory` service communicates with the `system` service on a particular host to retrieve its system properties and store them. You will develop functional and integration tests for the microservices. You will also learn about the Maven and Liberty configurations so that you can run your tests on Open Liberty with the Arquillian Liberty Managed container.

// Getting Started
[role="command"]
include::{common-includes}/gitclone.adoc[]

=== Try what you'll build

Run the following commands to navigate to the `finish` directory and run the tests:

[role="command"]
----
cd finish
mvn clean package
mvn liberty:create liberty:install-feature
mvn liberty:configure-arquillian
mvn failsafe:integration-test
----

Look for the following output:

== Developing Arquillian tests

Navigate to the `start` directory to begin.
// cloud hosted instructions
ifdef::cloud-hosted[]
```bash
cd /home/project/guide-arquillian-managed/start
```
endif::[]

You'll develop tests that use Arquillian and JUnit to verify the `inventory` microservice as an endpoint and the functions of the `InventoryResource` class. The code for the microservices is in the `src/main/java/io/openliberty/guides` directory.

[role='command']
include::{common-includes}/devmode-lmp33-start.adoc[]

[role="code_command", subs="quotes"]
----
#Create the `InventoryArquillianIT` test class.#
`src/test/java/it/io/openliberty/guides/inventory/InventoryArquillianIT.java`
----

InventoryArquillianIT.java
[source, Java, linenums, indent=0, role='code_column hide_tags=copyright']
----
include::finish/src/test/java/it/io/openliberty/guides/inventory/InventoryArquillianIT.java[]
----

Notice that the JUnit Arquillian runner runs the tests instead of the standard JUnit runner. The [hotspot=RunWith file=0]`@RunWith` annotation preceding the class tells JUnit to run the tests by using Arquillian.

The method annotated by [hotspot=Deployment file=0]`@Deployment` defines the content of the web archive, which is going to be deployed onto the Open Liberty. The tests are either run on or against the Liberty instance. The [hotspot=Testable file=0]`testable = true` attribute enables the deployment to run the tests "in container", that is the tests are run on the Liberty instance.

pom.xml
[source, xml, linenums, indent=0, role='code_column']
----
include::finish/pom.xml[]
----

The [hotspot=warName hotspot=WebArchive file=0]`WARNAME` variable is used to name the web archive and is defined in the [hotspot=ArquillianWarName file=1]`pom.xml` file. This name is necessary if you don't want a randomly generated web archive name.

The ShrinkWrap API is used to create the web archive. All of the packages in the `inventory` service must be added to the web archive; otherwise, the code compiles successfully but fails at runtime when the injection of the `InventoryResource` class takes place. You can learn about the ShrinkWrap archive configuration in this http://arquillian.org/guides/shrinkwrap_introduction/[Arquillian guide^].

The [hotspot=ArquillianResource file=0]`@ArquillianResource` annotation is used to retrieve the `\http://localhost:9080/arquillian-managed/` base URL for this web service. The annotation provides the host name, port number and web archive information for this service, so you don't need to hardcode these values in the test case. The `arquillian-managed` path in the URL comes from the WAR name you specified when you created the web archive in the [hotspot=Deployment file=0]`@Deployment` annotated method. It's needed when the `inventory` service communicates with the `system` service to get the system properties.

The [hotspot=testInventoryEndpoints file=0]`testInventoryEndpoints` method is an integration test to test the `inventory` service endpoints. The [hotspot=RunAsClient file=0]`@RunAsClient` annotation added in this test case indicates that this test case is to be run on the client side. By running the tests on the client side, the tests are run against the managed container. The endpoint test case first calls the `\http://localhost:9080/{WARNAME}/inventory/systems/{hostname}` endpoint with the `localhost` host name to add its system properties to the inventory. The test verifies that the system property for the local and service JVM match. Then, the test method calls the `\http://localhost:9080/{WARNAME}/inventory/systems` endpoint. The test checks that the inventory has one host and that the host is `localhost`. The test also verifies that the system property stored in the inventory for the local and service JVM match.

Contexts and Dependency Injection (CDI) is used to inject an instance of the [hotspot=InventoryResource file=0]`InventoryResource` class into this test class. You can learn more about CDI in the https://openliberty.io/guides/cdi-intro.html[Injecting dependencies into microservices^] guide.

The injected [hotspot=InventoryResource file=0]`InventoryResource` instance is then tested by the [hotspot=testInventoryResourceFunctions file=0]`testInventoryResourceFunctions` method. This test case calls the [hotspot=listContents file=0]`listContents()` method to get all systems that are stored in this inventory and verifies that `localhost` is the only system being found. Notice the functional test case doesn't store any system in the inventory, the `localhost` system is from the endpoint test case that ran before this test case. The [hotspot=InSequence1 hotspot=InSequence2 file=0]`@InSequence` Arquillian annotation guarantees the test sequence. The sequence is important for the two tests, as the results in the first test impact the second one.

The test cases are ready to run. You will configure the Maven build and the Liberty configuration to run them.

== Configuring Arquillian with Liberty

Configure your build to use the Arquillian Liberty Managed container and set up your Open Liberty to run your test cases by configuring the `server.xml` file.

=== Configuring your test build

First, configure your test build with Maven. All of the Maven configuration takes place in the [hotspot]`pom.xml` file, which is provided for you.

pom.xml
[source, xml, linenums, indent=0, role='code_column']
----
include::finish/pom.xml[]
----

ifdef::cloud-hosted[]
> From the menu of the IDE, select **File** > **Open** > guide-arquillian-managed/start/pom.xml, or click the following button

::openFile{path="/home/project/guide-arquillian-managed/start/pom.xml"}
endif::[]

Let's look into each of the required elements for this configuration.

You need the [hotspot=arquillian-bom]`arquillian-bom` Bill of Materials. It's a Maven artifact that defines the versions of Arquillian dependencies to make dependency management easier.

The [hotspot=arquillian-liberty-managed-junit]`arquillian-liberty-managed-junit` dependency bundle, which includes all the core dependencies, is required to run the Arquillian tests on a managed Liberty container that uses JUnit. You can learn more about the https://github.com/OpenLiberty/arquillian-liberty-dependencies[Arquillian Liberty dependency bundles^].

The [hotspot=maven-failsafe-plugin]`maven-failsafe-plugin` artifact runs your Arquillian integration tests by using JUnit.

Lastly, specify the [hotspot=liberty-maven-plugin]`liberty-maven-plugin` configuration that defines your Open Liberty runtime configuration. When the application runs in an Arquillian Liberty managed container, the name of the `.war` file is used as the context root of the application. You can pass context root information to the application and customize the container by using the [hotspot=arquillianProperties]`arquillianProperties` configuration. To allow connections to Liberty running in dev mode, set [hotspot=allowConnectingToRunningServer]`allowConnectingToRunningServer` to `true`.

To learn more about the `arquillianProperties` configuration, see the https://github.com/OpenLiberty/liberty-arquillian/blob/main/liberty-managed/README.md#configuration[Arquillian Liberty Managed documentation^].

=== Configuring Liberty's `server.xml` configuration file

Now that you're done configuring your Maven build, set up your Open Liberty to run your test cases by configuring the [hotspot]`server.xml` configuration file.

Take a look at the [hotspot]`server.xml` file.

server.xml
[source, xml, linenums, indent=0, role='code_column']
----
include::finish/src/main/liberty/config/server.xml[]
----

ifdef::cloud-hosted[]
> From the menu of the IDE, select **File** > **Open** > guide-arquillian-managed/start/src/main/liberty/config/server.xml, or click the following button

::openFile{path="/home/project/guide-arquillian-managed/start/src/main/liberty/config/server.xml"}
endif::[]

The [hotspot=localConnector]`localConnector` feature is required by the Arquillian Liberty Managed container to connect to and communicate with the Open Liberty runtime. The [hotspot=Servlet]`servlet` feature is required during the deployment of the Arquillian tests in which servlets are created to perform the in-container testing.

Open another command-line session and run the `configure-arquillian` goal from the `start` directory to integrate Arquillian and the Arquillian Liberty managed and remote containers with your existing project.

ifndef::cloud-hosted[]
[role="command"]
```
mvn liberty:configure-arquillian
```
endif::[]

ifdef::cloud-hosted[]
```bash
cd /home/project/guide-arquillian-managed/start
mvn liberty:configure-arquillian
```
endif::[]

Because you started Open Liberty in dev mode, all the changes were automatically picked up. You can run the tests by pressing the `enter/return` key from the command-line session where you started dev mode. Look for the following output:

== Running the tests

It's now time to build and run your Arquillian tests outside of dev mode. Exit dev mode by pressing `CTRL+C` in the command-line session where you ran Liberty in the previous section.

Run the Maven command to package the application. Then, run the Liberty Maven Plugin goals to create the Liberty instance, install the features, and deploy the application to the instance. The `configure-arquillian` goal configures your Arquillian container. You can learn more about this goal in the https://github.com/OpenLiberty/ci.maven/blob/main/docs/configure-arquillian.md[configure-arquillian goal documentation^].

ifndef::cloud-hosted[]
[role="command"]
```
mvn clean package
mvn liberty:create liberty:install-feature
mvn liberty:configure-arquillian
```
endif::[]
// cloud hosted instructions
ifdef::cloud-hosted[]
```bash
cd /home/project/guide-arquillian-managed/start
mvn clean package
mvn liberty:create liberty:install-feature
mvn liberty:configure-arquillian
```
endif::[]

Now, you can run your Arquillian tests with the Maven `integration-test` goal:

[role="command"]
```
mvn failsafe:integration-test
```

In the test output, you can see that the Liberty instance launched, and that the web archive, `arquillian-managed`, started as an application in the instance. You can also see that the tests are running and that the results are reported.

After the tests stop running, the test application is automatically undeployed and the instance shuts down. You should then get a message indicating that the build and tests are successful.

[source, role="no_copy"]
----
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running it.io.openliberty.guides.system.SystemArquillianIT
...
[AUDIT ] CWWKE0001I: The server defaultServer has been launched.
[AUDIT ] CWWKG0093A: Processing configuration drop-ins resource: guide-arquillian-managed/finish/target/liberty/wlp/usr/servers/defaultServer/configDropins/overrides/liberty-plugin-variable-config.xml
[INFO ] CWWKE0002I: The kernel started after 0.854 seconds
[INFO ] CWWKF0007I: Feature update started.
[AUDIT ] CWWKZ0058I: Monitoring dropins for applications.
[INFO ] Aries Blueprint packages not available. So namespaces will not be registered
[INFO ] CWWKZ0018I: Starting application guide-arquillian-managed.
...
[INFO ] SRVE0169I: Loading Web Module: guide-arquillian-managed.
[INFO ] SRVE0250I: Web Module guide-arquillian-managed has been bound to default_host.
[AUDIT ] CWWKT0016I: Web application available (default_host): http://localhost:9080/
[INFO ] SESN0176I: A new session context will be created for application key default_host/
[INFO ] SESN0172I: The session manager is using the Java default SecureRandom implementation for session ID generation.
[AUDIT ] CWWKZ0001I: Application guide-arquillian-managed started in 1.126 seconds.
[INFO ] CWWKO0219I: TCP Channel defaultHttpEndpoint has been started and is now listening for requests on host localhost (IPv4: 127.0.0.1) port 9080.
[AUDIT ] CWWKF0012I: The server installed the following features: [cdi-2.0, jaxrs-2.1, jaxrsClient-2.1, jndi-1.0, jsonp-1.1, localConnector-1.0, mpConfig-1.3, servlet-4.0].
[INFO ] CWWKF0008I: Feature update completed in 2.321 seconds.
[AUDIT ] CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 3.175 seconds.
[INFO ] CWWKZ0018I: Starting application arquillian-managed.
...
[INFO ] SRVE0169I: Loading Web Module: arquillian-managed.
[INFO ] SRVE0250I: Web Module arquillian-managed has been bound to default_host.
[AUDIT ] CWWKT0016I: Web application available (default_host): http://localhost:9080/arquillian-managed/
...
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 6.133 s - in it.io.openliberty.guides.system.SystemArquillianIT
[INFO] Running it.io.openliberty.guides.inventory.InventoryArquillianIT
[INFO ] CWWKZ0018I: Starting application arquillian-managed.
[INFO ] CWWKZ0136I: The arquillian-managed application is using the archive file at the guide-arquillian-managed/finish/target/liberty/wlp/usr/servers/defaultServer/dropins/arquillian-managed.war location.
[INFO ] SRVE0169I: Loading Web Module: arquillian-managed.
[INFO ] SRVE0250I: Web Module arquillian-managed has been bound to default_host.
...
[INFO ] Setting the server's publish address to be /inventory/
[INFO ] SRVE0242I: [arquillian-managed] [/arquillian-managed] [io.openliberty.guides.inventory.InventoryApplication]: Initialization successful.
[INFO ] Setting the server's publish address to be /system/
[INFO ] SRVE0242I: [arquillian-managed] [/arquillian-managed] [io.openliberty.guides.system.SystemApplication]: Initialization successful.
[INFO ] SRVE0242I: [arquillian-managed] [/arquillian-managed] [ArquillianServletRunner]: Initialization successful.
[AUDIT ] CWWKT0017I: Web application removed (default_host): http://localhost:9080/arquillian-managed/
[INFO ] SRVE0253I: [arquillian-managed] [/arquillian-managed] [ArquillianServletRunner]: Destroy successful.
[INFO ] SRVE0253I: [arquillian-managed] [/arquillian-managed] [io.openliberty.guides.inventory.InventoryApplication]: Destroy successful.
[AUDIT ] CWWKZ0009I: The application arquillian-managed has stopped successfully.
[INFO ] SRVE9103I: A configuration file for a web server plugin was automatically generated for this server at guide-arquillian-managed/finish/target/liberty/wlp/usr/servers/defaultServer/logs/state/plugin-cfg.xml.
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.297 s - in it.io.openliberty.guides.inventory.InventoryArquillianIT
...
Stopping server defaultServer.
...
Server defaultServer stopped.
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12.018 s
[INFO] Finished at: 2020-06-23T12:40:32-04:00
[INFO] ------------------------------------------------------------------------
----

== Great work! You're done!

You just built some functional and integration tests with the Arquillian managed container and ran the tests for your microservices on Open Liberty.

Try one of the related guides to learn more about the technologies that you come across in this guide.

include::{common-includes}/attribution.adoc[subs="attributes"]