Testing in Go

Fast            --- Milliseconds per test. Second(s) (or less) for all tests
Isolated        --- Order agnostic. No dependency on state, system, test environments etc
Repeatable      --- Same results anywhere, anytime, any number of times
Self-Validating --- A Test can determine by itself whether it failed or passed.
Timely          --- Tests are written just before the the code they test

Setup    - Automatically setup the environment and dependencies
Teardown - Clean up everything. Restore initial test state

> go help test      // description of of what 'go test' does
> go help tesfunc   // description of the function spec
> go test -h        // CLI flags and their description
> go test           // discovers and executes tests in your current package

func TestXxx(*testing.T)

TestInvalidLoginReturnsError     // valid test name
TestarossaFerrari                // invalid test name

import "testing"

func TestExample(t *testing.T) {
    t.Log("Hello World!")
}

PASS
ok      github.com/pshirali/testing-in-go/samples/ex1    0.006s

=== RUN   TestExample
--- PASS: TestExample (0.00s)
    sample_test.go:6: Hello World!
PASS
ok      github.com/pshirali/testing-in-go/samples/ex1    0.006s

Skip the test from the point where it's called

Log a message. (go test '-v')

Log an error. Marks the test FAIL, but continues execution.

- Log a fatal error.
- Mark the test FAIL, and stop execution of the current test.
- Execute any deferred functions.
- Proceed to the next test.

Can be used when a test logic needs to be executed
with multiple sets of inputs and corresponding results.

package adder

func AddInt(integers ...int) int {
    sum := 0
    for _, i := range integers {
        sum += i
    }
    return sum
}

func TestAdderUsingTable(t *testing.T) {
    cases := []struct {
        integers []int
        expected int
    }{
        {[]int{}, 0},        // -------------------------------------------
        {[]int{0, 0, 0}, 0}, //  TABLE: { Input, Expected }
        {[]int{-1, -2}, -3}, //  One set of test params per test iteration
        {[]int{1, 2, 3}, 6}, // -------------------------------------------
    }

    for _, c := range cases {
        t.Logf("-------------------- Adding: %v", c.integers)
        actual := adder.AddInt(c.integers...)
        if actual != c.expected {
            t.Errorf("Sum of %v = %v (Actual). Expected: %v",
                c.integers, actual, c.expected)
        }
    }
}

=== RUN   TestAdderUsingTable
--- PASS: TestAdderUsingTable (0.00s)
    adder_test.go:20: -------------------- Adding: []
    adder_test.go:20: -------------------- Adding: [0 0 0]
    adder_test.go:20: -------------------- Adding: [-1 -2]
    adder_test.go:20: -------------------- Adding: [1 2 3]
PASS
ok      github.com/pshirali/testing-in-go/samples/ex2    0.007s

        if actual != c.expected {
            t.Errorf("Sum of %v = %v (Actual). Expected: %v",
                c.integers, actual, c.expected)
        }

func TestAdderUsingSubtests(t *testing.T) {
    cases := []struct {
        name     string
        integers []int
        expected int
    }{
        {"Empty", []int{}, 0},
        {"Zero", []int{0, 0, 0}, 0},
        {"Negative", []int{-1, -2}, -3},
        {"Positive", []int{1, 2, 3}, 6},
    }

    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            t.Logf("-------------------- Adding: %v", c.integers)
            actual := adder.AddInt(c.integers...)
            if actual != c.expected {
                t.Fatalf("Sum of %v = %v (Actual). Expected: %v",
                    c.integers, actual, c.expected)
            }
        })
    }
}

=== RUN   TestAdderUsingSubtests
=== RUN   TestAdderUsingSubtests/Empty
=== RUN   TestAdderUsingSubtests/Zero
=== RUN   TestAdderUsingSubtests/Negative
=== RUN   TestAdderUsingSubtests/Positive
--- PASS: TestAdderUsingSubtests (0.00s)
    --- PASS: TestAdderUsingSubtests/Empty (0.00s)
        adder_test.go:45: -------------------- Adding: []
    --- PASS: TestAdderUsingSubtests/Zero (0.00s)
        adder_test.go:45: -------------------- Adding: [0 0 0]
    --- PASS: TestAdderUsingSubtests/Negative (0.00s)
        adder_test.go:45: -------------------- Adding: [-1 -2]
    --- PASS: TestAdderUsingSubtests/Positive (0.00s)
        adder_test.go:45: -------------------- Adding: [1 2 3]
PASS
ok      github.com/pshirali/testing-in-go/samples/ex2    0.007s

// SkipIf skips the test if the condition is true
func SkipIf(t *testing.T, condition bool, args ...interface{}) {
    if condition { t.Skip(args...) }
}

// Assert fatally fails the test if a condition is false
func Assert(t *testing.T, condition bool, args ...interface{}) {
    if !condition { t.Fatal(args...) }
}

// Equal deeply compares two types and fatally fails if they are unequal
import "reflect"
func Equal(t *testing.T, lhs, rhs interface{}, args ...interface{}) {
    if !reflect.DeepEqual(lhs, rhs) { t.Fatal(args...) }
}

Dirs and files that begin with "." or "_" are ignored by go tool
Dirs named "testdata" are ignored

1. A counter has an initial value of 0.
2. Exposes method to increment value. Implicit increment by 1.
3. Exposes method to retrieve current value.
4. Exposes method to reset value to 0.

package counter

type Resetter interface{ Reset() }
type Incrementer interface{ Increment() }
type IntValuer interface{ Value() int }

package unsafe_counter

type unsafeCounter struct {
    value int
}

func (c *unsafeCounter) Reset()     { c.value = 0 }
func (c *unsafeCounter) Increment() { c.value += 1 }
func (c *unsafeCounter) Value() int { return c.value }

func NewUnsafeCounter() *unsafeCounter {
    return &unsafeCounter{}
}

func TestCounterIncrementIncreasesValue(t *testing.T) {
    c := NewUnsafeCounter()
    for i := 1; i < 3; i++ {
        c.Increment()
        Assert(t, c.Value() == i, "At Step:", i, "!=", c.Value())
    }
}

func TestCounterIncrementReset(t *testing.T) {
    c := NewUnsafeCounter()
    for i := 0; i < 2; i++ {
        c.Increment()
    }
    c.Reset()
    Assert(t, c.Value() == 0, "Expected 0 after Reset. Got:", c.Value())
}

c := NewUnsafeCounter()

type safeCounter struct {
    mu sync.RWMutex
    uc UnsafeCounter
}

func (c *safeCounter) Reset() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.uc.Reset()
}
func (c *safeCounter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.uc.Increment()
}
func (c *safeCounter) Value() int {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.uc.Value()
}
func NewSafeCounter() *safeCounter {
    return &safeCounter{uc: NewUnsafeCounter()}
}

X = All tests which test the behavior of 'Counter' interface
Y = Multiple implementations which satisfy 'Counter'
    Thus, each implementation must satisfy all tests in X

NewUnsafeCounter() *unsafeCounter
NewSafeCounter() *safeCounter

- We only have access to the constructor function, not the structs
- We only get pointers to respective structs
- Constructor signatures are (and also assumed to be) different for
  each implementation
- The only 'commonality' is that the respective structs satisfy 
  a common (in this case 'Counter') interface

type CounterBuilder func() Counter

func <Interface>Builder() <Interface> {
    // instantiate dependencies here
    // return a new instance here
    return <Constructor>() // returns a pointer
}

func UnsafeCounterBuilder() Counter {
    return NewUnsafeCounter() // returns *unsafeCounter
}

func SafeCounterBuilder() Counter {
    return NewSafeCounter() // returns *safeCounter
}

func() Counter

type suite struct {
    builder func() Counter
}

func Suite(builder func() Counter) *suite {
    return &suite{builder: builder}
}

func (s *suite) TestCounterIncrementIncreasesValue(t *testing.T) {     // Added (s *suite)
    c := s.builder()              // <---------------------- new instance built by builder
    for i := 1; i < 3; i++ {
        c.Increment()
        Assert(t, c.Value() == i, "At Step:", i, "!=", c.Value())
    }
}

func (s *suite) TestCounterIncrementReset(t *testing.T) {              // Added (s *suite)
    c := s.builder()              // <---------------------- new instance built by builder
    for i := 0; i < 2; i++ {
        c.Increment()
    }
    c.Reset()
    Assert(t, c.Value() == 0, "Expected 0 after Reset. Got:", c.Value())
}

1. Tests are now methods implemented on Suite struct
2. Each test gets a fresh instance of Counter supplied by `s.builder()`

func (s *suite) RunAllTests(t *testing.T) {
    v := reflect.ValueOf(s)                                 //  1. Reflect on the suite
    for n := 0; n < v.NumMethod(); n++ {                    //  2. Iterate through method numbers
        i := v.Method(n).Interface()                        //  3. Get the method as interface{}
        if method, ok := i.(func(*testing.T)); ok {         //  4. If it matches test signature
            methodName := reflect.TypeOf(s).Method(n).Name  //  5. Get the method's name
            if strings.HasPrefix(methodName, "Test") {      //  6. If it begins with 'Test'
                t.Run(methodName, method)                   //  7. Run that method as a test
            }
        }
    }
}

The method 'RunAllTests' also matches the test signature 'func(*testing.T)'
Step 6 exists to exclude 'RunAllTests' and avoid a recursive loop

func TestCounterSuite(t *testing.T) {    // Table + Subtest driven tests against the Suite
    cases := []struct {
        name    string
        builder func() Counter
    }{
        {"SafeCounter", SafeCounterBuilder},
        {"UnsafeCounter", UnsafeCounterBuilder},
    }

    for _, c := range cases {
        t.Run(c.name, Suite(c.builder).RunAllTests)
    }
}

samples/ex3/test_suite $> go test -v

=== RUN   TestCounterSuite
=== RUN   TestCounterSuite/SafeCounter
=== RUN   TestCounterSuite/SafeCounter/TestCounterIncrementIncreasesValue
=== RUN   TestCounterSuite/SafeCounter/TestCounterIncrementReset
=== RUN   TestCounterSuite/UnsafeCounter
=== RUN   TestCounterSuite/UnsafeCounter/TestCounterIncrementIncreasesValue
=== RUN   TestCounterSuite/UnsafeCounter/TestCounterIncrementReset
--- PASS: TestCounterSuite (0.00s)
    --- PASS: TestCounterSuite/SafeCounter (0.00s)
        --- PASS: TestCounterSuite/SafeCounter/TestCounterIncrementIncreasesValue (0.00s)
        --- PASS: TestCounterSuite/SafeCounter/TestCounterIncrementReset (0.00s)
    --- PASS: TestCounterSuite/UnsafeCounter (0.00s)
        --- PASS: TestCounterSuite/UnsafeCounter/TestCounterIncrementIncreasesValue (0.00s)
        --- PASS: TestCounterSuite/UnsafeCounter/TestCounterIncrementReset (0.00s)
PASS
ok      github.com/pshirali/testing-in-go/samples/ex3/test_suite    0.007s

samples/ex3/test_suite $> go test -d

@@ TestCounterSuite : 0xc0000a6100 *testing.T
   ==== RunAllTests : 0xc0000a6200 *testing.T
        ===== Test1 : 0xc0000a6300 *testing.T
         \_ Counter : 0xc0000b0080 *safe_counter.safeCounter
        ===== Test2 : 0xc0000a6400 *testing.T
         \_ Counter : 0xc0000b00e0 *safe_counter.safeCounter
   ==== RunAllTests : 0xc0000a6500 *testing.T
        ===== Test1 : 0xc0000a6600 *testing.T
         \_ Counter : 0xc000070238 *unsafe_counter.unsafeCounter
        ===== Test2 : 0xc0000a6700 *testing.T
         \_ Counter : 0xc000070308 *unsafe_counter.unsafeCounter
PASS
ok      github.com/pshirali/testing-in-go/samples/ex3/test_suite    0.007s

func (s *suite) RunAllTests(t *testing.T) {
    //
    // Before and After Suite (defer <After>())
    //
    v := reflect.ValueOf(s)
    for n := 0; n < v.NumMethod(); n++ {
        i := v.Method(n).Interface()
        if method, ok := i.(func(*testing.T)); ok {
            methodName := reflect.TypeOf(s).Method(n).Name
            if strings.HasPrefix(methodName, "Test") {
                // Before Test
                // (don't defer <AfterTest>() here, inside a loop)
                t.Run(methodName, method)
                // After Test
            }
        }
    }
}

samples/ex3/test_suite $> go test -w

    >>> [ RunAllTests -Before- ] >>>            // SafeCounter

        --- [ BeforeTest: TestCounterIncrementIncreasesValue ] ---
        --- [ AfterTest: TestCounterIncrementIncreasesValue ] ---
        --- [ BeforeTest: TestCounterIncrementReset ] ---
        --- [ AfterTest: TestCounterIncrementReset ] ---

    <<< [ RunAllTests -After- ] <<<

    >>> [ RunAllTests -Before- ] >>>            // UnsafeCounter

        --- [ BeforeTest: TestCounterIncrementIncreasesValue ] ---
        --- [ AfterTest: TestCounterIncrementIncreasesValue ] ---
        --- [ BeforeTest: TestCounterIncrementReset ] ---
        --- [ AfterTest: TestCounterIncrementReset ] ---

    <<< [ RunAllTests -After- ] <<<

PASS
ok      github.com/pshirali/testing-in-go/samples/ex3/test_suite    0.007s

func (s *suite) GenerateTestData()
func (s *suite) DoSomethingAwesomeWith(c Counter)

Suite(c TestConfig, builder ()func Interface).RunAllTests
- TestConfig := LocalFileSystem, InMemoryFileSystemAbstraction,
                InMemoryDatabase, RealDatabase, etc.
- builder    := Implementations under test

Suite(..).RunAllTests
Suite(..).RunSpecificTests
Suite(..).RunPrivateTests
          \_ RunPrivateTests exposes the runner, but hides the 'testMethods'
             1. The suite could be published in a package
             2. Consumer cannot modify the tests

INGREDIENTS:
2 tests
2 implementations
1 fat 'Counter' interface (which happened to have all methods from the implementations)

1. Large X -- Large number of tests to validate one input-set/implementation
2. The tests effectively use all methods of the interface

1. If a Suite requires a fat interface, but clusters within the suite use a subset of interfaces.
   
   Problem  : THE SUITE IS TOO MIXED. It breaks single-responsibility-principle
   Solution : Break the suite into smaller suites where:
              - The interface footprint is smaller
              - The cluser of tests now effectively use all methods

PROS of reflection vs a manual list of 't.Run'
- Works great for large number of tests
- Proof against misspelt test names (strings, not TestFunction names)
- Proof against maintenance of the 'Run' list

CONS
- Overkill

Example:
1. TestCounterSuite tests basic counter functionality
2. TestCounterSuite DID NOT test 'goroutine safety' in SafeCounter
   Testing the goroutine safety of counters would be a different suite by itself

Example:
An implementation which returns numbers from the fibonacci series
on 'Increment()' could still satisfy the 'Counter' interface, but
fail TestCounterSuite

1. MUST NOT:
Share state between tests
- Stateful Suite members with testdata
- State dependent on order of test execution

2. SHOULD NOT:
- Perform excessive Setup or Teardown outside the test function
- This should be invoked from within each test function per test.
- Copy-paste is not considered (as) bad in testing (but don't overdo)

3. SHOULD NOT:
Make the Suite complex any more than it should be.
- Core Suite responsiblity: (single responsibility principle)
    a) Encapsulate a collection of tests
    b) Provide runner(s) to execute those tests
- Extend responsibly
- "Test" is the king. "Suite" is the helper.

Handler {                   |  Runner {
    Middleware1 {           |      TestFunction {
        Middleware2 {       |          Env Setup+ defer Teardown
            BusinessCode {} |          Test Setup+ defer Teardown
        }                   |          Test Logic
    }                       |      }
}                           |  }
----------------------------+-------------------------------------
 This is a common pattern   |  Everything that happens in a test,
    in application code     |       remains within the test!
----------------------------+-------------------------------------

- Setup and Teardown should be invoked from within the test.
- If a test fails, you should only have to look into the code
  within the failing test

<--------- code under test ---------->    \
                  ^                        \
                  |                         | Keep this distance minimum. Ideally next hop.
                  |                        /
<------------ test code ------------->    /

<--------- code under test ---------->    \
                  ^                        \
         calls something else               | Affects readability. Increases test code footprint
            calls something                /
<------------ test code ------------->    /

1. Test code nested through many calls can affect readability
2. Larger test code footprint -> More chances of bugs in test code
3. If distributed across multiple files, then fragmented test code
   affects readability further.

>> Simple vs Easy <<

testgoData
\__ Use of helper functions and their usage in tests

Data driven

Use of golden files

Setup     - Stuff you do before the test logic begins
Teardown  - Stuff you do after a test has PASSED or FAILED.
            The teardown will 'undo' what Setup did.

1. If you need to read/write to temp files on the filesystem
2. Talk to a database
3. Talk to a server over the network
4. Assemble a complex piece of testdata to test with
5. Test resilience or error handling in failure scenarios
etc.

func BuildSomethingComplex(<args>) <someType> {
    //
    //  Assemble dependencies,
    //  Generate randomized data, templates, etc
    //  specifically tuned as an input for testing
    //
    return <someType>
}

[1] chtmpdir
[2] Usage of chtmpdir in: TestFaccessat

func fixture(t *testing.T) func() {
    // setup
    if err != nil {
        t.Fatal(..errorMsg..)
    }
    return func() {
        // teardown
    }
}

func TestFunction(t *testing.T) {
    defer fixture(t)()
      ^      ^      ^
      |      |      +____ This () is for the returned teardown func()
      |      |
      |      +___________ Fixture does setup and returns a teardown func()
      |
      +__________________ Deferred: Hence, guaranteed execution after the
    ...                   TestFunction completes execution
}

func TestFunction(t *testing.T) {
    resource, teardown := fixture(t)
    defer teardown()
    //
    //  test code uses resource
    //
    ...
}

func TestFunction(t *testing.T) {
    strukt := fixture(t)        // returns a struct with extended functionality
    defer strukt.teardown()     // cleanup
    //
    //  strukt.<fields> and struct.<methods> get used in the test
    //
    ...
}

func LeakingFixture(t *testing.T) func() {
    var err error
    err = Step1()
    if err != nil { t.Fatalf("Failed Step 1") }
    err = Step2()
    if err != nil { t.Fatalf("Failed Step 2") }

    return func() { ..teardown.. }
}

1. Raise t.Fatal against the first state change causing code.
2. No more state change causing code must be part of that fixture.
3. A teardown func() would thus not have to run on t.Fatal as:
    - The error was caused while making the first state change
4. When the setup does succeed, the teardown concerns itself with
   reverting the one state change that succeeded.

func TestSomethingInIsolation(t *testing.T) func {
    defer requireContainer(t)()             // idempotent setup & teardown
    defer requireSystemTestConfig(t)()      // idempotent setup & teardown
    defer requireSwitchToContainer(t)()     // idempotent setup & teardown
    //
    //  subprocess go test cmd to re-run this test inside
    //  a container
    //
}

defer AyyoFixture(t)()
                     \__ Don't miss this