moq/README.md

108 lines
2.9 KiB
Markdown
Raw Normal View History

2016-11-06 13:36:57 +01:00
![moq logo](moq-logo-small.png) [![Build Status](https://travis-ci.org/matryer/moq.svg?branch=master)](https://travis-ci.org/matryer/moq) [![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] destination interface [interface2 [interface3 [...]]]
-out string
output file (default stdout)
-pkg string
package name (default will infer)
```
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.
This 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: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)
2017-07-07 15:49:48 +02:00
if mockedEmailSender.CallsTo.Send != 1 {
t.Errorf("Send was called %d times", mockedEmailSender.CallsTo.Send)
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-07 15:49:48 +02:00
* Use `.CallsTo.Method` to track the calls
2016-08-29 14:33:28 +02:00
* Use `go:generate` to invoke the `moq` command
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/).