Skip to content
Go Interface Mocking Tool
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github update .gitignore, codeowners, and .editorconfig Oct 10, 2017
sbin add circleci config and codecov Oct 10, 2017
vendor add vendor "" Nov 28, 2017
.editorconfig update .gitignore, codeowners, and .editorconfig Oct 10, 2017
.gitignore update git ignores Nov 13, 2017
Gopkg.lock add vendor "" Nov 28, 2017
Gopkg.toml add vendor "" Nov 28, 2017
LICENSE Create LICENSE Oct 10, 2017
Makefile support function and map parameter types Nov 30, 2017 Merge branch master Jun 18, 2018
endtoend_test.go update test infrastructure to work with new test data location Nov 29, 2017
generator.go Merge branch master Jun 18, 2018
golden_test.go Merge branch master Jun 18, 2018
importer18.go initial commit Oct 9, 2017
main.go misspell Jun 18, 2018
model.go fix typo Jun 19, 2018
template.go Merge branch master Jun 18, 2018


Circle CI BSD Go Report Card

Percolate's Go Interface Mocking Tool. Please read our introductory blog post.


go get


  charlatan [options] <interface> ...
  charlatan -h | --help


  -dir string
        input package directory [default: current package directory]
  -file value
        name of input file, may be repeated, ignored if -dir is present
  -output string
        output file path [default: ./charlatan.go]
  -package string
        output package name [default: "<current package>"]

If you would like the mock implementations to live in the same package as the interface definition then use the simplest invocation as a directive:

//go:generate charlatan Interface

or from the command line:

charlatan -file=path/to/file.go Interface

You can chose the output path using -output, which must include the name of the generated source file. Any intermediate directories in the path that don't exist will be created. The package used in the generated file's package directive can be set using -package.


Given the following interface:

package example

//go:generate charlatan Service

type Service interface {
	Query(filter *QueryFilter) ([]*Thing, error)
	Fetch(id string) (*Thing, error)

Running go generate ... for the above package/file should produce the file charlatan.go:

package example

type QueryInvocation struct {
	Parameters struct {
		Filter *QueryFilter
	Results struct {
		Ident1 []*Thing
		Ident2 error

type FetchInvocation struct {
	Parameters struct {
		Id string
	Results struct {
		Ident3 *Thing
		Ident4 error

type FakeService struct {
	QueryHook func(*QueryFilter) ([]*Thing, error)
	FetchHook func(string) (*Thing, error)

	QueryCalls []*QueryInvocation
	FetchCalls []*FetchInvocation

func (f *FakeService) Query(filter *QueryFilter) (id1 []*Thing, id2 error) {
	invocation := new(QueryInvocation)
	invocation.Parameters.Filter = filter

	id1, id2 := f.QueryHook(filter)

	invocation.Results.Ident1 = id1
	invocation.Results.Ident2 = id2


// other generated code elided ...

Now you can use this in your tests by injecting the FakeService implementation instead of the actual one. A FakeService can be used anywhere a Service interface is expected.

func TestUsingService(t *testing.T) {
	// expectedThings := ...
	// expectedCriteria := ...
	svc := &example.FakeService{
		QueryHook: func(filter *QueryFilter) ([]*Thing, error) {
			if filter.Criteria != expectedCriteria {
				t.Errorf("expected criteria value: %v, have: %v", filter.Criteria, expectedCriteria)
				return nil, errors.New("unexpected criteria")
			return expectedThings, nil

	// use the `svc` instance in the code under test ...

	// assert state of FakeService ...

Create anonymous function implementations for only those interface methods that should be called in the code under test. This will force a panic if any unexpected calls are made to the mock implementation.

The generated code has godoc formatted comments explaining the use of the mock and its methods.

You can’t perform that action at this time.