In this file, we explain how to set up, run, and develop this project. Before reading this, you should read the project description.
In the online version of this file, you can see the current status of the project.
Current pipeline status:
Current code coverage: 
The skeleton leverages various frameworks that simplify and aid software development. In the following, we provide a quick introduction, with a focus on how these frameworks help you complete this project.
We provide instructions exclusively for Linux (in particular, for Ubuntu). We strongly recommend you use Ubuntu to develop and run this project.
The project is set up to use docker - if you are curious, you can find a simple introduction here. Docker essentially simulates a lightweight virtual machine, which allows us to work in a controlled environment that comes with the necessary dependencies for this project. To install docker, you may follow these instructions.
We have prepared a docker image containing all tools needed to run and develop this project. To run this docker image in interactive mode (i.e., in a terminal where you can run any command), run
./run-docker.sh
[...]
root@a515c5af06d6:/project/analysis$ TYPE YOUR COMMAND HERE...In the following, we assume you are inside the docker image, either because you ran the previous command, or because you are developing inside the container (discussed later).
Alternatively, you could manually follow the instructions inside the Dockerfile to install all relevant tools directly on your system. However, this should not be necessary, and we recommend not to do this.
We manage the project's build, reporting and testing using Maven. The most important maven commands are:
# delete automatically generated files
root@a515c5af06d6:/project/analysis$ mvn clean
[...]
# compile, run unit and integration tests, report code coverage
root@a515c5af06d6:/project/analysis$ mvn verify
[...]
# generate test report
root@a515c5af06d6:/project/analysis$ mvn site
[...]Command mvn verify generates information on test coverage
here.
Command mvn site generates a report on test results
here.
- If you get unexpected errors that do not make sense, it often helps to run
mvn cleanand try again.
We have set up maven to run unit tests (detected by filename pattern
*Test.java) and integration tests (detected by filename pattern *IT.java),
which are located in this directory.
The most important maven commands regarding testing are
# run unit tests and create "surefire" report
root@a515c5af06d6:/project/analysis$ mvn test surefire-report:report
# run integration tests and create "failsafe" report
root@a515c5af06d6:/project/analysis$ mvn verify -Dskip.surefire.tests site -Dskip.surefire.testsThe two reports are located in surefire-report.html and failsafe-report.html, respectively.
We use SLF4J as a front-end for logging, and Logback as our logging backend.
While logging is not necessary to solve this project, it is easy to do and can be very helpful. See Runner.java for an simple usage example of logging in action.
Feel free to adapt the logging configuration if needed. For example, you can reduce the console logging information by adapting the "Log level for console".
We have set up the project to build and test the project on every push to the code repository, as controlled by .gitlab-ci.yml and .gitlab-ci-custom.yml. When the tests fail, you will be notified by e-mail (depending on your GitLab notification settings).
We recommend that you start to develop new functionality by writing corresponding tests, i.e., that you adhere to test-driven development.
ERROR: Job failed (system failure): Likely, running the job again will resolve this issue. To this end, in GitLab, navigate to CI/CD -> Jobs -> Click on the box "Failed" of the failed job -> Click "Retry" (top right)
We use JaCoCo to record and report the code
coverage achieved by all tests. When running mvn verify, the code coverage is
reported
here
(column "Missed Instructions Cov", row "Total"). As
discussed in the project description, we will award additional points for a
instruction coverage of >=75%.
IMPORTANT NOTE: To ensure we will be able to run your submission, follow these rules:
- Some files in this repository come with a note to
NOT MODIFY THIS FILE. We will overwrite these files for grading, so changing them may mean that we cannot compile your project. - Before submission, check that the GitLab CI/CD runs without errors by checking the pipeline status (see above). In particular, please make sure that you do not commit failing tests as you will not get any additional points for code coverage if some of your tests fail. We will use the same workflow as the GitLab CI/CD to test your submission.
To develop, debug, and run this project, we suggest using Visual Studio Code to develop inside a docker container. This allows you to work on this project without having to install its dependencies on your host system.
To this end, follow these installation instructions. Instead of "adding your user to the docker group" (which opens up a potential security hole), you may instead install docker in rootless mode.
Then, install the Java Extension Pack in Visual Studio code:
- Open Visual Studio Code
- Launch VS Code Quick Open (Ctrl+P)
- Paste the following command, and press enter:
ext install vscjava.vscode-java-pack - Launch VS Code Quick Open again (Ctrl+P)
- Paste the following command, and press enter:
ext install ms-vscode-remote.remote-containers
To open the project in Visual Studio Code:
- Open Visual Studio Code
- Press F1, type "Dev Containers: Open folder in Container"
- Navigate to directory analysis, and "Open" it
- Wait a few minutes for everything to load
To run all unit tests:
- Click on tab "Testing" in the left-hand-side panel
- Click "Run Test" in the new panel (or "Debug Test" to debug)
- Wait for the test results to pop up