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.
We implement a Banking system with the following use cases:
- Open account
- Withdraw funds
- Deposit funds
- View account
We also have authentication with Keycloak - a realm with client_id and with client_credentials flow enabled.
The overall architecture is split into:
- Application Core (
core) layer contains the business logic. - Adapter (
adapter) layer contains the infrastructural concerns.
The Application Core(core) is composed of:
- Ports (
ports), representing an interface to the Application Core, isolating it from infrastructural concerns. There are both Driver (driver) ports, representing use cases; and Driven (driven) ports, representing gateways. - Internals (
internal), representing the internal implementation of the Application Core, more specifically, the implementation of the Driver (driver) ports. This implementation can be anything. Here we illustrate the implementation with Clean Architecture (cleanarch) approach and the CRUD (crud) approach, but other approaches are possible too. The use case tests are independent of the implementation approach; the internal implementation is thus swappable.
The Adapter (adapter) layer is composed of driver adapters and driven adapters.
- Driver adapters: REST API Adapter (
adapter-restapi-*) - Driven adapters: Persistence Adapters (
adapter-persistence-*), Random Number Generation Adapters (adapter-generation-*), Time Adapters (adapter-time-*), Third Party Integration Adapters (adapter-thirdparty-*), and Messaging Adapters (adapter-messaging-*).
The application can be executed via startup.
- Core Layer: Unit Tests targeting the Driver Ports.
- Adapter Layer: Integration Tests targeting the Driven Ports. In cases of integrating with third-party systems or microservices, we use Contract Testing.
As can be seen below, you can separately run these fast-running and slow-running tests.
- OpenJDK 17
- Docker
Make sure that Gradle works:
./gradlew
Remove old images/volumes:
docker-compose down -vApply the environment variables (Windows):
. .\env\env.ps1Apply the environment variables (for Linux/Mac):
source ./env/env.shApply 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 docker/for-mac#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.0Run docker:
docker-compose up -dhttp://localhost:15672
user: admin
pass: admin
Run unit tests for core:
./gradlew coreTest
As a prerequisite, please see Environment Setup.
To run all the adapter integration tests:
./gradlew adapterTestNote: Currently, this fails locally due to open issues with Flyway & MongoDB( #111 and #114).
As a prerequisite, please see Environment Setup.
To run the whole system tests:
./gradlew systemTestNote: Currently, this fails locally due to open issues with Flyway & MongoDB( #111 and #114).
As a prerequisite, please see Environment Setup.
In the above instructions, we ran the tests separately. You can run them all:
./gradlew testNote: Currently, this fails locally due to open issues with Flyway & MongoDB( #111 and #114).
Run code coverage (executes Jacoco):
./gradlew codeCoverageTo run it for specific project:
./gradlew core:codeCoverageRun mutation testing (executes pitest):
./gradlew mutationTestSee the build\reports directory for the generated reports for test results, code coverage and mutation testing.
Reports:
- build\reports\tests
- build\reports\jacoco
- build\reports\pitest
To manually run the app.
./gradlew runAppThen CTRL+C to terminate the app.
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 -dYou 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:testFor code coverage, the underlying call is:
./gradlew jacocoTestReportFor mutation testing, the underlying call is:
./gradlew pitestFor 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 databaseIf you experience Integration Tests failing, please see the following known issue #64.
If you experience any other issues, please create a ticket https://github.com/valentinacupac/banking-kata-java/issues/new
Our contributors are:
- Valentina Cupać (valentinacupac)
- Adrián Lizaga (adrianliz)
- Amin Talukder (eamtalu)
- Franco Lombardo (f-lombardo)
- Donald Siziba (donaldsiziba)
- Joao Cipriano (JoaoCipriano)
- Guillaume Taffin (GuillaumeTaffin)
- Juliano Silva (julianojj)
If you'd like to contribute, see instructions here https://github.com/valentinacupac/banking-kata-java/blob/main/CONTRIBUTING.md
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent