github.com/Capventis/moq@v0.2.6-0.20220316100624-05dd47497214/README.md (about)

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