Puff

Open source smoke testing platform

Puff is an open source smoke testing platform for students to collaboratively write and run tests on their assignment or project code for quick and easy sanity testing.

Course-management

Spring-boot microservice managing courses, assignments and user actions for the puff platform. For the full overview of the puff project see the docs repository.

Getting started

Clone the project with https://github.com/puffproject/course-management.git

Install Java

You'll need Java to run Puff's microservices developed with Spring Boot.

Download and install the Java JDK 8
Set the JAVA_HOME environment variable
Verify your installation by running java -version

Install Maven

Puff uses Maven as its build tool for its backend.

Download and install Maven
Verify your installation with mvn -v

Setup Keycloak (If you haven't already)

Keycloak is an open source Identity and Access Management solution aimed at modern applications and services. It makes it easy to secure applications and services with little to no code.

Puff uses keycloak as a user management and authentication solution. More information about Keycloak can be found on their offical docs page.

Follow the instructions found at https://github.com/puffproject/docs#setup-keycloak to setup a local keycloak server. This only needs to be configured once.

Once configured, generate an authentication token by making the following curl call replacing TEST_USER_USERNAME, TEST_USER_PASSWORD and USER_AUTH_CLIENT_SECRET with the credentials for the test accounts you created and the client-secret for user-auth.

curl -X POST 'http://localhost:8180/auth/realms/puff/protocol/openid-connect/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=password' \
 --data-urlencode 'client_id=user-auth' \
 --data-urlencode 'client_secret=USER_AUTH_CLIENT_SECRET' \
 --data-urlencode 'username=TEST_USER_USERNAME' \
 --data-urlencode 'password=TEST_USER_PASSWORD'

Run the backend

In order to run a microservice locally run

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

If you need to build the .jar of the application run mvn package.
In order to run tests run mvn test.

Development

Swagger

Puff's Spring-Boot backend exposes a REST API. The project utilizes Swagger to document and keep a consistent REST interface.

Once you have a microservice running (See run the backend) visit http://localhost:8080/swagger-ui.html. A json api version to be consumed and used to generate client libraries can be accessed at http://localhost:8080/v2/api-docs. Select Authorize and login with a test user account to try out any of the endpoints.

H2 Database

Puff's Spring-boot backend uses a H2 runtime database to simulate a database connection for local development. Once the project is running it can be accessed at http://localhost:8080/h2.

The credentials for the database are as follows:

Driver Class: org.h2.Driver
JDBC URL: jdbc:h2:mem:testdb
User Name: admin
Password:

For more information about H2 databases see the H2 Database Engine.

Formatting

The codebase is auto-formatted with the formatter-maven-plugin that will format all source code files in the src/ and test/ directories according to the settings in the style.xml file, which are based on eclipse profile settings.

Run the formatter:format command to run the formatter. It is also bound to the format goal that will run as part of the compile phase.

You can also add the git hook in .hooks to your local .git/hooks folder to run the formatter on pre-commit.

Contributors

The Puff project is looking for contributors to join the initiative! For information about progress, features under construction and opportunities to contribute see our project board.

If you're interested in helping please read our CONTRIBUTING.md for details like our Code of Conduct and contact Benjamin Kostiuk for more information.

puffproject / course-management