|
Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Learn how to build and test a simple web application using Gradle and Open Liberty.
You will learn how to build and test a simple web servlet application using the Gradle war
plug-in and the Liberty Gradle plug-in. The war plug-in compiles and builds the application
code. The liberty Gradle plug-in
installs the Open Liberty runtime, creates an instance, and installs the application to run and test.
The application displays a simple web page with a link. When you click that link, the application
calls the servlet to return a simple response of Hello! Is Gradle working for you?.
One benefit of using a build tool like Gradle is that you can define the details of the project and any dependencies it has, and Gradle automatically downloads and installs the dependencies. Another benefit of using Gradle is that it can run repeatable, automated tests on the application. You can, of course, test your application manually by starting a Liberty instance and pointing a web browser at the application URL. However, automated tests are a much better approach because you can easily rerun the same tests each time the application is built. If the tests don’t pass after you change the application, the build fails, and you know that you introduced a regression that requires a fix to your code.
Choosing a build tool often comes down to personal or organizational preference, but you might choose to use Gradle for several reasons. Gradle defines its builds by using Groovy build scripts, which gives you a lot of control and customization in your builds. Gradle also uses a build cache that rebuilds only the parts of your application that changed, which saves build time in larger projects. So Gradle can be a good choice in larger, more complex projects.
Using this guide, you will create a Gradle build definition file (build.gradle) for the
web application project, and use it to build the application. You will then create a simple,
automated test, and configure Gradle to run it after building the application.
Learn more about Gradle on the official Gradle website.
The web application that you will build using Gradle and Open Liberty is provided for you
in the start directory so that you can focus on learning about Gradle. The application uses
the standard Gradle directory structure. Using this directory structure saves you from
customizing the build.gradle file later.
All the application source code, including the Open Liberty server.xml configuration file,
is in the start/src directory:
└── src
└── main
└── java
└── liberty
└── config
└── webapp
└── WEB-INFIf you do not have Gradle installed, make sure that the JAVA_HOME environment variable is set, or that the Java application can run. Running the Gradle Wrapper automatically installs Gradle. To learn more about the Gradle Wrapper, see the Gradle Wrapper documentation.
Run the following commands to navigate to the start directory and verify that Gradle was installed correctly:
cd start gradlew.bat -v
cd start ./gradlew -v
You should see information about the Gradle installation similar to this example:
------------------------------------------------------------
Gradle 7.6
------------------------------------------------------------
Build time: 2022-11-25 13:35:10 UTC
Revision: daece9dbc5b79370cc8e4fd6fe4b2cd400e150a8
Kotlin: 1.7.10
Groovy: 3.0.13
Ant: Apache Ant(TM) version 1.10.11 compiled on July 10 2021
JVM: 11.0.12 (Eclipse OpenJ9 openj9-0.27.0)
OS: Mac OS X 12.6.3 x86_64settings.gradle
link:finish/settings.gradle[role=include]build.gradle
link:finish/build.gradle[role=include]The project configuration is defined in the Gradle settings and build files. You will create these project configurations one section at a time.
Gradle settings
are used to instantiate and configure the project. This sample uses the settings.gradle
to name the project GradleSample.
Create the Gradle settings file in thestartdirectory.settings.gradle
This settings.gradle file isn’t required for a single-module Gradle project.
Without this definition, by default, the project name is set as the name of the folder in
which it is contained (start for this example).
Let’s go through the build.gradle
file so that you understand each part.
Configuration |
Purpose |
Plug-ins used |
The first part of the build file specifies the plug-ins required to build the project and some basic project configuration. |
buildscript |
Where to find plug-ins for download. |
repositories |
Where to find dependencies for download. |
dependencies |
Java dependencies that are required for compiling, testing, and running the application are included here. |
ext |
Gradle extra properties extension for project level properties. |
test |
Unit test and integration test configuration. |
Create the build file in thestartdirectory.build.gradle
The first section of code defines the war and liberty plug-ins
that you want to use. The war plug-in contains all the tasks to compile
Java files, build the WAR file structure, and assemble the archive. The liberty
plug-in contains the tasks used to install the Liberty runtime and create and manage
the associated Liberty instances. The compatibility and encoding settings are for Java.
The buildscript section defines plug-in versions to use in the
build and where to find them. This guide uses the liberty plug-in,
which is available from the Maven Central Repository.
The repositories section defines where to find the dependencies
that you are using in the build. For this build, everything you need is in Maven Central.
The dependencies section defines what is needed to compile and
test the code. This section also defines how to run the application. The
providedCompile dependencies are APIs that are needed to compile the
application, but they do not need to be packaged with the application because Open Liberty
provides their implementation at run time. The testImplementation dependencies
are needed to compile and run tests.
The Gradle extra properties extension allows you to add properties to a Gradle project.
If you use a value more than once in your build file, you can simplify updates by defining
it as a variable here and referring to the variable later in the build file.
This project defines variables for the application ports and the context-root.
You can view the default and Liberty tasks available by running the following command:
gradlew.bat tasks./gradlew tasksStart Open Liberty in dev mode, which starts the Open Liberty instance and listens for file changes:
./gradlew libertyDev
After you see the following message, your Liberty instance is ready in dev mode.
********************************************** * Liberty is running in dev mode.
The dev mode holds your command prompt to listen for file changes. You need to open another command prompt to continue, or simply open the project in your editor.
Navigate your browser to the http://localhost:9080/GradleSample/servlet URL to access the application.
The servlet returns a simple response of Hello! Is Gradle working for you?.
EndpointIT.java
link:finish/src/test/java/io/openliberty/guides/hello/it/EndpointIT.java[role=include]build.gradle
link:finish/build.gradle[role=include]HelloServlet.java
link:finish/src/main/java/io/openliberty/guides/hello/HelloServlet.java[role=include]One of the benefits of building an application with a build system like Gradle is that
it can be configured to run a set of automated tests. The war
plug-in extends the Java plug-in,
which provides test tasks. You can write tests for the individual units of code outside
of a running Liberty instance (unit tests), or you can write them to call the application
that runs on the Liberty instance (integration tests). In this example, you will create a simple
integration test that checks that the web page opens and that the correct response is
returned when the link is clicked.
Create theEndpointITtest class.src/test/java/io/openliberty/guides/hello/it/EndpointIT.java
The test class name ends in IT to indicate that it contains an integration test.
The integration tests are put in the it folder by convention.
The test section in your build file is added by the Java plug-in, and the
useJUnitPlatform() line configures Gradle to add JUnit 5 support.
The systemProperty configuration defines some variables needed by
the test class. While the port number and context-root information can be
hardcoded in the test class, it is better to specify it in a single place like the Gradle
build.gradle file, in case they need to change.
The systemProperty lines passes these details to the test JVMs
as a series of system properties, resolving the http.port
and context.root variables.
The init() method in the EndpointIT.java test class uses these
system variables to build the URL of the application.
In the test class, after defining how to build the application URL, the @Test
annotation indicates the start of the test method.
In the try block of the test method, an HTTP GET request to the
URL of the application returns a status code. If the response to the request includes the
string Hello! Is Gradle working for you?, the test passes. If that string is not in the
response, the test fails. The HTTP client then disconnects from the application.
In the import statements of this test class, you’ll notice that the
test has some new dependencies. Earlier you added some testImplementation
dependencies. The Apache httpclient and org.junit.jupiter
dependencies are needed to compile and run the integration test EndpointIT
class.
The scope for each of the dependencies is set to testImplementation
because the libraries are needed only during the Gradle test phase and do not need to be
packaged with the application.
Now, the created WAR file contains the web application, and dev mode can run any integration
test classes that it finds. Integration test classes are classes with names that end in IT.
The directory structure of the project in the start folder should now look like this
example:
└── build.gradle
├── settings.gradle
└── src
├── main
│ ├── java
│ ├── liberty
│ │ └── config
│ └── webapp
│ └── WEB_INF
└── test
└── javaWe show a few more Gradle tricks in this example with the openBrowser task.
This task displays your application and the test report in the default browser.
The final Gradle magic to add is the task dependency directives.
The dependency directives organizes task execution.
In this case, the test task is set to run after the Liberty instance is started, and the
openBrowser task is executed after the test task is finalized.
Because you started Open Liberty in dev mode at the start of the guide, press the enter/return
key from the command-line session where you started dev mode to run the tests.
You will see that the browser opened up the test summary page, which ran one successful test.
To see whether the test detects a failure, change the response string in the
src/main/java/io/openliberty/guides/hello/HelloServlet.java file
so that it doesn’t match the string that the test is looking for. Then rerun the Gradle
test to automatically restart and retest your application to check to see if the test fails.
You built and tested a web application project running on an Open Liberty instance using Gradle.