Merge pull request #1 from lmirabal/list-accounts

List accounts

Author: lmirabal

README.md

@@ -0,0 +1,40 @@
+# Testing using hexagonal architecture
+
+Use a bank example to demonstrate how using a hexagonal architecture can help to test an application.
+
+## Structure
+
+The application is split into 3 modules:
+
+- domain: business logic driving how the bank behaves.
+- http: api to expose the bank functionality via http.
+- web: dummy web ui driving the application.
+
+## Solution
+
+The business logic of the bank is fully implemented as part of the domain. As per typical hexagonal architecture, where
+an interaction is needed with the outside world, a contract (port) is defined to state how the application expects that
+to happen. In this example only 2 are defined:
+
+- one that allows to drive the application by exposing all the banks capabilities - driving or primary port;
+- and another to define how the bank accounts data is stored and queried - driven or secondary port.
+
+The isolation of the business logic that the hexagonal architecture provides, allows components to have a single
+purpose, only mapping from the technology in use to business terms. This is considered one of its main benefits but here
+we attempt to show how it can also greatly help testing.
+
+Having every component in the system defined in terms of contracts means that writing tests based on those very same
+contracts allows to have a single suite of tests that can be run against any layer of the system, providing excellent
+test coverage for the whole system with small effort.
+
+This example mainly focuses in the contract defining how the business behaves as it highlights the benefits of the
+approach, but the same strategy can be applied to any other port. For examples, if there were multiple ways to
+store/query accounts, a single test could be defined to test all of them.
+
+## Technology
+
+The intention is to have as simple as possible code so very few external dependencies are used. It's implemented in
+[kotlin](https://kotlinlang.org), my preferred programming language, and the only production dependency is the
+[http4k](http://http4k.org/) library, which is used to define the http api as well as the server templating in the ui.
+
+For testing, only [junit5](https://junit.org/junit5/) and [hamkrest](https://github.com/npryce/hamkrest) are used.

build.gradle

@@ -15,6 +15,7 @@ subprojects {
     dependencies {
         testImplementation 'org.jetbrains.kotlin:kotlin-test-junit5'
         testImplementation 'org.junit.jupiter:junit-jupiter-api:5.7.0'
+        testImplementation 'com.natpryce:hamkrest:1.8.0.1'
         testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.7.0'
     }
 

domain/build.gradle

@@ -0,0 +1,13 @@
+plugins {
+    id 'java-test-fixtures'
+}
+
+dependencies {
+    testFixturesImplementation 'org.jetbrains.kotlin:kotlin-test-junit5'
+    testFixturesImplementation 'org.junit.jupiter:junit-jupiter-api:5.7.0'
+    testFixturesImplementation 'com.natpryce:hamkrest:1.8.0.1'
+}
+
+compileTestFixturesKotlin {
+    kotlinOptions.jvmTarget = '11'
+}

domain/src/main/kotlin/lmirabal/bank/Bank.kt

@@ -0,0 +1,8 @@
+package lmirabal.bank
+
+import lmirabal.bank.model.BankAccount
+
+interface Bank {
+    fun createAccount(): BankAccount
+    fun listAccounts(): List<BankAccount>
+}

domain/src/main/kotlin/lmirabal/bank/BankService.kt

@@ -0,0 +1,18 @@
+package lmirabal.bank
+
+import lmirabal.bank.data.BankAccountRepository
+import lmirabal.bank.model.Amount
+import lmirabal.bank.model.BankAccount
+import lmirabal.bank.model.BankAccountId
+
+class BankService(
+    private val accountRepository: BankAccountRepository,
+    private val idFactory: () -> BankAccountId = { BankAccountId.random() }
+) : Bank {
+    override fun createAccount(): BankAccount {
+        return BankAccount(idFactory(), Amount.ZERO)
+            .also { newAccount -> accountRepository.add(newAccount) }
+    }
+
+    override fun listAccounts(): List<BankAccount> = accountRepository.list()
+}

domain/src/main/kotlin/lmirabal/bank/data/BankAccountRepository.kt

@@ -0,0 +1,8 @@
+package lmirabal.bank.data
+
+import lmirabal.bank.model.BankAccount
+
+interface BankAccountRepository {
+    fun add(account: BankAccount)
+    fun list(): List<BankAccount>
+}

domain/src/main/kotlin/lmirabal/bank/data/InMemoryBankAccountRepository.kt

@@ -0,0 +1,13 @@
+package lmirabal.bank.data
+
+import lmirabal.bank.model.BankAccount
+
+class InMemoryBankAccountRepository : BankAccountRepository {
+    private val accounts: MutableList<BankAccount> = arrayListOf()
+
+    override fun add(account: BankAccount) {
+        accounts.add(account)
+    }
+
+    override fun list(): List<BankAccount> = accounts
+}

domain/src/main/kotlin/lmirabal/bank/model/Amount.kt

@@ -0,0 +1,8 @@
+package lmirabal.bank.model
+
+data class Amount(val minorUnits: Long) {
+
+    companion object {
+        val ZERO = Amount(0)
+    }
+}

domain/src/main/kotlin/lmirabal/bank/model/BankAccount.kt

@@ -0,0 +1,12 @@
+package lmirabal.bank.model
+
+import java.util.UUID
+
+data class BankAccount(val id: BankAccountId, val balance: Amount)
+
+data class BankAccountId(val value: UUID) {
+
+    companion object {
+        fun random() = BankAccountId(UUID.randomUUID())
+    }
+}

domain/src/test/kotlin/lmirabal/bank/BankServiceTest.kt

@@ -0,0 +1,22 @@
+package lmirabal.bank
+
+import com.natpryce.hamkrest.assertion.assertThat
+import com.natpryce.hamkrest.equalTo
+import lmirabal.bank.data.InMemoryBankAccountRepository
+import lmirabal.bank.model.Amount
+import lmirabal.bank.model.BankAccount
+import lmirabal.bank.model.BankAccountId
+import org.junit.jupiter.api.Test
+
+class BankServiceTest : BankTest() {
+    private val id = BankAccountId.random()
+    private val idFactory = { id }
+    override val bank = BankService(InMemoryBankAccountRepository(), idFactory)
+
+    @Test
+    fun createsAnAccount() {
+        val account = bank.createAccount()
+
+        assertThat(account, equalTo(BankAccount(id, Amount.ZERO)))
+    }
+}