Configuration
==============
`mockery init`
--------------
`mockery init [module_name]` is a useful command that can bootstrap you with a fully-functioning configuration set. For example, if we run:
``` title=""
$ mockery init github.com/vektra/mockery/v3/internal/fixtures
2025-03-14T23:06:12.535709000-05:00 INF writing to file file=.mockery.yml version=v0.0.0-dev
2025-03-14T23:06:12.536493000-05:00 INF done version=v0.0.0-dev
```
```yaml title=".mockery.yml"
all: false
dir: '{{.InterfaceDir}}'
filename: mocks_test.go
force-file-write: false
formatter: goimports
log-level: info
structname: '{{.Mock}}{{.InterfaceName}}'
pkgname: '{{.SrcPackageName}}'
recursive: false
template: testify
packages:
github.com/vektra/mockery/v3/internal/fixtures:
config:
all: true
```
We can then run mockery against this config to generate the code:
``` title=""
$ mockery
2025-03-14T23:42:17.014113000-05:00 INF Starting mockery config-file=/Users/landon/git/LandonTClipp/mockery/.mockery.yaml version=v0.0.0-dev
2025-03-14T23:42:17.014258000-05:00 INF Parsing configured packages... version=v0.0.0-dev
2025-03-14T23:42:17.527483000-05:00 INF Done parsing configured packages. version=v0.0.0-dev
[...]
2025-03-14T23:42:17.531239000-05:00 INF Executing template file=/Users/landon/git/LandonTClipp/mockery/internal/fixtures/mocks_test.go version=v0.0.0-dev
2025-03-14T23:42:17.690601000-05:00 INF Writing template to file file=/Users/landon/git/LandonTClipp/mockery/internal/fixtures/mocks_test.go version=v0.0.0-dev
```
```title=""
$ head -n 17 /Users/landon/git/LandonTClipp/mockery/internal/fixtures/mocks_test.go
// Code generated by mockery; DO NOT EDIT.
// github.com/vektra/mockery
package test
import (
"encoding/json"
"io"
"net/http"
"unsafe"
mock "github.com/stretchr/testify/mock"
http1 "github.com/vektra/mockery/v3/internal/fixtures/12345678/http"
"github.com/vektra/mockery/v3/internal/fixtures/constraints"
http0 "github.com/vektra/mockery/v3/internal/fixtures/http"
test "github.com/vektra/mockery/v3/internal/fixtures/redefined_type_b"
)
```
??? tip "Extended Example"
A more complex configuration example can be seen below:
```yaml
all: False
template-data:
boilerplate-file: ./path/to/boilerplate.txt
template: testify
packages:
github.com/vektra/example:
config:
# Make use of the template variables to place the mock in the same
# directory as the original interface.
dir: "{{.InterfaceDir}}"
filename: "mocks_test.go"
pkgname: "{{.PackageName}}_test"
structname: "{{.Mock}}{{.InterfaceName}}"
interfaces:
Foo:
Bar:
config:
# Make it unexported instead
structname: "mock{{.InterfaceName}}"
Baz:
# Create two mock implementations of Baz with different names.
configs:
- filename: "mocks_baz_one_test.go"
structname: "MockBazOne"
- filename: "mocks_baz_two_test.go"
structname: "MockBazTwo"
io:
config:
dir: path/to/io/mocks
filename: "mocks_io.go"
```
These are the highlights of the config scheme:
1. The parameters are merged hierarchically
2. There are a number of template variables available to generalize config values.
3. The style of mock to be generated is specified using the [`template`](template/index.md) parameter.
Parameter Descriptions
-----------------------
[](https://pkg.go.dev/github.com/vektra/mockery/v3/config#Config)
| name | templated | default | description |
|--------------------------------------------------------|---------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `all` | :fontawesome-solid-x: | `#!yaml false` | Generate all interfaces for the specified packages. |
| `_anchors` | :fontawesome-solid-x: | `#!yaml {}` | Unused by mockery, but allowed in the config schema so that you may define arbitrary yaml anchors. |
| `config` | :fontawesome-solid-x: | `#!yaml ""` | Set the location of the mockery config file. |
| `dir` | :fontawesome-solid-check: | `#!yaml "{{.InterfaceDir}}"` | The directory where the mock file will be outputted to. |
| `exclude-subpkg-regex` | :fontawesome-solid-x: | `#!yaml []` | A list of regular expressions that denote which subpackages should be excluded when `#!yaml recursive: true` |
| `exclude-interface-regex` | :fontawesome-solid-x: | `#!yaml ""` | When set along with `include-interface-regex`, then interfaces which match `include-interface-regex` but also match `exclude-interface-regex` will not be generated. If `all` is set, or if `include-interface-regex` is not set, then `exclude-interface-regex` has no effect. |
| `filename` | :fontawesome-solid-check: | `#!yaml "mocks_test.go"` | The name of the file the mock will reside in. Multiple interfaces from the same source package can be placed into the same output file. |
| `force-file-write` | :fontawesome-solid-x: | `#!yaml true` | When set to `#!yaml force-file-write: true`, mockery will forcibly overwrite any existing files. Otherwise, it will fail if the output file already exists. |
| `formatter` | :fontawesome-solid-x: | `#!yaml "goimports"` | The formatter to use on the rendered template. Choices are: `gofmt`, `goimports`, `noop`. |
| `formatter-options` | :fontawesome-solid-x: | `#!yaml nil` | Additional options for the formatter. See below. |
| `generate` | :fontawesome-solid-x: | `#!yaml true` | Can be used to selectively enable/disable generation of specific interfaces. See [the related docs](generate-directive.md) for more details. |
| [`include-auto-generated`](include-auto-generated.md){ data-preview } | :fontawesome-solid-x: | `#!yaml false` | When set to `true`, mockery will parse files that are auto-generated. This can only be specified in the top-level config or package-level config. |
| `include-interface-regex` | :fontawesome-solid-x: | `#!yaml ""` | When set, only interface names that match the expression will be generated. This setting is ignored if `all: True` is specified in the configuration. To further refine the interfaces generated, use `exclude-interface-regex`. |
| [`inpackage`](inpackage.md){ data-preview } | :fontawesome-solid-x: | `#!yaml nil` | When set, this overrides mockery's auto-detection logic when determining if the mock file is inside or outside of the mocked interface's package. |
| `log-level` | :fontawesome-solid-x: | `#!yaml "info"` | Set the level of the logger |
| `structname` | :fontawesome-solid-check: | `#!yaml "{{.Mock}}{{.InterfaceName}}"` | The name of the generated interface implementation. |
| `packages` | :fontawesome-solid-x: | `#!yaml null` | A dictionary containing configuration describing the packages and interfaces to generate mocks for. |
| `pkgname` | :fontawesome-solid-check: | `#!yaml "{{.SrcPackageName}}"` | The `#!go package name` given to the generated mock files. |
| `recursive` | :fontawesome-solid-x: | `#!yaml false` | When set to `true` on a particular package, mockery will recursively search for all sub-packages and inject those packages into the config map. |
| [`replace-type`](replace-type.md){ data-preview } | :fontawesome-solid-x: | `#!yaml {}` | Use this parameter to specify type replacements. |
| `build-tags` | :fontawesome-solid-x: | `#!yaml ""` | A space-separated list of additional build tags to load packages. |
| `require-template-schema-exists` | :fontawesome-solid-x: | `#!yaml true` | If set to `#!yaml true` and the schema failed to download, mockery will fail. Otherwise, mockery will not attempt to download the file nor do any schema validation. |
| `template` | :fontawesome-solid-x: | `#!yaml ""` | The template to use. The choices are defined in the [Templates](../template/) section. |
| `template-data` | :fontawesome-solid-x: | `#!yaml {}` | A `map[string]any` that provides arbitrary options to the template. Each template will have a different set of accepted keys. Refer to each template's documentation for more details. |
| `template-schema` | :fontawesome-solid-check: | `#!yaml "{{.Template}}.schema.json"` | The URL of the JSON schema to apply to the `template-data` parameter. See the [template docs](./template/index.md#schemas){ data-preview } for more details. |
The `formatter-options` field allows formatter-specific configuration. Currently goimports is supported. For
example:
```yaml title="mockery.yaml"
---
formatter: goimports
formatter-options:
goimports:
local-prefix: github.com/myrepo
tab-indent: true
```
Templates
---------
Parameters marked as being templated have access to a number of template variables and functions through the Go [`text/template`](https://pkg.go.dev/text/template#hdr-Examples) system.
### Variables
The variables provided are specified in the [`config.TemplateData`](https://pkg.go.dev/github.com/vektra/mockery/v3/config#TemplateData) struct.
### Functions
All of the functions defined in [`StringManipulationFuncs`](https://pkg.go.dev/github.com/vektra/mockery/v3/shared#pkg-variables) are available to templated parameters.
Config sources
--------------
Config can not only be specified from the `.yml` file, but also from CLI parameters (where available) and environment variables. For example, specifying a boolean value for a particular parameter called `enable-feature` from each config source would look like this:
| source | value |
|----------------------|------------------------------|
| command line | `--enable-feature=true` |
| Environment variable | `MOCKERY_ENABLE_FEATURE=True` |
| yaml | `#!yaml enable-feature: True` |
Config is loaded from each source in the following order:
1. Default values
2. Environment variables
3. Config file
4. CLI Parameters