moq/README.md

126 lines
3.7 KiB
Markdown
Raw Normal View History

![moq logo](moq-logo-small.png) [![build](https://github.com/matryer/moq/workflows/build/badge.svg)](https://github.com/matryer/moq/actions?query=branch%3Amaster) [![Go Report Card](https://goreportcard.com/badge/github.com/matryer/moq)](https://goreportcard.com/report/github.com/matryer/moq)
2016-08-30 14:00:43 +02:00
2016-08-29 14:25:35 +02:00
Interface mocking tool for go generate.
By [Mat Ryer](https://twitter.com/matryer) and [David Hernandez](https://github.com/dahernan), with ideas lovingly stolen from [Ernesto Jimenez](https://github.com/ernesto-jimenez).
2016-08-29 14:00:18 +02:00
2016-09-22 10:29:05 +02:00
### What is Moq?
2016-09-21 17:03:39 +02:00
Moq is a tool that generates a struct from any interface. The struct can be used in test code as a mock of the interface.
2016-10-14 11:59:38 +02:00
![Preview](preview.png)
above: Moq generates the code on the right.
2016-09-22 09:35:56 +02:00
2016-10-14 15:01:13 +02:00
You can read more in the [Meet Moq blog post](http://bit.ly/meetmoq).
2016-09-22 09:35:56 +02:00
### Installing
2016-09-22 10:29:05 +02:00
To start using Moq, just run go get:
2016-09-22 09:35:56 +02:00
```
$ go get github.com/matryer/moq
```
2016-08-30 14:00:43 +02:00
### Usage
2016-08-29 14:00:18 +02:00
2016-09-21 23:10:12 +02:00
```
moq [flags] source-dir interface [interface2 [interface3 [...]]]
2020-09-18 10:52:55 +02:00
-fmt string
go pretty-printer: gofmt, goimports or noop (default gofmt)
-out string
output file (default stdout)
-pkg string
package name (default will infer)
-stub
return zero values when no mock implementation is provided, do not panic
-skip-ensure
2020-09-18 10:53:31 +02:00
suppress mock implementation check, avoid import cycle if mocks
generated outside of the tested package
Specifying an alias for the mock is also supported with the format 'interface:alias'
2020-09-18 10:58:15 +02:00
Example: moq -pkg different . MyInterface:MyMock
2016-09-21 23:10:12 +02:00
```
**NOTE:** `source-dir` is the directory where the source code (definition) of the target interface is located.
It needs to be a path to a directory and not the import statement for a Go package.
2016-08-30 14:04:56 +02:00
In a command line:
2016-08-29 14:00:18 +02:00
```
2016-09-22 09:35:56 +02:00
$ moq -out mocks_test.go . MyInterface
2016-08-29 14:25:35 +02:00
```
2016-08-30 14:04:56 +02:00
In code (for go generate):
```go
package my
2016-09-21 23:07:00 +02:00
//go:generate moq -out myinterface_moq_test.go . MyInterface
2016-08-30 14:04:56 +02:00
type MyInterface interface {
Method1() error
Method2(i int)
}
```
Then run `go generate` for your package.
2016-08-30 14:00:43 +02:00
### How to use it
2016-08-29 14:30:24 +02:00
Mocking interfaces is a nice way to write unit tests where you can easily control the behaviour of the mocked object.
2016-08-29 14:31:32 +02:00
Moq creates a struct that has a function field for each method, which you can declare in your test code.
2019-11-03 08:54:11 +01:00
In this example, Moq generated the `EmailSenderMock` type:
2016-08-29 14:30:24 +02:00
```go
func TestCompleteSignup(t *testing.T) {
var sentTo string
2016-08-29 14:30:24 +02:00
2016-08-29 14:31:32 +02:00
mockedEmailSender = &EmailSenderMock{
2016-08-29 14:30:24 +02:00
SendFunc: func(to, subject, body string) error {
sentTo = to
return nil
},
}
CompleteSignUp("me@email.com", mockedEmailSender)
callsToSend := len(mockedEmailSender.SendCalls())
if callsToSend != 1 {
t.Errorf("Send was called %d times", callsToSend)
2016-08-29 14:30:24 +02:00
}
if sentTo != "me@email.com" {
t.Errorf("unexpected recipient: %s", sentTo)
}
}
2016-08-29 14:31:32 +02:00
func CompleteSignUp(to string, sender EmailSender) {
// TODO: this
}
2016-08-29 14:30:24 +02:00
```
2016-08-29 14:33:28 +02:00
The mocked structure implements the interface, where each method calls the associated function field.
## Tips
* Keep mocked logic inside the test that is using it
2017-07-07 15:49:48 +02:00
* Only mock the fields you need
* It will panic if a nil function gets called
2017-07-07 16:12:32 +02:00
* Name arguments in the interface for a better experience
2016-08-29 14:34:34 +02:00
* Use closured variables inside your test function to capture details about the calls to the methods
2017-07-11 22:30:08 +02:00
* Use `.MethodCalls()` to track the calls
2016-08-29 14:33:28 +02:00
* Use `go:generate` to invoke the `moq` command
* If Moq fails with a `go/format` error, it indicates the generated code was not valid.
You can run the same command with `-fmt noop` to print the generated source code without attempting to format it.
This can aid in debugging the root cause.
2016-09-01 11:30:27 +02:00
## License
2016-09-22 10:29:05 +02:00
The Moq project (and all code) is licensed under the [MIT License](LICENSE).
2016-09-01 11:30:27 +02:00
2016-09-22 10:29:05 +02:00
The Moq logo was created by [Chris Ryer](http://chrisryer.co.uk) and is licensed under the [Creative Commons Attribution 3.0 License](https://creativecommons.org/licenses/by/3.0/).