add Gradle Java toolchain and improve documentation

This commit is contained in:
Michael Hoennig 2022-08-05 13:10:11 +02:00
parent 06996e4dc4
commit 433d0e19f5
4 changed files with 88 additions and 7 deletions

View File

@ -23,8 +23,10 @@ Everything is tested on _Ubuntu Linux 22.04_ and _MacOS Monterey (12.4)_.
To be able to build and run the Java Spring Boot application, you need the following tools:
- Docker 20.x (on MacOS you also need *Docker Desktop* or similar)
- PostgreSQL Server 13.7-bullseye (see instructions below to install and run in Docker)
- Java JDK 17.x
- PostgreSQL Server 13.7-bullseye
(see instructions below to install and run in Docker)
- Java JDK at least recent enough to run Gradle
(JDK 17.x will be automatically installed by Gradle toolchain support)
- Gradle in some not too outdated version (7.4 will be installed via wrapper)
You also might need an IDE (e.g. *IntelliJ IDEA* or *Eclipse* or *VS Code* with *[STS](https://spring.io/tools)* and a GUI Frontend for *PostgreSQL* like *Postbird*.
@ -207,6 +209,17 @@ pandoc --filter pandoc-plantuml rbac.md -o rbac.pdf
If you have figured out how it works, please add instructions above this section.
### IDE Specific Settings
#### IntelliJ IDEA
Go to [Gradle Settings}(jetbrains://idea/settings?name=Build%2C+Execution%2C+Deployment--Build+Tools--Gradle) and select "Build and run using" and "Run tests using" both to "gradle".
Otherwise, settings from `build.gradle`, like compiler arguments, are not applied when compiling through *IntelliJ IDEA*.
Go to [Annotations Processors](jetbrains://idea/settings?name=Build%2C+Execution%2C+Deployment--Compiler--Annotation+Processors) and activate annotation processing.
Otherwise, *IntelliJ IDEA* can't see *Lombok* generated classes
and will show false errors (missing identifiers).
### Other Tools
**jq**: a JSON formatter.
@ -238,7 +251,46 @@ You can explore the prototype as follows:
### Directory and Package Structure
Generally, the standard Java directory structure is used, where productive and test code are sparated like this:
#### General Directory Structure
.aliases
build/
build.gradle
doc/
.editorconfig
etc/
.git/
.gitattributes
.gitignore
.gradle/
gradle/
gradlew
gradlew.bat
.idea/
LICENSE.md
out/
README.md
.run/
settings.gradle
sql/
src/
TODO.md
TODO-progress.png
tools/
#### Source Code Package Structure
For the source code itself, the general standard Java directory structure is used, where productive and test code are separated like this:
```
src

View File

@ -8,7 +8,6 @@ plugins {
group = 'net.hostsharing'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'
wrapper {
distributionType = Wrapper.DistributionType.BIN
@ -25,6 +24,12 @@ repositories {
mavenCentral()
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
ext {
set('testcontainersVersion', "1.17.3")
}
@ -61,6 +66,10 @@ dependencyManagement {
}
}
tasks.withType(JavaCompile) {
options.compilerArgs += ["-parameters"]
}
tasks.named('test') {
useJUnitPlatform()
}

View File

@ -62,3 +62,13 @@ A whitebox-test knows and considers the internals of an implementation, e.g. it
A "double" is a general term for something which replaces a real implementation of a dependency of the unit under test.
This can be a "dummy", a "fake", a "mock", a "spy" or a "stub".
#### Test-Fixture
Generally a test-fixture refers to all code within a test
which is needed to setup the test environment and extract results,
but which is not part of the test-cases.
In other words: The code which is needed to bind test-cases to the actual unit under test,
is called test-fixture.

View File

@ -9,13 +9,16 @@
- [System-Integration-Tests](#system-integration-tests)
<!-- generated TOC end. -->
### General Issues
### General Concepts
The following test concept uses terms like "double" and "mock" (maybe in inflected form like "mocking" or "mocked"), "whitebox-test" and "blackbox-tests" and "test-fixture".
Please look up their definition in the [glossary](glossary.md)
Where our APIs should be designed in a way that it's possible, using a mocking library like *Mockito* often leads to shorter test code.
Most important for a test is, to clearly express what it actually is testing.
For this, it might help to wrap test setup and assertions into test fixture
### Kinds of Tests
@ -26,7 +29,7 @@ Depending on the concrete aspects which we want to test, we are using different
In this project a *Unit* for *UnitTests* can be a single method (function), a class or even a group of classes which express a common concept.
The unit are technically whitebox-tests and count into test-code-coverage.
But the whitebox-knowledge should only be used for the text-fixture.
But the whitebox-knowledge should only be used for the [test-fixture](./glossary.md#test-fixture).
Unit-Test in this project are implemented with *JUnit Jupiter*, *Mockito* and *AssertJ*.
@ -65,10 +68,17 @@ Such tests are implemented with *JUnit Jupiter* through some sort of `@SpringBoo
*Mockito* can also be used for this kind of tests, to separate multiple integrations.
Integration-Tests are relatively slow and therefore should focus on the integration.
Internal issues should be tested through Unit-Tests.
Java-internal issues should be tested through Unit-Tests.
These Tests are always named `...IntegrationTest` and can automatically run in the build-process.
##### DataJpaTest / Database-Integration-Tests
In this project, a major part of the program logic is coded in the database as stored procedures, functions and triggers.
This program logic is tested through *integration tests* using `DataJpaTest`
because pure unit tests in the database are not only cumbersome but also easily lead to large test gaps.
#### Acceptance-Tests