Interoperability with gomock

[nfx]

This PR addresses two major issues

• mockgen cannot yet mock higher-level wrappers, like *AndWait because of generics are not yet supported by gomock: Mockgen: Support generating mock for interfaces with generics golang/mock#621
• fundamentally fixes Split high-level generated interface from low-level direct API mapping #87

Interoperability with gomock

When developing large applications, you find yourself in need of mocking APIs. For Go, there's gomock framework for code generating testing mocks. In this small example, we'll show how to use gomock with Databricks SDK for Go.

Please read through dbfs_test.go test example.

Declaring which mocks to generate

//go:generate go run github.com/golang/mock/mockgen@latest -package=mocks -destination=mocks/dbfs.go github.com/databricks/databricks-sdk-go/service/dbfs DbfsService

• go run github.com/golang/mock/mockgen@latest downloads and executes the latest version of mockgen command
• -package=mocks instructs to generate mocks in the mocks package
• -destination=mocks/dbfs.go instructs to create dbfs.go file with mock stubs.
• github.com/databricks/databricks-sdk-go/service/dbfs tells which Databricks package to look services in.
• DbfsService tells which services to generate mocks for.

Initializing gomock

Every test needs the following preamble:

ctrl := gomock.NewController(t)
defer ctrl.Finish()

Mocking individual methods with gomock

Every actual method call must be mocked for the test to pass:

mockDbfs := mocks.NewMockDbfsService(ctrl)
mockDbfs.EXPECT().Create(gomock.Any(), gomock.Eq(dbfs.Create{
    Path:      "/a/b/c",
    Overwrite: true,
})).Return(&dbfs.CreateResponse{
    Handle: 123,
}, nil)

Testing idioms with Databricks SDK for Go

You can stub out the auth with the databricks.NewMockConfig(nil) helper function. Every service has a public property with the name of the service plus Service suffix. You have to manually set the stubs for every service that is called in unit tests.

w := workspaces.New(databricks.NewMockConfig(nil))
w.Dbfs.DbfsService = mockDbfs

Running this example

1. Run go mod tidy in this folder to create go.sum file to pick dependency versions.
2. Run go mod vendor to download dependencies into vendor/ directory.
3. Run go generate ./... to create mocks/ directory.
4. Run go test ./... to invoke tests with mocks.

[nfx]

Pros:

"SDK Features" and "low level" clients are physically separated, that allows for mocking.

Risks

It isn't easy to read godoc, and, subsequently, pkg.go.dev documentation - the place, where developers go for documentation. In this example, methods get hidden

[nfx]

though, generating dummy proxy methods like this one does solve the documentation issue:

[pietern]

Not for this PR: the stuttering here can/should be removed: CreateNetworkConfig -> Create

[nfx]

there are certain risks with it, like "automatic name clashes" - I'll see if it's possible

[pietern]

WithImpl -> SetImpl, "with" implies its scoped somehow (same as #167)