Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarification/simplification of packages documentation #592

Merged
merged 2 commits into from
Apr 6, 2023
Merged

Clarification/simplification of packages documentation #592

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bc9cb3
Clarification/simplification of `packages` documentation
LandonTClipp Apr 6, 2023
48a20c3
fix tests for defaults
LandonTClipp Apr 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
82 changes: 66 additions & 16 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,19 +32,69 @@ mockery will search upwards from your current-working-directory up to the root p
Parameter Descriptions
-----------------------

| name | description |
|------|-------------|
| `name` | The `name` option takes either the name or matching regular expression of the interface to generate mock(s) for. |
| `all` | It's common for a big package to have a lot of interfaces, so mockery provides `all`. This option will tell mockery to scan all files under the directory named by `--dir` ("." by default) and generates mocks for any interfaces it finds. This option implies `recursive: True`. |
| `recursive` | Use the `recursive` option to search subdirectories for the interface(s). This option is only compatible with `name`. The `all` option implies `recursive: True`. |
| `output` | mockery always generates files with the package `mocks` to keep things clean and simple. You can control which mocks directory is used by using `output`, which defaults to `./mocks`. |
|`outpkg`| Use `outpkg` to specify the package name of the generated mocks.|
| `inpackage` and `keeptree` | For some complex repositories, there could be multiple interfaces with the same name but in different packages. In that case, `inpackage` allows generating the mocked interfaces directly in the package that it mocks. In the case you don't want to generate the mocks into the package but want to keep a similar structure, use the option `keeptree`. |
| `filename` | Use the `filename` and `structname` to override the default generated file and struct name. These options are only compatible with non-regular expressions in `name`, where only one mock is generated. |
| `case` | mockery generates files using the casing of the original interface name. This can be modified by specifying `case: underscore` to format the generated file name using underscore casing. |
| `print` | Use `print: True` to have the resulting code printed out instead of written to disk. |
| `exported` | Use `exported: True` to generate public mocks for private interfaces. |
| `with-expecter` | Use `with-expecter: True` to generate `EXPECT()` methods for your mocks. This is the preferred way to setup your mocks. |
| `testonly` | Prepend every mock file with `_test.go`. This is useful in cases where you are generating mocks `inpackage` but don't want the mocks to be visible to code outside of tests. |
| `inpackage-suffix` | When `inpackage-suffix` is set to `True`, mock files are suffixed with `_mock` instead of being prefixed with `mock_` for InPackage mocks |
| `replace-type source=destination` | Replaces aliases, packages and/or types during generation.|
=== "non-`packages` config"

### non-`packages`


#### Config Variables
These are the configuration options when not using the [`packages`](/mockery/features/#packages-configuration) config

| name | description |
|------|-------------|
| `name` | The `name` option takes either the name or matching regular expression of the interface to generate mock(s) for. |
| `all` | It's common for a big package to have a lot of interfaces, so mockery provides `all`. This option will tell mockery to scan all files under the directory named by `--dir` ("." by default) and generates mocks for any interfaces it finds. This option implies `recursive: True`. |
| `recursive` | Use the `recursive` option to search subdirectories for the interface(s). This option is only compatible with `name`. The `all` option implies `recursive: True`. |
| `output` | mockery always generates files with the package `mocks` to keep things clean and simple. You can control which mocks directory is used by using `output`, which defaults to `./mocks`. |
|`outpkg`| Use `outpkg` to specify the package name of the generated mocks.|
| `inpackage` and `keeptree` | For some complex repositories, there could be multiple interfaces with the same name but in different packages. In that case, `inpackage` allows generating the mocked interfaces directly in the package that it mocks. In the case you don't want to generate the mocks into the package but want to keep a similar structure, use the option `keeptree`. |
| `filename` | Use the `filename` and `structname` to override the default generated file and struct name. These options are only compatible with non-regular expressions in `name`, where only one mock is generated. |
| `case` | mockery generates files using the casing of the original interface name. This can be modified by specifying `case: underscore` to format the generated file name using underscore casing. |
| `print` | Use `print: True` to have the resulting code printed out instead of written to disk. |
| `exported` | Use `exported: True` to generate public mocks for private interfaces. |
| `with-expecter` | Use `with-expecter: True` to generate `EXPECT()` methods for your mocks. This is the preferred way to setup your mocks. |
| `testonly` | Prepend every mock file with `_test.go`. This is useful in cases where you are generating mocks `inpackage` but don't want the mocks to be visible to code outside of tests. |
| `inpackage-suffix` | When `inpackage-suffix` is set to `True`, mock files are suffixed with `_mock` instead of being prefixed with `mock_` for InPackage mocks |
| `replace-type source=destination` | Replaces aliases, packages and/or types during generation.|

=== "`packages` config"

### [`packages` config](/mockery/features/#packages-configuration)

These are the config options when using the `packages` config option. Config variables may have changed meanings or have been substracted entirely, compared to the non-`packages` config.

#### Config Variables

| name | templated | default | description |
|------|-----------|---------|-------------|
| `all` | :octicons-x-16: | `#!yaml false` | Generate all interfaces for the specified packages. |
| `tags` | :octicons-x-16: | `#!yaml ""` | Set the build tags of the generated mocks. |
| `config` | :octicons-x-16: | `#!yaml ""` | Set the location of the mockery config file. |
| `dir` | :material-check: | `#!yaml "mocks/{{.PackagePath}}"` | The directory where the mock file will be outputted to. |
| `disable-config-search` | :octicons-x-16: | `#!yaml false` | Disable searching for configuration files |
| `disable-version-string` | :octicons-x-16: | `#!yaml false` | Disable the version string in the generated mock files. |
| `dry-run` | :octicons-x-16: | `#!yaml false` | Print the actions that would be taken, but don't perform the actions. |
| `filename` | :material-check: | `#!yaml "mock_{{.InterfaceName}}.go"` | The name of the file the mock will reside in. |
| `inpackage` | :octicons-x-16: | `#!yaml false` | When generating mocks alongside the original interfaces, you must specify `inpackage: True` to inform mockery that the mock is being placed in the same package as the original interface. |
| `mockname` | :material-check: | `#!yaml "Mock{{.InterfaceName}}"` | The name of the generated mock. |
| `outpkg` | :material-check: | `#!yaml "{{.PackageName}}"` | Use `outpkg` to specify the package name of the generated mocks. |
| `log-level` | :octicons-x-16: | `#!yaml "info"` | Set the level of the logger |
| [`packages`](/mockery/features/#packages-configuration) | :octicons-x-16: | `#!yaml null` | A dictionary containing configuration describing the packages and interfaces to generate mocks for. |
| `print` | :octicons-x-16: | `#!yaml false` | Use `print: True` to have the resulting code printed out instead of written to disk. |
| [`with-expecter`](/mockery/features/#expecter-structs) | :octicons-x-16: | `#!yaml true` | Use `with-expecter: True` to generate `EXPECT()` methods for your mocks. This is the preferred way to setup your mocks. |
| [`replace-type`](/mockery/features/#replace-types) | :octicons-x-16: | `#!yaml null` | Replaces aliases, packages and/or types during generation.|

#### Template variables

Variables that are marked as being templated are capable of using mockery-provided template parameters.

| name | description |
|------|-------------|
| InterfaceDir | The path of the original interface being mocked. This can be used as `#!yaml dir: "{{.InterfaceDir}}"` to place your mocks adjacent to the original interface. This should not be used for external interfaces. |
| InterfaceName | The name of the original interface being mocked |
| InterfaceNameCamel | Converts a string `interface_name` to `InterfaceName` |
| InterfaceNameLowerCamel | Converts `InterfaceName` to `interfaceName` |
| InterfaceNameSnake | Converts `InterfaceName` to `interface_name` |
| MockName | The name of the mock that will be generated. Note that this is simply the `mockname` configuration variable |
| PackageName | The name of the package from the original interface |
| PackagePath | The fully qualified package path of the original interface |
31 changes: 5 additions & 26 deletions docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,11 +141,12 @@ packages:

### Templated variables

Included with this feature is the ability to use templated strings for various configuration options. This is useful to define where your mocks are placed and how to name them.

These are various layouts you may want to adopt:
Included with this feature is the ability to use templated strings for various configuration options. This is useful to define where your mocks are placed and how to name them. You can view the template variables available in the [Configuration](/mockery/configuration/#parameter-descriptions) section of the docs, under the `packages config` tab.


#### Layouts
### Layouts

Using different configuration parameters, we can deploy our mocks on-disk in various ways. These are some common layouts:

!!! info "layouts"

Expand Down Expand Up @@ -235,28 +236,6 @@ These are various layouts you may want to adopt:
mock.Mock
}
```




#### Template Variable Descriptions

The template variables available for your use are:

| name | description |
|------|-------------|
| InterfaceDir | The path of the original interface being mocked. This can be used as `#!yaml dir: "{{.InterfaceDir}}"` to place your mocks adjacent to the original interface. This should not be used for external interfaces. |
| InterfaceName | The name of the original interface being mocked |
| InterfaceNameCamel | Converts a string `interface_name` to `InterfaceName` |
| InterfaceNameLowerCamel | Converts `InterfaceName` to `interfaceName` |
| InterfaceNameSnake | Converts `InterfaceName` to `interface_name` |
| MockName | The name of the mock that will be generated. Note that this is simply the `mockname` configuration variable |
| PackageName | The name of the package from the original interface |
| PackagePath | The fully qualified package path of the original interface |


!!! warning
Many of the config options when using `packages` have either changed meanings or are no longer used. It's recommended to delete all previous configuration you have as their meanings may have changed.

Mock Constructors
-----------------
Expand Down
6 changes: 3 additions & 3 deletions docs/notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ func TestFoo(t *testing.T) {

This introduces ambiguities because if you want to do something like this:

```
```go
m.On("Bar", mock.Anything).Return(nil)
```

Expand All @@ -69,13 +69,13 @@ This is impossible to distinguish between these two intentions:

This is fixed in https://github.com/vektra/mockery/pull/359 where you can provide `unroll-variadic: False` to get back to the old behavior. Thus, if you want to assert the first case, you can then do:

```
```go
m.On("Bar", mock.Anything).Return(nil)
```

If you want to specify the second case, you must set `unroll-variadic: True`. Then this assertion's intention will be modified to mean the second case:

```
```go
m.On("Bar", mock.Anything).Return(nil)
```

Expand Down
3 changes: 3 additions & 0 deletions pkg/config/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,9 @@ func NewConfigFromViper(v *viper.Viper) (*Config, error) {
v.SetDefault("filename", "mock_{{.InterfaceName}}.go")
v.SetDefault("mockname", "Mock{{.InterfaceName}}")
v.SetDefault("outpkg", "{{.PackageName}}")
v.SetDefault("with-expecter", true)
v.SetDefault("dry-run", false)
v.SetDefault("log-level", "info")
}

if err := v.UnmarshalExact(c); err != nil {
Expand Down
20 changes: 12 additions & 8 deletions pkg/config/config_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -591,10 +591,12 @@ packages:
github.com/vektra/mockery/v2/pkg:
`,
want: &Config{
Dir: "mocks/{{.PackagePath}}",
FileName: "mock_{{.InterfaceName}}.go",
MockName: "Mock{{.InterfaceName}}",
Outpkg: "{{.PackageName}}",
Dir: "mocks/{{.PackagePath}}",
FileName: "mock_{{.InterfaceName}}.go",
MockName: "Mock{{.InterfaceName}}",
Outpkg: "{{.PackageName}}",
WithExpecter: true,
LogLevel: "info",
},
},
{
Expand All @@ -606,10 +608,12 @@ packages:
github.com/vektra/mockery/v2/pkg:
`,
want: &Config{
Dir: "barfoo",
FileName: "foobar.go",
MockName: "Mock{{.InterfaceName}}",
Outpkg: "{{.PackageName}}",
Dir: "barfoo",
FileName: "foobar.go",
MockName: "Mock{{.InterfaceName}}",
Outpkg: "{{.PackageName}}",
WithExpecter: true,
LogLevel: "info",
},
},
}
Expand Down