github.com/moitias/moq@v0.0.0-20240223074357-5eb0f0ba4054/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  ```
    20  $ go install github.com/matryer/moq@latest
    21  ```
    22  
    23  Note that Go 1.18+ is needed for installing from source. For using Moq with
    24  older Go versions, use the pre-built binaries published with 
    25  [Moq releases](https://github.com/matryer/moq/releases). 
    26  
    27  ### Usage
    28  
    29  ```
    30  moq [flags] source-dir interface [interface2 [interface3 [...]]]
    31    -fmt string
    32      	go pretty-printer: gofmt, goimports or noop (default gofmt)
    33    -out string
    34      	output file (default stdout)
    35    -pkg string
    36      	package name (default will infer)
    37    -rm
    38      	first remove output file, if it exists
    39    -skip-ensure
    40      	suppress mock implementation check, avoid import cycle if mocks generated outside of the tested package
    41    -stub
    42      	return zero values when no mock implementation is provided, do not panic
    43    -version
    44      	show the version for moq
    45    -with-resets
    46      	generate functions to facilitate resetting calls made to a mock
    47  
    48  Specifying an alias for the mock is also supported with the format 'interface:alias'
    49  
    50  Ex: moq -pkg different . MyInterface:MyMock
    51  ```
    52  
    53  **NOTE:** `source-dir` is the directory where the source code (definition) of the target interface is located.
    54  It needs to be a path to a directory and not the import statement for a Go package.
    55  
    56  In a command line:
    57  
    58  ```
    59  $ moq -out mocks_test.go . MyInterface
    60  ```
    61  
    62  In code (for go generate):
    63  
    64  ```go
    65  package my
    66  
    67  //go:generate moq -out myinterface_moq_test.go . MyInterface
    68  
    69  type MyInterface interface {
    70  	Method1() error
    71  	Method2(i int)
    72  }
    73  ```
    74  
    75  Then run `go generate` for your package.
    76  
    77  ### How to use it
    78  
    79  Mocking interfaces is a nice way to write unit tests where you can easily control the behaviour of the mocked object.
    80  
    81  Moq creates a struct that has a function field for each method, which you can declare in your test code.
    82  
    83  In this example, Moq generated the `EmailSenderMock` type:
    84  
    85  ```go
    86  func TestCompleteSignup(t *testing.T) {
    87  
    88  	var sentTo string
    89  
    90  	mockedEmailSender = &EmailSenderMock{
    91  		SendFunc: func(to, subject, body string) error {
    92  			sentTo = to
    93  			return nil
    94  		},
    95  	}
    96  
    97  	CompleteSignUp("me@email.com", mockedEmailSender)
    98  
    99  	callsToSend := len(mockedEmailSender.SendCalls())
   100  	if callsToSend != 1 {
   101  		t.Errorf("Send was called %d times", callsToSend)
   102  	}
   103  	if sentTo != "me@email.com" {
   104  		t.Errorf("unexpected recipient: %s", sentTo)
   105  	}
   106  
   107  }
   108  
   109  func CompleteSignUp(to string, sender EmailSender) {
   110  	// TODO: this
   111  }
   112  ```
   113  
   114  The mocked structure implements the interface, where each method calls the associated function field.
   115  
   116  ## Tips
   117  
   118  * Keep mocked logic inside the test that is using it
   119  * Only mock the fields you need
   120  * It will panic if a nil function gets called
   121  * Name arguments in the interface for a better experience
   122  * Use closured variables inside your test function to capture details about the calls to the methods
   123  * Use `.MethodCalls()` to track the calls
   124  * Use `.ResetCalls()` to reset calls within an invidual mock's context
   125  * Use `go:generate` to invoke the `moq` command
   126  * If Moq fails with a `go/format` error, it indicates the generated code was not valid.
   127    You can run the same command with `-fmt noop` to print the generated source code without attempting to format it.
   128    This can aid in debugging the root cause.
   129  
   130  ## License
   131  
   132  The Moq project (and all code) is licensed under the [MIT License](LICENSE).
   133  
   134  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.
   135  
   136  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/).
   137