📝 Document application & calculator packages

Author: peterjamesmatthews

README.md

@@ -0,0 +1,28 @@
+# Go Mock
+
+An example go library that uses [`go.uber.org/mock`](https://pkg.go.dev/go.uber.org/mock) to easily
+mock an external service for unit testing.
+
+An important `Application` method `CoolAlgorithm` needs to be unit tested.
+
+`CoolAlgorithm` relies on an external `calculator` service and for whatever reason, that external
+service cannot be used during unit testing.
+
+To remedy this, we first define the `Calculatorer` interface:
+
+In order to mock this interface, we first have to install `mockgen`:
+
+```sh
+go install go.uber.org/mock/mockgen@latest
+```
+
+We then use `mockgen` to generate a mock client to use in our unit test:
+
+```sh
+mockgen -source=./calculator/Calculatorer.go -destination=./mock_calculator/Client.go
+```
+
+Finally, we construct an `Application` instance that uses our mocked client. We set expectations and
+return values for the methods that will be called during the `CoolAlgorithm` unit test:
+
+_TODO: add code examples_

app/Application.go

@@ -0,0 +1,9 @@
+package application
+
+import "pjm.dev/mock/calculator"
+
+// Application holds the main application state and functionality.
+type Application struct {
+	// Calculator is the application's interface with the calculator service.
+	Calculator calculator.Calculatorer
+}

application/Application.go

@@ -1,7 +1,8 @@
-package app
+package application
 
-func (application *Application) CoolAlgorithm(x int) int {
-	var output int = x
+// CoolAlgorithm is an important bit of Application functionality that relies on the Calculatorer interface.
+func (application *Application) CoolAlgorithm(input int) int {
+	var output int = input
 
 	output = application.Calculator.Add(output, 0)
 	output = application.Calculator.Subtract(output, 0)

app/CoolAlgorithm.go renamed to application/CoolAlgorithm.go

@@ -1,17 +1,17 @@
-package app_test
+package application_test
 
 import (
 	"testing"
 
 	"go.uber.org/mock/gomock"
-	"pjm.dev/mock/app"
+	"pjm.dev/mock/application"
 	"pjm.dev/mock/mock_calculator"
 )
 
 func TestCoolAlgorithm(t *testing.T) {
 	ctrl := gomock.NewController(t)
 	mockCalculator := mock_calculator.NewMockCalculatorer(ctrl)
-
+	application := application.Application{Calculator: mockCalculator}
 	number := 100
 
 	mockCalculator.
@@ -38,7 +38,6 @@ func TestCoolAlgorithm(t *testing.T) {
 		Times(1).
 		Return(number)
 
-	application := app.Application{Calculator: mockCalculator}
 	if application.CoolAlgorithm(number) != number {
 		t.Fail()
 	}

app/CoolAlgorithm_test.go renamed to application/CoolAlgorithm_test.go

@@ -1,8 +1,13 @@
 package calculator
 
+// Interface that the external calculator service implements.
 type Calculatorer interface {
+	// Add returns the sum of two ints.
 	Add(int, int) int
+	// Subtract returns the difference of two ints.
 	Subtract(int, int) int
+	// Multiply returns the product of two ints.
 	Multiply(int, int) int
+	// Divide returns the quotient of two ints.
 	Divide(int, int) int
 }

calculator/Calculatorer.go

@@ -1,5 +1,9 @@
 package calculator
 
+// Client is a toy implementation of the Calculatorer interface that can't be used in unit tests.
+//
+// In the real application, this would use whatever protocol the calculator service uses to
+// communicate.
 type Client struct{}
 
 func (client *Client) Add(a int32, b int32) int32 {