wavetogether / templates_kotlin_spring

Template project for Kotlin + Spring configuration, as name describes.

Kotlin-Spring boot project template

Table of Contents

• Overview
• Tools and frameworks
• Building and running
  • How to build
  • How to run
  • How to run tests and get reports
  • How to generate API documentation
  • How to measure code quality and get reports

Overview

Kotlin & Spring boot project template for rapid development setup.

Template branches:

• main - Simplest.

• spring-data-jpa - JPA on simplest version

Tools and frameworks

• Build tool:

  • Gradle 7.1

• Languages and Platforms:

  • Java 17

  • Kotlin 1.5

  • Groovy 3.0

• Frameworks and environments:

  • Undertow

  • Spring boot

• Code quality measurements:

  • JUnit 5

  • detekt

• Automatic documentation

  • Spring RESTDocs

  • Asciidoctor

Building and running

It is better to declare JAVA_HOME environment variable and make java command executable via PATH before following these instructions.

How to build

./gradlew clean assemble [-PbuildConfig=<local|alpha|beta|release>]

• buildConfig is set to local by default, if omitted or set to wrong value.

• Stand-alone JAR executable is created under app-main/build/libs after assemble task is ran.

How to run

You must create application.yml file on project root or execution context root directory before running project. There is application.yml.sample on project root, for quick reference.

After a successful build, run server as following:

java -jar app-main/build/libs/{app-name}-{app-version}.jar

How to run tests and get reports

Tests must be organised by execution time, and they could be grouped as three categories:

1. Small test: a.k.a. 'Unit test', must be run quickly and frequently.

2. Medium test: a.k.a. 'Integration test', must be run before code check-in.

3. Large test: a.k.a. 'End-to-end test', must be run before code integration.

You can find detailed rules for test groups in TestTags.kt.

• Running tests:

  gradlew [<smallTest|mediumTest|largeTest>|test] [jacocoTestReport]

  test for running all tests, and other options for running tests in group, respectively.

• Getting test reports:

  Test reports are automatically generated under build/reports directory of each module after all tests are run.

• Getting code coverage reports:

  Running Gradle task jacocoTestReport while running tests will generate reports under build/reports/jacoco both in XML and HTML formats.

How to generate API documentation

Simply, run tests that involving actual API calls and with asciidoctor task as following:

gradlew [<smallTest|mediumTest|largeTest>|test] asciidoctor

However, it is advised to run such tests in a large scale - group them as largeTest - to provide a documentation that reflects client’s point of view as much as possible.

Thus, in this template project all endpoint tests are marked as TestTags.TEST_LARGE by default in RestAssuredTestBase class.

How to measure code quality and get reports

1. Generating detekt code analysis report

   gradlew [:<GRADLE_MODULE_NAME>:]detekt

   detekt report file is created as build/reports/detekt.html per module if module name is omitted.

2. Generating jacoco code coverage report

   gradlew [<smallTest|mediumTest|largeTest>|test] jacocoTestReport

   jacoco coverage report file is created under build/reports/jacoco/ directory if tests are executed successfully.