- Overview of the project
- Setup
- Running Your project
- Testing Your Project
- Checking your code coverage
- Live updates for Gradle test or run
- Continuous Integration with GitHub Actions
- Go do the lab!
- Resources
Here you will explore serving up a simple website that you create, using a server written with the Javalin framework server. Javalin is a micro framework for creating web applications in Java which you will be using to create the server component (back-end) of your website.
The client component (front-end) of your website will use JavaScript to allow you to accept and process user input. We will use JUnit to test the server code and introduce continuous integration using GitHub Actions.
Your specific tasks for this lab can be found in the LABTASKS.md file in this repository.
You'll be building parts of a simple to-do list using a
client-server architecture. The server will be able to handle
simple HTTP GET requests, where a client (or a user) can
visit a URL such as http://localhost:4567/api/users and the server
will respond with JSON-formatted text containing
all the users the server knows about, e.g.,
[
{
"_id":"588935f57546a2daea44de7c",
"name":"Connie Stewart",
"age":25,
"company":"OHMNET",
"email":"[email protected]"
},
{
"_id":"588935f5597715f06f3e8f6c",
"name":"Lynn Ferguson",
"age":25,
"company":"NIQUENT",
"email":"[email protected]"
},
{
"_id":"588935f51c55b55c75a84848",
"name":"Roseann Roberson",
"age":23,
"company":"OHMNET",
"email":"[email protected]"
},
...
]The client will be a combination of HTML, CSS, and JavaScript that runs in the browser and converts user actions (such as clicking a button) into requests to the server. In a "real" system you'd want to display the results nicely as part of the application web interface (like the nicely formatted list of e-mails in GMail). To keep this lab simple, however, you'll just display the "raw" JSON that the client receives from the server.
This goal of this lab is to implement the desired server functionality. The details are in LABTASKS.md.
- First, Open GitKraken. If you already have a project open, close it or open a new tab.
- Click "Clone a repo", select "GitHub.com" and find this repo in "Repository to Clone"
- Select where to put it and clone it
- You can then click "Open Repo" from the notification that appears to open the repo
Launch Visual Studio Code, and then choose File -> Open Folder…. Navigate to your clone
of the repo and choose Open.
You may see a dialog that looks like this if you don't already have the recommended extensions:
Don't worry if you don't get the dialog, it is probably because you already have them all installed.
Like in previous labs, click "Install All" to automatically install them.
If you use Chrome, you may find it helpful to install the JSONVue extension. This will make JSON in the browser look pretty and actually be readable when you visit the different API endpoints.
If you use Firefox, this functionality is built-in, so there is no need to install an extension.
We use the Gradle build tool to build and run our web application. Gradle is a powerful system for defining, managing, and running tasks that allows us to easily build and test our full web application.
We will be using Gradle from the terminal. You can do this either with the terminal app or the terminal built into VS Code.
From the project directory, you will need to change into the server directory with
cd serverFrom the server directory you can use Gradle to run the server:
./gradlew runYour server should now be running on port 4567, the port we've configured Javalin to run on. Visit it at http://localhost:4567 in your web browser.
The server will continue to run indefinitely until you stop it. You can
stop it by typing Control-C (often written ^C) in the terminal where
it's running.
There's very little meaningful logic in the client component of this project so we're not going to worry about testing the client here. We'll begin testing the client when we introduce Angular in subsequent labs.
The server-side portion of this project will be tested using JUnit.
Server-side tests are located in the src/test/java directory.
To run your server-side tests: while in the server directory, run:
./gradlew testThis will run all tests and output info about the run to a test report "website". To see the report open the file in your browser:
server/build/reports/tests/test/index.html
It will look something like this:
These test reports are especially helpful when a test fails because you will get the full stack trace there.
When a test fails, you will get a notice in the terminal that there were failing tests along with a path to the report. You can copy that path into your browser to see the report.
We have the JaCoCo (Java Code Coverage) plugin set up in Gradle so you can see how well your tests cover (i.e., exercise) your code. The command
./gradlew checkwill run the tests followed by the test coverage report generator. This report is a "website" like the one from JUnit above. To see the report open the file in your browser:
server/build/jacocoHtml/index.html
It will look something like this:
If you generate and look at that report at the start of the lab, you'll see that you start
with 100% coverage of all the user files.
You'd like to keep it that way, so check your
code coverage after major stories are finished and look for areas that you're not yet testing. You also want to maintain high test coverage
as you introduce your todo code.
./gradlew check will fail (and thus block your ability to
merge in a pull request)) if your test coverage ever falls below 80%,
so keep an eye on it and take action if it starts to slide down.
📌 The Main.java and Server.java files are excluded from
the test coverage. They're hard to test without actually generating
HTTP requests, and are mostly configuration rather than "logic", so
we've chosen to not over-complicate the project with attempts to test
that code. You are not obliged to provide any coverage for that. You
should make sure your tests cover things like your ToDoController and the like, though.
By default, if you're running the server with ./gradlew run and make changes
to your Java code, you have to stop the server (with ^C) and restart it for
those changes to take effect. Similarly, if you make changes and want to
see if ./gradle test or ./gradle check passes, then you have re-run those
commands by typing them in again.
Happily, Gradle gives us the --continuous (or -t for short) flag to simplify
these use cases. If, for example, you enter ./gradlew --continuous run, then
Gradle will automagically notice when relevant files have changed, recompile, and
re-run the project. Similarly, you can have ./gradlew --continuous check running
in a terminal and it will automatically re-run the checks whenever you save changes.
GitHub Actions is a Continuous Integration tool that performs builds of your project every time you push to GitHub. This is very helpful, as it makes keeping track of your testing over the lifetime of a project very easy. Having a build/test history makes it easy to find where, or when, your project broke, which makes it a lot easier to figure out why it broke and get it fixed and building successfully again.
GitHub Actions is built into GitHub and free to use on open source projects (like ours).
We've done the hard part of setting up the config files for GitHub Actions so it will work automatically. You can find the tests in the "Actions" tab of the GitHub repo.
Now that you're all set up, you should be ready to head over to LABTASKS.md, where most of the actual work of the lab is described.