Backity

Backity is a web service for automatically downloading backups of your games from external clients such as GOG.

For instructions on how to use Backity, consult the Wiki.

⚠️Warning: Backity is not yet production-ready! Anything may break at any time.⚠️

The information below is aimed at developers who want to extend this project's functionality.

---

• Getting Started
• Profiles summary
  • Spring profiles
  • Maven profiles
• API documentation
  • Swagger
  • OpenAPI
• Client code generation
• Working with frontend on a local environment
• Running test suites
  • Backend
  • Frontend
• SonarQube analysis on a local environment
  • Prerequisites
  • Launching SonarQube on a local environment
  • Full analysis
  • Backend analysis
  • Frontend analysis
  • Verifying results
• Mutation testing
• Built With

Getting Started

First, clone this repository.

Then, build it locally with:

mvn clean install

You can run the project with the following command:

mvn spring-boot:run -Dspring-boot.run.profiles=dev

As a result, you should be able to visit the home page on http://localhost:8080/:

Profiles summary

The project can be built with various different profiles to allow for flexible configuration. Below you'll find a short summary of the available profiles.

Spring profiles

• dev - for local development. Allows things like handling requests from http://localhost:4200/.
• angular - special profile used for client code generation. Applied automatically when the angular Maven profile is enabled.

Maven profiles

• sonar-cloud - for code analysis on push to master
• frontend-pre-sonar - for including code coverage reports from the frontend module during a sonar analysis
• frontend-sonar - for running only a sonar analysis for the frontend module
• angular - for generating client code

API documentation

First, build and run the application. Then you'll be able to reach the API docs.

Swagger

The Swagger UI page: http://localhost:8080/swagger-ui.html.

OpenAPI

The OpenAPI description is available at the following urls:

• http://localhost:8080/v3/api-docs - in json format
• http://localhost:8080/v3/api-docs.yaml - in yml format

Client code generation

To run client code generation using the openapi-generator-maven-plugin, execute the following command:

mvn clean verify -Pangular -DskipTests

The application will be started so that the API specification can be obtained from the Open API endpoint.

The generated code will be available in the frontend/src/main/angular/src/backend directory. Don't edit those files manually.

Working with frontend on a local environment

If you want to see how changes you make in the frontend code affect the application you don't need to build it together with the backend module every time. Use the following commands:

cd frontend/src/main/angular
ng serve

and visit http://localhost:4200/. The application reloads automatically which speeds up your work.

In order to incorporate changes into the project, rebuild the whole application from the main project directory with:

mvn clean package

Running test suites

Backend

Run unit tests with the following command in the project directory:

mvn test

Run all tests with the following command in the project directory:

mvn verify

Frontend

Run all tests for the Angular code with:

cd frontend/src/main/angular
ng test

SonarQube analysis on a local environment

This project is configured so that its integration tests are taken into consideration when calculating code coverage. SonarQube will show these tests as unit tests on the dashboard, as there is currently no native integration test support within Sonar.

Prerequisites

• You need to have Docker and Docker-Compose installed.
• You need Chrome installed on your machine to run a frontend analysis with code coverage.

Launching SonarQube on a local environment

To start a local instance of SonarQube, use the following command in the root of this repository:

docker-compose -f docker/sonarqube/docker-compose_sonar.yml --env-file docker/sonarqube/.env up -d

You should only need to do this once.

Note that the first run may take a while before SonarQube is fully configured - you may want to check the Docker logs for sonarqube_first_run_setup_backend to confirm whether the setup is finished successfully.

The Java analysis profile is stored in docker/sonarqube/java_profile.xml and is automatically restored when first launching the Docker instance.

The quality gate is defined in an init script (docker/sonarqube/import_data.sh) and is automatically restored when first launching the Docker instance.

The imported profile and quality gate are set as default.

Authentication is disabled by default.

The SonarQube instance will become available at http://localhost:9000.

Full analysis

You can run analysis for the whole project (both backend and frontend) by running the following command from the root of this repository:

mvn clean verify sonar:sonar -Pfrontend-pre-sonar -Ppitest-full

Backend analysis

You can run a separate analysis for the backend module:

cd backend
mvn clean verify sonar:sonar -Ppitest-full

Frontend analysis

You can run a separate analysis for the frontend module:

cd frontend
mvn sonar:sonar -Pfrontend-pre-sonar

Verifying results

Visit the Projects SonarQube page and choose the right project.

Mutation testing

Mutation testing is the act of automatically modifying existing code in small ways, then checking if our tests will fail. This project supports Java mutation testing through Pitest. Bear in mind that mutation testing may take a while.

To generate a full mutation coverage report, use the command:

mvn clean test-compile -Ppitest-full

Navigate to ./backend/target/pit-reports and open index.html to view the report.

The most efficient way to generate a local coverage report during development is:

mvn clean test-compile -Ppitest-new-code

This will only analyse code that has been changed compared to the main Git branch.

To use Pitest as part of Continuous Integration, use the following command in the CI script:

mvn clean test-compile -Ppitest-new-code -Ppitest-strict

This will fail the build if the mutation threshold is below a certain value.

Built With

• Maven
• Spring Boot v3.2+
• Angular v12+
• frontend-maven-plugin
• springdoc-openapi
• Bootstrap v5+
• ng-bootstrap

Table of contents generated with markdown-toc