Skip to content

Commit

Permalink
feat: update docs (#48)
Browse files Browse the repository at this point in the history
  • Loading branch information
tkrop committed Jul 2, 2023
1 parent 44c2bd4 commit 76e9202
Show file tree
Hide file tree
Showing 4 changed files with 79 additions and 60 deletions.
7 changes: 5 additions & 2 deletions .github/workflows/go.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,11 @@ jobs:
- name: Build and tests
env:
CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
run: make all --trace

run: make --trace all

# - name: Release and publish
# run: make --trace release publish

- name: Send coverage report
uses: shogo82148/actions-goveralls@v1
with:
Expand Down
4 changes: 3 additions & 1 deletion mock/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,8 @@ func SetupUnit(

**Note:** The `mock.Get(mocks, NewServiceMock)` is the standard pattern to
request a new or existing mock instance from the mock controller. As input, any
test interface or entity compatible with the `gomock.TestReporter` can be used.
test interface or entity compatible with the [`gomock.TestReporter`][gomock-rep]
can be used.


## Generic mock call setup
Expand Down Expand Up @@ -252,4 +253,5 @@ for more information on requirements in parallel parameterized tests.


[gomock]: <https://github.com/golang/mock>
[gomock-rep]: <https://github.com/golang/mock/blob/v1.6.0/gomock/controller.go#L65>
[gock]: <https://github.com/h2non/gock>
124 changes: 69 additions & 55 deletions mock/mock.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const (
// Head mode to detach head, i.e. do not order mock calls after predecessor
// mock calls provided via context.
Head DetachMode = 1
// Tail mode to deteach tail, i.e. do not order mock calls before successor
// Tail mode to detach tail, i.e. do not order mock calls before successor
// mock calls provided via context.
Tail DetachMode = 2
// Both mode to detach tail and head, i.e. do neither order mock calls after
Expand All @@ -48,9 +48,9 @@ func (m DetachMode) String() string {
}

type (
// Call alias for `gomock.Call`.
// Call alias for [gomock.Call].
Call = gomock.Call
// Controller alias for `gomock.Controller`.
// Controller alias for [gomock.Controller].
Controller = gomock.Controller

// chain is the type to signal that mock calls must and will be orders in a
Expand All @@ -66,7 +66,7 @@ type (
// will be detached from its successor.
detachTail any
// detachBoth is the type to signal that the mock call must and will be
// deteched from its predecessor as well as from its successor.
// detached from its predecessor as well as from its successor.
detachBoth any
)

Expand All @@ -83,7 +83,8 @@ type Mocks struct {
mocks map[reflect.Type]any
}

// NewMocks creates a new mock handler using given test reporter (`*testing.T`).
// NewMocks creates a new mock handler using given test reporter, e.g.
// [*testing.T], or [test.Test].
func NewMocks(t gomock.TestReporter) *Mocks {
return (&Mocks{
Ctrl: gomock.NewController(t),
Expand All @@ -93,8 +94,8 @@ func NewMocks(t gomock.TestReporter) *Mocks {
}

// Get resolves the singleton mock from the mock handler by providing the
// constructor function generated by `gomock` to create a new mock. The mock
// is only created once and stored in an internal creator to mock map.
// constructor function generated by [gomock] to create a new mock. The mock is
// only created once and stored in an internal creator function to mock map.
func (mocks *Mocks) Get(creator func(*Controller) any) any {
ctype := reflect.TypeOf(creator)
mock, ok := mocks.mocks[ctype]
Expand All @@ -114,7 +115,7 @@ func (mocks *Mocks) Expect(fncalls SetupFunc) *Mocks {
return mocks
}

// syncWith used to synchronize the waitgroup of the mock setup with the wait
// syncWith used to synchronize the wait group of the mock setup with the wait
// group of the given test reporter. This function is called automatically on
// mock creation and therefore does not need to be called on the same reporter
// again.
Expand All @@ -125,85 +126,98 @@ func (mocks *Mocks) syncWith(t gomock.TestReporter) *Mocks {
return mocks
}

// Wait waits for all mock calls registered via `mocks.Times(<#>)` to be
// consumed before testing continuing. This method implements the `WaitGroup`
// interface to support testing of detached `go-routines` in an isolated
// [test](../test) environment.
// Wait waits for all mock calls registered via [Call], [Do], [Return],
// [Panic], and [Times] to be consumed before testing can continue. This method
// implements the [sync.WaitGroup] interface to support testing of detached
// *goroutines* in an isolated [test](../test) environment.
func (mocks *Mocks) Wait() {
mocks.wg.Wait()
}

// Add adds the given delta on the waiting group handling the expected or
// consumed mock calls. This method implements the `WaitGroup` interface to
// support testing of detached `go-routines` in an isolated [test](../test)
// environment.
// Add adds the given delta on the wait group to register the expected or
// notify the consumed mock calls. This method implements the [sync.WaitGroup]
// interface to support testing of detached *goroutines* in an isolated
// [test](../test) environment.
//
// Deprecated: `Call`, `Do`, `Return`, and `Panic` are automatically register
// and notify call consumption, thus these extra calls are not necessary any
// longer.
// **Note:** Usually call expectation setup is completely handled via `Call`,
// `Do`, `Return`, and `Panic`. Use this method only for synchronizing tests
// *goroutines*.
func (mocks *Mocks) Add(delta int) int {
mocks.wg.Add(delta)
return delta
}

// Done removes exactly one expected mock call from the wait group handling the
// expected or consumed mock calls. This method implements the `WaitGroup`
// interface to support testing of detached `go-routines` in an isolated
// [test](../test) environment.
// Done removes exactly one expected mock call from the wait group to notify
// a consumed mock call. This method implements the [sync.WaitGroup] interface
// to support testing of detached `go-routines` in an isolated [test](../test)
// environment.
//
// Deprecated: `Call`, `Do`, `Return`, and `Panic` are automatically register
// and notify call consumption, thus these extra calls are not necessary any
// longer.
// **Note:** Usually call expectation setup is completely handled via `Call`,
// `Do`, `Return`, and `Panic`. Use this method only for synchronizing tests
// *goroutines*.
func (mocks *Mocks) Done() {
mocks.wg.Done()
}

// Times is creating the expectation that exactly the given number of mock call
// are consumed. This call is best provided as input for `Times` in combination
// with `Call`, `Do`, `Return`, and `Panic` considering that these will add one
// additional expected call.
// are consumed. This call is supposed to be used as input for [gomock.Times]
// in combination with [Call], [Do], [Return], and [Panic]. Setting up [Times]
// is considering that these methods add one expected call by reducing the
// registration by one.
func (mocks *Mocks) Times(num int) int {
mocks.wg.Add(num - 1)
return num
}

// Call is a convenience method providing a notification function for `Do` or
// `DoAndReturn` to signal that a mock call setup was consumed returning the
// executing the given call back function and returning its result. This method
// registers exactly one expected call.
// Call is a convenience method to setup a call back function for [gomock.Do]
// and [gomock.DoAndReturn]. Using this method signals an expected mock call
// during setup as well as a consumed mock call when executing the given call
// back function. The function is supplied with the regular call parameters and
// expected to return the mock result - if required, as [gomock.Do] ignores
// arguments.
//
// **Note:** Call registers exactly one expected call automatically.
func (mocks *Mocks) Call(fn any, call func(...any) []any) any {
return mocks.notify(fn, call)
}

// Do is a convenience method providing a notification function for `Do` or
// `DoAndReturn` to signal that a mock call setup was consumed returning the
// given arguments as result - if available. This method registers exactly one
// expected call.
// Do is a convenience method to setup a call back function for [gomock.Do]
// or [gomock.DoAndReturn]. Using this method signals an expected mock call
// during setup as well as a consumed mock call when executing the given call
// back function returning the given optional arguments as mock result - if
// necessary, as [gomock.Do] ignores arguments.
//
// **Note:** Do registers exactly one expected call automatically.
func (mocks *Mocks) Do(fn any, args ...any) any {
return mocks.notify(fn, nil, args...)
}

// Return is a convenience method providing a notification function for `Do` or
// `DoAndReturn` to signal that a mock call setup was consumed returning the
// given arguments as result - if available. This method registers exactly one
// expected call.
// Return is a convenience method to setup a call back function for [gomock.Do]
// or [gomock.DoAndReturn]. Using this method signals an expected mock call
// during setup as well as a consumed mock call when executing the given call
// back function returning the given optional arguments as mock result - if
// necessary, as [gomock.Do] ignores arguments.
//
// Deprecated: use shorter 'Do' method.
// **Note:** Return registers exactly one expected call automatically.
func (mocks *Mocks) Return(fn any, args ...any) any {
return mocks.notify(fn, nil, args...)
}

// Panic is a convenience method providing a notification function for `Do` or
// `DoAndReturn` to signal that a mock call setup was consumed while panicing
// with given reason. This method registers exactly one expected call.
// Panic is a convenience method to setup a call back function that panics with
// given reason for [gomock.Do] or [gomock.DoAndReturn]. Using this method
// signals an expected mock call during setup as well as a consumed mock call
// when executing the given call back function.
//
// **Note:** Return registers exactly one expected call automatically.
func (mocks *Mocks) Panic(fn any, reason any) any {
return mocks.notify(fn, func(...any) []any { panic(reason) })
}

// notify is a generic method for providing a customized notification function
// of the given function call type with given custom call behavior and given
// return arguments for usage in `Do` or `DoAndReturn`. The method registers
// exactly one expected call.
// return arguments for usage in [gomock.Do] or `[gomock.DoAndReturn]. When
// notify is called, it registers exactly one expected service call that is
// consumed, when the created call back function is called.
func (mocks *Mocks) notify(
fn any, call func(...any) []any, args ...any,
) any {
Expand Down Expand Up @@ -299,8 +313,8 @@ func Chain(fncalls ...func(*Mocks) any) func(*Mocks) any {
}

// Parallel creates a set of parallel set of mock calls that is validated by
// `gomock`. While the parallel setup provids some freedom, this still defines
// constrainst with repect to parent and child setup methods, e.g. when setting
// `gomock`. While the parallel setup provides some freedom, this still defines
// constraints with respect to parent and child setup methods, e.g. when setting
// up parallel chains in a chain, each parallel chains needs to follow the last
// mock call and finish before the following mock call.
//
Expand Down Expand Up @@ -338,7 +352,7 @@ func Detach(mode DetachMode, fncall func(*Mocks) any) func(*Mocks) any {
}

// Sub returns the sub slice of mock calls starting at index `from` up to index
// `to` inclduing. A negative value is used to calculate an index from the end
// `to` including. A negative value is used to calculate an index from the end
// of the slice. If the index of `from` is higher as the index `to`, the
// indexes are automatically switched. The returned sub slice of mock calls
// keeps its original semantic.
Expand Down Expand Up @@ -370,7 +384,7 @@ func Sub(from, to int, fncall func(*Mocks) any) func(*Mocks) any {
}

// GetSubSlice returns the sub slice of mock calls starting at index `from`
// up to index `to` inclduing. A negative value is used to calculate an index
// up to index `to` including. A negative value is used to calculate an index
// from the end of the slice. If the index `from` is after the index `to`, the
// indexes are automatically switched.
func GetSubSlice[T any](from, to int, calls []T) any {
Expand Down Expand Up @@ -451,8 +465,8 @@ func inOrder(anchors []*Call, call any) []*Call {
}
}

// inOrderCall creates an order for the given mock call using the given achors
// as predecessor and resturn the call as next anchor.
// inOrderCall creates an order for the given mock call using the given anchors
// as predecessor and return the call as next anchor.
func inOrderCall(anchors []*Call, call *Call) []*Call {
if len(anchors) != 0 {
for _, anchor := range anchors {
Expand Down Expand Up @@ -504,7 +518,7 @@ func inOrderDetachHead(anchors []*Call, calls []detachHead) []*Call {
}

// inOrderDetachTail creates a tail detached set of mock calls using the
// anchors as predessors but without adding the mock calls as next anchors.
// anchors as predecessors but without adding the mock calls as next anchors.
// The provided anchors are provided as next anchors.
func inOrderDetachTail(anchors []*Call, calls []detachTail) []*Call {
for _, call := range calls {
Expand All @@ -521,7 +535,7 @@ var (
ErrModeNotSupprted = errors.New("mode not supported")
)

// NewErrNoCall creates an error with given call type to panic on inorrect
// NewErrNoCall creates an error with given call type to panic on incorrect
// call type.
func NewErrNoCall(call any) error {
return fmt.Errorf("%w [type: %v] must be *gomock.Call",
Expand Down
4 changes: 2 additions & 2 deletions perm/perm.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,14 +63,14 @@ func (p *Test) Test(t test.Test, perm []string, expect test.Expect) {
}

// Remain calculate and add the missing permutations and add it with
// expected result to the given permmutation map.
// expected result to the given permutation map.
func (perms ExpectMap) Remain(expect test.Expect) ExpectMap {
cperms := ExpectMap{}
for key, value := range perms {
cperms[key] = value
}

// we only need to permutate the first key.
// we only need to permute the first key.
for key := range cperms {
slices.PermuteDo(strings.Split(key, "-"),
func(perm []string) {
Expand Down

0 comments on commit 76e9202

Please sign in to comment.