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.

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

proposal: testing: define naming convention for test functions #33688

Open
taiidani opened this issue Aug 16, 2019 · 4 comments

Comments

@taiidani
Copy link

commented Aug 16, 2019

This proposal is for eliciting discussion around the current absent naming convention for test functions. This should not involve any changes to the language specification itself but instead serve as a guidepost for community tooling and best practices.

Background

There is precedent within the community and within the Go packages themselves to name test functions in a specific way based on their definitions. Two primary cases demonstrate this.

gotests

The popular gotests tool defines an informal specification for naming tests and uses it to auto-generate table driven tests from a given function definition. It appears to be widely accepted and used among the IDE community.

If accepted into the main specification, the IDE integrations using this tool could be further developed with additional features such as "Jump to Test for Function" / "Jump to Function for Test". Without a specification these features would be based upon an informal specification and subject to potential breakage if the community shifts to another upstream test generation tool.

(Disclaimer -- this issue came from a discussion on gotests: cweill/gotests#106)

testing examples

In the go source for the testing package a naming convention has already been defined for "Example" test cases. Extracting the content from those docs for clarity:

The naming convention to declare examples for the package, a function F, a type T and
method M on type T are:

func Example() { ... }
func ExampleF() { ... }
func ExampleT() { ... }
func ExampleT_M() { ... }

Multiple example functions for a package/type/function/method may be provided by
appending a distinct suffix to the name. The suffix must start with a
lower-case letter.

func Example_suffix() { ... }
func ExampleF_suffix() { ... }
func ExampleT_suffix() { ... }
func ExampleT_M_suffix() { ... }

Having a naming convention for Example test functions gives a solid starting point if we decide to move forward for a standard Test function.

Proposal

I would stop short of officially recommending a naming convention for Go to adopt, but encourage that the discussion start based on the existing examples we are seeing in gotests and in the Example function naming conventions. Looking forward to what everyone thinks!

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

commented Aug 16, 2019

Seems reasonable to me but it's not clear what would actually change in the Go project. Are you suggesting that we add some comments to the testing package doc explaining that the format used for example names should also be used for test names?

@taiidani

This comment has been minimized.

Copy link
Author

commented Aug 16, 2019

Yes, that's the suggestion -- a documentation update that implies convention.

At the moment the docs are not (to me at least) indicating that they apply to both Tests and Examples. Maybe my interpretation was incorrect? Do they actually already apply to both types?

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

commented Aug 16, 2019

The naming conventions only apply to examples, because the naming of examples affects the way that godoc presents the package documentation. Test names do not affect godoc, as godoc doesn't do anything about tests.

@taiidani

This comment has been minimized.

Copy link
Author

commented Aug 17, 2019

Ah, that makes a lot of sense! The tooling for godoc required that a specification be formed around Examples in order to accurately parse the source and generate documentation from it.

That's very similar to what's happening on the community side with gotests. They were auto-generating tests from source code and needed a clear specification for their tooling to handle developers' function definitions. From the original discussion:

It was a solution to the fact that in Golang you can have a function called Foo and foo in the same package or on the same struct. So if you generated a test for both, they would have identical test names.

@bcmills bcmills changed the title proposal: define naming convention for tests proposal: testing: define naming convention for test functions Aug 19, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.