testaroli

Package testaroli allows to monkey patch Go test binary, e.g. override functions and methods with stubs/mocks to simplify unit testing. It can be used only for unit testing and never in production.

Platforms suported

This package modifies actual executable at runtime, therefore is OS- and CPU arch-specific.

OS/arch combinations:

	x86_64	ARM64
Linux	Supported	Supported
Windows	Supported	-
macOS	Supported	Supported

Command line options

It is recommended to switch off compiler optimisations and disable function inlining using -gcflags="all=-N -l" CLI option when running tests, like this:

go test -gcflags="all=-N -l" ./...

Typical use:

import . "github.com/qrdl/testaroli"

// you want to test function foo() which in turn calls function bar(), so you
// override function bar() to check whether it is called with correct argument
// and to return predefined result

func foo() error {
    ...
    if err := bar(baz); err != nil {
        return err
    }
    ...
}

func bar(baz int) error {
    ...
}

func TestBarFailing(t *testing.T) {
    Override(TestingContext(t), bar, Once, func(a int) error {
        Expectation().CheckArgs(a)  // <-- arg value checked here
        return ErrInvalid
    })(42) // <-- expected argument value

    err := foo()
    if !errors.Is(err, ErrInvalid) {
        t.Errorf("unexpected %v", err)
    }
    it err = ExpectationsWereMet(); err != nil {
        t.Error(err)
    }
}

It is also possible to override functions and methods in other packages, including ones from standard library, like in example below. Please note that method receiver becomes the first argument of the mock function.

func TestFoo(t *testing.T) {
    Override(TestingContext(t), (*os.File).Read, Once, func(f *os.File, b []byte) (n int, err error) {
        Expectation()
        copy(b, []byte("foo"))
        return 3, nil
    })

    f, _ := os.Open("test.file")
    defer f.Close()
    buf := make([]byte, 3)
    n, _ := f.Read(buf)
    if n != 3 || string(buf) != "foo" {
        t.Errorf("unexpected file content %s", string(buf))
    }
    if err = ExpectationsWereMet(); err != nil {
        t.Error(err)
    }
}

See more advanced usage examples in examples directory.