diff --git a/.github/workflows/go.yaml b/.github/workflows/go.yaml index 800f191..b8a3ac6 100644 --- a/.github/workflows/go.yaml +++ b/.github/workflows/go.yaml @@ -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: diff --git a/mock/README.md b/mock/README.md index f0f97f2..2a31a87 100644 --- a/mock/README.md +++ b/mock/README.md @@ -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 @@ -252,4 +253,5 @@ for more information on requirements in parallel parameterized tests. [gomock]: +[gomock-rep]: [gock]: diff --git a/mock/mock.go b/mock/mock.go index e01fd0c..49a267c 100644 --- a/mock/mock.go +++ b/mock/mock.go @@ -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 @@ -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 @@ -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 ) @@ -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), @@ -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] @@ -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. @@ -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 { @@ -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. // @@ -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. @@ -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 { @@ -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 { @@ -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 { @@ -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", diff --git a/perm/perm.go b/perm/perm.go index a3126fa..175a6b4 100644 --- a/perm/perm.go +++ b/perm/perm.go @@ -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) {