Add support for generating mocks for generic interfaces

[cruickshankpg]

Description

This adds support for generating mocks for generic interfaces. It does bump the go version to 1.18 so not sure how you want to handle this.

• Fixes mockery fails to generate mocks for interfaces that use generics #451

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Version of Golang used when building/testing:

• 1.11
• 1.12
• 1.13
• 1.14
• 1.15
• 1.16
• 1.17
• 1.18

How Has This Been Tested?

I've added unit tests for different types of generic interfaces, happy to add any others you think are worthwhile.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[LandonTClipp]

Thanks for the PR, this is looking great!

Semantic Versioning Discussion

This change could/will break anyone who is using go install to download mockery, or any installation method that requires compilation using a locally-installed go binary. However, we have had a note on the README here: https://github.com/vektra/mockery#semantic-versioning that says of our semantic versioning policy:

What the version does not track:

1. The interfaces, objects, methods etc. in the vektra/mockery package.
2. Compatibility of go get-ing mockery with new or old versions of Golang.

However I realize that in one of the installation methods listed is go install https://github.com/vektra/mockery#go-install and there is no note about this not being supported. This is obviously confusing and I fully anticipate unhappiness if we simply bump the minor version. So I apologize in advance for that confusion, and I will correct it for the future. In fact, I attempted to deprecate this previously but got a lot of push back. I should have stuck to my guns :)

We do clearly outline in the Semantic Versioning section of the README that semver won't be tracking any of the code in the mockery package, and that the only thing that is subject to semver are the CLI and the generated mocks. Because of this, I think that this update warrants only a minor version bump.

The reason why I'm really against a major version bump can be distilled to two reasons:

1. We have explicitly said we don't support go get/go install
2. Waiting for this to be bumped to v3 will delay its release for months, as we also had many other updates planned for v3. I think many people would find this unacceptable, as generics have been long anticipated.

I am opening this up for discussion from the community. Please share your thoughts, let's come to a consensus before solidifying it!

[LandonTClipp]

@cruickshankpg could you fix the merge conflicts?

[LandonTClipp]

I have a few comments on this. I have a few other thoughts that I will share in the coming days. Thanks again.

[LandonTClipp]

@cruickshankpg could you resolve the merge conflicts? Also the tests are (expectedly) failing, I will modify the PR builder as anything pre 1.18 will never pass now.

[cruickshankpg]

I'm hitting golang/go#51629 when manually running mockery agaIinst my own interfaces, I'm not entirely sure why I'm not hitting this in the unit tests. The fix hasn't been included in a release yet so I've pinned to the relevant sha of the fix.

[LandonTClipp]

Thanks for the update @cruickshankpg.

So I have thought about this for a while and I want to add a new release before this with an explicit deprecation notice in the logs for go install. I've added notes in the readme that this will break but I want to leave a deprecation notice out for possibly a month just to make it as clear as possible.

Sorry to delay this but I think this is the right way forward.

[slessard]

If not go install then how should one install this new version of Mockery? (Even an unsupported suggestion would be welcome.)

[LandonTClipp]

The only recommended/supported methods are:

1. Downloading the pre-built binaries
2. Using the docker image
3. Using homebrew

You can use go install/go get if you want, but there are two caveats here:

1. We will not support issues with this method going forward
2. You will have to keep your local Golang binary at a version greater than or equal to what's listed in our go.mod. As long as your go version is up to date, it will probably work most of the time. But please don't use it for production stuff as any time we add support for new language features, it will likely break your workflows.

[fastcat]

What about go run github.com/vektra/mockery/v2 ... esp. from within a //go:generate directive? That will always use the same version you have in your go.mod. It wastes a bit of linker time, but not much. It also avoids problems with different modules requiring different versions of this package's CLI to be installed somewhere "global".

[LandonTClipp]

@fastcat using any golang command that compiles the source code using a local go binary isn't supported. You are certainly free to use the command if you find it useful for your purposes but I strongly recommend against it.

Intrinsically, the issue is that we break semantic versioning if minor bumps might require people to upgrade their golang version. We could do major bumps any time we support a new language feature but that's a hassle and probably not the right path. Sure you can pin the mockery version but I certainly expect if we don't do it this way that people will express frustration that a simple minor bump broke their processes.

So ultimately, you can obviously do what you want, but just understand the caveats listed above. Officially, we will no longer support it, semantic versioning demands we don't. Realistically, you're free to tread at your own caution.

[guenhter]

@cruickshankpg go 1.18.2 was released yesterday. Maybe this solves golang/go#51629 for you and you can get rid of pinning the version. Worth a try I'd say.

[fastcat]

@LandonTClipp ok, thanks for clarifying what the risk/concern is. It wasn't clear before, and seemed like a go install or go run created binary might malfunction, which I have seen be a problem for other tools that have similar disclaimers! Having an open source tool that says "we don't support you compiling this tool from source, only us doing it" without further context is weird.

Pinning the version in my go.mod seems like it will avoid all these issues in my case -- there won't be any "surprises" unless I change it. And while I'm sure many others will disagree, my 2 cents is that I don't see a problem with "you need to update to a Go version released many months ago" as a problematic thing for a feature bump in a tool like this :)

[LandonTClipp]

I'll go ahead and merge this in the coming days and give the version a -beta.0 suffix. I'll release a non-beta tag after June 1st. @cruickshankpg could you rebase on master to confirm the tests work?

[cruickshankpg]

@cruickshankpg go 1.18.2 was released yesterday. Maybe this solves golang/go#51629 for you and you can get rid of pinning the version. Worth a try I'd say.

yep I'm not seeing it after upgrading to 1.18.2. I've removed the upgrade to an interim x/tools version

[ashyxz]

@cruickshankpg go 1.18.2 was released yesterday. Maybe this solves golang/go#51629 for you and you can get rid of pinning the version. Worth a try I'd say.

yep I'm not seeing it after upgrading to 1.18.2. I've removed the upgrade to an interim x/tools version

For anyone coming to this, I had to replace golang.org/x/tools => github.com/reillywatson/tools v0.1.10-0.20220322163840-50e5cab0be89 per this comment

[cruickshankpg]

Retested and I was still seeing Unexpected package creation during export data loading so have reinstated the pin to an interim x/tools version that contains the fix

[slessard]

The only recommended/supported methods are:

1. Downloading the pre-built binaries

Is there an easy link where I can always download the latest release similar to how go install github.com/vektra/mockery/v2@latest always gets the latest release?

[PH9]

I am using GitLab CI with go image. How use mockery on GitLab CI then?

When go image has no docker inside, and go image has no brew to install.

[mfrister]

@LandonTClipp

The only recommended/supported methods are:

1. Downloading the pre-built binaries
2. Using the docker image
3. Using homebrew

Unfortunately, no longer supporting go install means projects using mockery can no longer use tool versioning via a tools.go and go.mod, as proposed in the Go Wiki.

Versioning via go.mod has the benefit of automated dependency update tools like Renovate being able to automatically create MRs for tool updates.

Not being able to use go install then means having to make a decision between manually updating mockery (when installing pre-built binaries) and no longer using go generate ./... in CI jobs checking that all generated code is up-to-date (when using a separate CI job with the mockery Docker image that doesn't have the other tools installed).

I don't have a solution ready, but maybe this is an argument for looking for a better solution. I'd be ok with requiring an up-to-date Go version for the newest mockery versions, I'm just afraid that generally declaring go install as not supported may result in decisions that may break go install for other reasons than using an older Go versions in the future.

[LandonTClipp]

@mfrister Thank you for your views on the matter. I do know that many people are using go install and obviously I want this project to be as useful as possible to as many people as possible. Points like yours have been raised before when we previously tried to deprecate go install but the core issue is that I want to get ahead of people submitting tickets asking why mockery broke for them if/when we add new language features. If something breaks in a minor version bump then you've broken semantic versioning.

Practically, what I think I'm comfortable with doing, is having a gentleman's agreement where we will do our best to make sure that go install/get does work assuming you're on the latest go version. If there's ever a question about that you can link back to this comment. But from an official standpoint, we can't/shouldn't recommend people use go install. Our supported installation methods will always work no matter what environment you're on (minus any architectures/OSs we don't build for yet). Go install will not always work. So from a maintainer's perspective I think semantically it's the only logically consistent stance we can make. But as I said I'm willing to unofficially work with people to maintain its functioning, especially since it's a common and popular method.

People who still want to use go install despite our recommendations will have to understand these implications. Also realistically I don't ever foresee go install being completely broken especially if people submit PRs to maintain it. So, do with that as you may.

[LandonTClipp]

@slessard we can probably modify the asset names so that you can reference the latest URL. For instance currently you'd use a URL like:

https://github.com/vektra/mockery/releases/download/v2.12.3/mockery_2.12.3_Darwin_x86_64.tar.gz

But since the tar file has the version name it makes it hard to download the latest as the name will always change. So instead we could do something like:

https://github.com/vektra/mockery/releases/latest/mockery_Darwin_x86_64.tar.gz

How does that sound?

[slessard]

@slessard we can probably modify the asset names so that you can reference the latest URL. For instance currently you'd use a URL like:

https://github.com/vektra/mockery/releases/download/v2.12.3/mockery_2.12.3_Darwin_x86_64.tar.gz

But since the tar file has the version name it makes it hard to download the latest as the name will always change. So instead we could do something like:

https://github.com/vektra/mockery/releases/latest/mockery_Darwin_x86_64.tar.gz

How does that sound?

That is certainly a positive change. Also an apt-get package for certain linux distributions would be nice

[wspowell]

This change could/will break anyone who is using go install to download mockery, or any installation method that requires compilation using a locally-installed go binary.

This is proven false with your follow up response.

Intrinsically, the issue is that we break semantic versioning if minor bumps might require people to upgrade their golang version.

So it will work as long as the local golang binary matches at least the go.mod version.

For a project whose sole purpose is to closely follow a language spec and generate code based on that language's changes, I believe using semantic versioning as a reason for abandoning a core language design (go install) is extremely misguided. Semantic versioning is at the core of the argument to abandon go install support entirely because anyone bumping their minor version might have their workflows broken. And yet, while using this argument, are willing to break that contract for the go1.18 update.

Programming gets messy sometimes (a lot of times). For a project like this, I think it is acceptable to bump minor versions for new golang versions that contain minor breaking changes when the project is forced to in order to keep on producing correct mocks (otherwise, no go.mod change is necessary). When a major change like generics comes along, if there is any time to bump the major version this is it. While my statement is my own opinion, I believe Golang devs will understand and be willing to work with you on these aspects regarding semantic versioning since by definition you are not in complete control of how you can semantically version your project.

That being said, I urge you to remove the "official deprecation" label of go install on the project. A caveat can be added that states that a golang binary update might be required for minor revisions, if that helps. For those of us that rely on your project for work, it either forces us to abandon go install completely due to potentially instability (even though it sounds like it will work just fine) or potentially persuade devs to find alternatives, which would be difficult, or avoid the project in the first place. Either way, it shifts that burden onto the consumers of your project, which I find unacceptable inside golang's ecosystem.

[LandonTClipp]

Thanks for your insight @wspowell .

This is proven false with your follow up response.

I'm not sure I follow. It will break anyone who doesn't have an up-to-date Golang version installed. Yes it is corrected by updating your Golang version but intrinsically if we are requiring users to modify their environment to support updates to this project outside of major version bumps, we have broken semver. We could do major bumps as you say but I think that's a bit much. Maybe it is a personal preference. I prefer to introduce feature additions without breaking people where possible.

I believe using semantic versioning as a reason for abandoning a core language design (go install) is extremely misguided.

The stance I am taking is that officially we do not want to tell people to use go install for the reasons I've mentioned. I'm okay with placing a caveat that we will do our best to ensure go install works, but that users need to understand the implications for their workflows. Golang users are fairly capable folk so I'm not worried about that, I just don't want people to become upset that we broke their workflows because they are having to upgrade golang for a feature they might not even need.

And yet, while using this argument, are willing to break that contract for the go1.18 update.

We have already publicized that go install is not tracked in the semver for quite a long time in the readme. This has simply been the first time we've been forced to enforce it. The contract has already been "broken" for months/years.

or avoid the project in the first place

Certainly I want to avoid pushing you away :)

Either way, it shifts that burden onto the consumers of your project, which I find unacceptable inside golang's ecosystem.

There is a burden placed on the users either way. I'm simply picking a burden that I feel is in the best interest of semantic and logical correctness.

I do hear your concerns and I greatly appreciate your input. I'm amenable to the idea of perhaps not deprecating it entirely, but recommending people not to use it. And if folks want to use it, then I can point to our stance when they submit tickets asking why their workflows are broken.

[fastcat]

To me there are huge differences between:

1. go install may produce a binary that malfunctions
2. go install may produce a binary that generates source code that fails to compile with your version of go
3. go install may fail to compile a binary

Items (2) and (3) create very clear errors for the user. Something fails very clearly, and you either upgrade go or you downgrade mockery. And from what you've said, my inference is that (3) is the sole concern here, yes?

While I disagree with your stance on (not) requiring folks to update Go, I recognize it's something on which reasonable people may disagree 🙂. What I do ask is that the deprecation notice be made clear about the risks and reasons for why go install is discouraged. The existing notice and linked PR comment does not make clear what the risk is.

Absent that clarity, the current documentation reads as equivalent to "despite this being an open source project, we do not support users compiling it for themselves". That would be a very anti-open-source thing to say, and from the more detailed contents of this thread (as opposed to the one linked comment from the README), it's obviously not what you mean.

So, in the interest of staying positive & being helpful, some suggested wording that I think would clarify this:

If you choose to compile mockery from source, such as with go install, you may need to upgrade your environment to have at least the version of Go declared in this project's go.mod, even if you are creating mocks for an older version of Go. If your version of Go is at least that specified in this project's go.mod, then compiling mockery from source should produce a working binary, and the mocks it generates should be compatible with the version of Go used in your project, i.e. if the interfaces you are mocking work with a given version of Go, then the generated mocks should be compatible with that same version.

[irridia]

I tend to agree with @wspowell. The following is IMHO, and I do get that this particular ship has already sailed.

It feels like all of the issues discussed in this PR thread can be distilled down to the consequences of one decision: not wanting to use semantic versioning as intended because "it's a bit much". If you're releasing software that is no longer backwards-compatible, you increase the major version. This is widely understood, even assumed, and I would posit a critical foundation of modern software engineering. I agree bumping a major version just for this support is a lot, but it's the only answer that fixes more than it breaks.

While major version tagging is a bit hairy in go, I think it's safe to assume consumers (developers) now understand the tagging/versioning semantics of the go ecosystem more reliably than they will know the one-off decisions of arbitrary GitHub projects that could be direct or indirect dependencies on their work. And they would likely prefer to understand one integrated versioning and tooling mechanism than several potential mechanisms (binary, docker, etc) each with their own mockery-specific version choice caveats.

Removing guarantees of support for a foundational part of go tooling is a slippery slope (looking at you, golangci-lint), and the hesitance to call a spade a spade doesn't help.

I happen to use brew for this (which still uses go install, BTW), but if I had to use this tool in automation I would not feel comfortable with "downloading a binary at a pinned hash" or "setting up a new docker compose flow to integrate a pinned docker image". Using hardcoded versions isn't a responsible option to me—it again (see: slippery slope) defeats the purpose of semantic versioning. I'll also hand-wave at the security implications of this approach as an exercise left to the reader. ;)

[LandonTClipp]

Hi folks. I've thought about the above comments and based on the feedback everyone has provided, I will continue to support go install however we will do the following:

1. Strict recommendations not to use go install with clear descriptions as to why, and our motivations for not recommending it. I am even considering not showing it on the readme, but maybe somewhere in the wiki that people have to go searching for.
2. The semantic versioning will continue to not track go install for major breaking changes in v2. We continue to do this for v2 because it is what we've published for years, so we won't break that promise.
3. For v3 we will consider tracking go install in semver. Begrudgingly, I admit the points listed above that the golang community has certain expectations around go install that aren't generally common in other software ecosystems. But I think folks have made clear that this is something they want, so the people have spoken!

The deprecation notice will be removed in the coming days and I'll make the necessary changes to documentation. Thanks for the productive discussions everyone.

[nashikb]

Thanks for the points and followup!