Goal of the testing
framework is to provide simple and efficient tools to for
writing effective unit and component tests in go
.
To accomplish this, the testing
framework contains a couple of opinionated
small extensions for testing, gomock
, and gock
to enable isolated, parallel, parameterized tests using a common pattern to
setup strongly validating mock request and response chains that work across
detached go
-routines and various error scenarios.
The core idea of the mock
/gock
packages is to provide a
short pragmatic domain language for defining mock requests with response that
enforce validation, while the test
package provides the building
blocks for test isolation.
type UnitParams struct {
mockSetup mock.SetupFunc
input*... *model.*
expect test.Expect
expect*... *model.*
expectError error
}
var testUnitParams = map[string]UnitParams {
"success" {
mockSetup: mock.Chain(
CallMockA(input..., output...),
...
test.Panic("failure message"),
),
...
expect: test.ExpectSuccess
}
}
func TestUnit(t *testing.T) {
test.Map(t, testParams).
Run(func(t test.Test, param UnitParams){
// Given
mocks := mock.NewMock(t).Expect(
param.mockSetup,
)
unit := NewUnitService(
mock.Get(mocks, NewServiceMock),
...
)
// When
result, err := unit.call(param.input*...)
mocks.Wait()
// Then
if param.expectError != nil {
assert.Equal(t, param.expectError, err)
} else {
require.NoError(t, err)
}
assert.Equal(t, param.expect*, result)
})
}
This opinionated test pattern supports a wide range of test in a standardized way.
Parameterized test are an efficient way to setup a high number of related test
cases cover the system under test in a black box mode from feature perspective.
With the right tools and concepts - as provided by this testing
framework,
parameterized test allow to cover all success and failure paths of a system
under test as outlined above.
Running tests in parallel make the feedback loop on failures faster, help to
detect failures from concurrent access and race conditions using go test -race
, that else only appear randomly in production, and foster a design with
clear responsibilities. This side-effects compensate for the small additional
effort needed to write parallel tests.
Test isolation is a precondition to have stable running test - especially run in parallel. Isolation must happen from input perspective, i.e. the outcome of a test must not be affected by any previous running test, but also from output perspective, i.e. it must not affect any later running test. This is often complicated since many tools, patterns, and practices break the test isolation (see requirements for parallel isolated tests.
Test are only meaningful, if they validate ensure pre-conditions and validate post-conditions sufficiently strict. Without validation test cannot ensure that the system under test behaves as expected - even with 100% code and branch coverage. As a consequence, a system may fail in unexpected ways in production.
Thus it is advised to validate mock input parameters for mocked requests and
to carefully define the order of mock requests and responses. The
mock
framework makes this approach as simple as possible, but it is
still the responsibility of the developer to setup the validation correctly.
The testing
framework consists of the following sub-packages:
-
test
provides a small framework to simply isolate the test execution and safely check whether a test fails or succeeds as expected in coordination with themock
package - even in if a system under test spans detachedgo
-routines. -
mock
provides the means to setup a simple chain or a complex network of expected mock calls with minimal effort. This makes it easy to extend the usual narrow range of mocking to larger components using a unified pattern. -
gock
provides a drop-in extension for Gock consisting of a controller and a mock storage that allows to run tests isolated. This allows to parallelize simple test and parameterized tests. -
perm
provides a small framework to simplify permutation tests, i.e. a consistent test set where conditions can be checked in all known orders with different outcome. This is very handy in combination withtest
to validated themock
framework, but may be useful in other cases too.
Please see the documentation of the sub-packages for more details.
Running tests in parallel not only makes test faster, but also helps to detect
race conditions that else randomly appear in production when running tests
with go test -race
.
Note: there are some general requirements for running test in parallel:
- Tests must not modify environment variables dynamically - utilize test specific configuration instead.
- Tests must not require reserved service ports and open listeners - setup services to acquire dynamic ports instead.
- Tests must not share files, folder and pipelines, e.g.
stdin
,stdout
, orstderr
- implement logic by using wrappers that can be redirected and mocked. - Tests must not share database schemas or tables, that are updated during execution of parallel tests - implement test to setup test specific database schemas.
- Tests must not share process resources, that are update during execution of parallel tests. Many frameworks make use of common global resources that make them unsuitable for parallel tests.
Examples for such shared resources in common frameworks are:
- Using of monkey patching to modify commonly used global functions,
e.g.
time.Now()
- implement access to these global functions using lambdas and interfaces to allow for mocking. - Using of
gock
to mock HTTP responses on transport level - make use of thegock
-controller provided by this framework. - Using the Gin HTTP web framework which uses a common
json
-parser setup instead of a service specific configuration. While this is not a huge deal, the repeated global setup creates race alerts. Instead usechi
that supports a service specific configuration.
With a careful design the general pattern provided above can be used to support parallel test execution.
This software is open source as is under the MIT license. If you start using the software, please give it a star, so that I know to be more careful with changes. If this project has more than 25 Stars, I will introduce semantic versions for changes.
This project is using go-make for building, which provides default implementations for most common tasks. Read the go-make manual for more information about how to build, test, lint, etc.
If you like to contribute, please create an issue and/or pull request with a proper description of your proposal or contribution. I will review it and provide feedback on it.