search

valentinajemuovic / banking-kata-java

Banking Kata (Java)
MIT License
346 stars 92 forks source link
clean-architecture java tdd

readme

Banking Kata - Java

CI

Overview

This project illustrates TDD & Clean Architecture implementation in Java, showing the Use Case Driven Development Approach.

This demo was created for the purposes of meetup series on TDD & Clean Architecture. See the YouTube Meetups. Please note that this project is purely for demo purposes only.

Business Requirements

We implement a Banking system with the following use cases:

We also have authentication with Keycloak - a realm with client_id and with client_credentials flow enabled.

Architecture

The overall architecture is split into:

The Application Core(core) is composed of:

The Adapter (adapter) layer is composed of driver adapters and driven adapters.

The application can be executed via startup.

Tests

As can be seen below, you can separately run these fast-running and slow-running tests.

Prerequisites

Running Gradle

Make sure that Gradle works:

./gradlew

Environment Setup

Remove old images/volumes:

docker-compose down -v

Apply the environment variables (Windows):

. .\env\env.ps1

Apply the environment variables (for Linux/Mac):

source ./env/env.sh

Apply the environment variable in the ide, in case if it needs to run the application from ide UI button For intellij, there is a plugin EnvFile can help to run the env file.

#chmod 777 ./env/env.intellij.ui
Then select the Run->Edit configuration which will then provide the option to import and run the file.

For Mac only, you need to build a custom Keycloak image to enable Keycloak to work on Mac M1. This is due to a reported Mac-specific issue https://github.com/docker/for-mac/issues/5310. For any other OS, please skip this step, because this issue is Mac-specific:

cd startup
chmod +x ./src/main/resources/keycloak/build-keycloak-image-m1.zsh
./src/main/resources/keycloak/build-keycloak-image-m1.zsh 16.0.0

Run docker:

docker-compose up -d

verify if rabbitmq admin console is accessible and the docker image is running without issues

http://localhost:15672
user: admin
pass: admin

Running Unit Tests

Run unit tests for core:

./gradlew coreTest

Running Integration Tests

As a prerequisite, please see Environment Setup.

To run all the adapter integration tests:

./gradlew adapterTest

Note: Currently, this fails locally due to open issues with Flyway & MongoDB( #111 and #114).

Running System Tests

As a prerequisite, please see Environment Setup.

To run the whole system tests:

./gradlew systemTest

Note: Currently, this fails locally due to open issues with Flyway & MongoDB( #111 and #114).

Running all Tests

As a prerequisite, please see Environment Setup.

In the above instructions, we ran the tests separately. You can run them all:

./gradlew test

Note: Currently, this fails locally due to open issues with Flyway & MongoDB( #111 and #114).

Running Code Coverage

Run code coverage (executes Jacoco):

./gradlew codeCoverage

To run it for specific project:

./gradlew core:codeCoverage

Running Mutation Testing

Run mutation testing (executes pitest):

./gradlew mutationTest

Viewing Reports

See the build\reports directory for the generated reports for test results, code coverage and mutation testing.

Reports:

Running Spring Boot

To manually run the app.

./gradlew runApp

Then CTRL+C to terminate the app.

Optional Notes

The following are for additional reading, you do not need to execute these, but you can if you wish.

Environment variables are located inside the env folder. You can optionally choose to edit them.

You can choose to run the tests via IntelliJ UI.

In the case of integration tests (for adapters) you'd have to specify environment variables before you run the tests. To do that, you can copy the text from the file env/env.intellij.ui into the Environment variables section into Tests in 'banking-kata.adapters' configuration.

To run Docker with the environment file:

docker-compose --env-file=env/.env.local up -d

You can run the integration tests individually, e.g. if you modified a module (in this way you avoid waiting for all of them to finish):

./gradlew adapter-persistence-jpa:test

For code coverage, the underlying call is:

./gradlew jacocoTestReport

For mutation testing, the underlying call is:

./gradlew pitest

For flyway operation from CLI: There will be flyway tasks available in the gradle as the plugin is applied to adapter-persistence-jpa. Tasks can be executed by the following way -

./gradlew adapter-persistence-jpa:flywayInfo  //will provide the schema file under flywayInfo
./gradlew adapter-persistence-jpa:flywayClean //will clear up the schema from database
./gradlew adapter-persistence-jpa:flywayMigrate //will apply the db schema migration into database

Issues

If you experience Integration Tests failing, please see the following known issue https://github.com/valentinacupac/banking-kata-java/issues/64.

If you experience any other issues, please create a ticket https://github.com/valentinacupac/banking-kata-java/issues/new

Contributors

Our contributors are:

Contributing

If you'd like to contribute, see instructions here https://github.com/valentinacupac/banking-kata-java/blob/main/CONTRIBUTING.md