github.com/rancher/moq@v0.0.0-20200712062324-13d1f37d2d77/README.md (about)

     1  ![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)
     2  
     3  Interface mocking tool for go generate.
     4  
     5  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).
     6  
     7  ### What is Moq?
     8  
     9  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.
    10  
    11  ![Preview](preview.png)
    12  
    13  above: Moq generates the code on the right.
    14  
    15  You can read more in the [Meet Moq blog post](http://bit.ly/meetmoq).
    16  
    17  ### Installing
    18  
    19  To start using Moq, just run go get:
    20  ```
    21  $ go get github.com/matryer/moq
    22  ```
    23  
    24  ### Usage
    25  
    26  ```
    27  moq [flags] source-dir interface [interface2 [interface3 [...]]]
    28    -fmt string
    29  	go pretty-printer: gofmt (default) or goimports
    30    -out string
    31      	output file (default stdout)
    32    -pkg string
    33      	package name (default will infer)
    34  Specifying an alias for the mock is also supported with the format 'interface:alias'
    35  Ex: moq -pkg different . MyInterface:MyMock
    36  ```
    37  
    38  **NOTE:** `source-dir` is the directory where the source code (definition) of the target interface is located. 
    39  It needs to be a path to a directory and not the import statement for a Go package.
    40  
    41  In a command line:
    42  
    43  ```
    44  $ moq -out mocks_test.go . MyInterface
    45  ```
    46  
    47  In code (for go generate):
    48  
    49  ```go
    50  package my
    51  
    52  //go:generate moq -out myinterface_moq_test.go . MyInterface
    53  
    54  type MyInterface interface {
    55  	Method1() error
    56  	Method2(i int)
    57  }
    58  ```
    59  
    60  Then run `go generate` for your package.
    61  
    62  ### How to use it
    63  
    64  Mocking interfaces is a nice way to write unit tests where you can easily control the behaviour of the mocked object.
    65  
    66  Moq creates a struct that has a function field for each method, which you can declare in your test code.
    67  
    68  In this example, Moq generated the `EmailSenderMock` type:
    69  
    70  ```go
    71  func TestCompleteSignup(t *testing.T) {
    72  
    73  	var sentTo string
    74  
    75  	mockedEmailSender = &EmailSenderMock{
    76  		SendFunc: func(to, subject, body string) error {
    77  			sentTo = to
    78  			return nil
    79  		},
    80  	}
    81  
    82  	CompleteSignUp("me@email.com", mockedEmailSender)
    83  
    84  	callsToSend := len(mockedEmailSender.SendCalls())
    85  	if callsToSend != 1 {
    86  		t.Errorf("Send was called %d times", callsToSend)
    87  	}
    88  	if sentTo != "me@email.com" {
    89  		t.Errorf("unexpected recipient: %s", sentTo)
    90  	}
    91  
    92  }
    93  
    94  func CompleteSignUp(to string, sender EmailSender) {
    95  	// TODO: this
    96  }
    97  ```
    98  
    99  The mocked structure implements the interface, where each method calls the associated function field.
   100  
   101  ## Tips
   102  
   103  * Keep mocked logic inside the test that is using it
   104  * Only mock the fields you need
   105  * It will panic if a nil function gets called
   106  * Name arguments in the interface for a better experience
   107  * Use closured variables inside your test function to capture details about the calls to the methods
   108  * Use `.MethodCalls()` to track the calls
   109  * Use `go:generate` to invoke the `moq` command
   110  
   111  ## License
   112  
   113  The Moq project (and all code) is licensed under the [MIT License](LICENSE).
   114  
   115  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/).