I am currently writing ExampleFuncs in my Go test scripts. For example:
package hello
import "testing"
func ExampleGetSymbol() {
data := GetSymbol("AAPL")
fmt.Println(len(data.Data))
// Output: 21
}
Now, this gives me two benefits:
This example is executed when I am running go test and
It appears in the godoc documentation under func GetSymbol
One thing bothers me and I am wondering if there is anything I should do about it.
For the user that's trying to learn from this example, the line
data := GetSymbol("AAPL")
should actually be
data := hello.GetSymbol("AAPL")
but since the test is in the same scope as the package, I cannot use it like this.
So I guess the distilled version of my question would be:
Is there a way to allow package.field notation inside the package scope?
Thanks in advance
Rather than putting this in package hello, put it in package hello_test. You're allowed to have both hello and hello_test packages in the same directory, and it allows (requires) you to create your examples the way you're suggesting.
Incidentally, this also causes you to write your test cases (at least for this file) only to the public API. This is often a good thing. But if you need to write to private functions, you can split your tests into separate files, some in the hello package and some in hello_test.
BTW, documentation for this is slightly buried. You can find it in the "Test packages" section of the go cmd documentation.
Related
There's a lot of examples in test code that are shadowing package names in test libraries like testify.
For example:
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestSomething(t *testing.T) {
assert := assert.New(t)
require := require.New(t)
var a string = "Hello"
var b string = "Hello"
assert.Equal(a, b, "The two words should be the same.")
}
Shouldn't it be an explicit decision and rare occurrence to override the value of a package namespace with a local variable?
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestSomething(t *testing.T) {
assertions := assert.New(t)
req := require.New(t)
var a string = "Hello"
var b string = "Hello"
assert.Equal(a, b, "The two words should be the same.")
}
I'd expect the proper behavior to be aliasing the package like pkgassert which I doesn't feel idiomatic, or ensuring that variables are not set to the same name as the package: assertions := assert.New(t).
Other examples:
Ok: buf := bytes.Buffer{}
Bad: bytes := bytes.Buffer{}
Note: I'm not focused on variable naming patterns, as Go tends to recommend single letter, or short variables in the narrowed scope you might use the buffer for. Assume the longer name is acceptable and desired due to the function length.
If this is a desired behavior in testing packages I'd like to know why?
It appears to violate a key principle of idiomatic Go in "no magic" and being readable.
If there are undesired side effects from this I'd like to know of that as well.
My assumption is that is means after import that any calls to the package in the same scope wouldn't work due to variable shadowing
Edit
Scope Shadowing in Go was a nice read and gave some great points on usage. The main takeaway I had from this and from Stack commenters:
It can enhance readability. (I think this is probably due to Go preferring small concise naming for packages, making package names in Go variable length.)
Parallel Test Issues was something I recall reading a while back. I didn't understand the recommendation to "hide" the loop variable by putting in:
for _, tc := range tests {
tc := tc
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
// Here you test tc.value against a test function.
// Let's use t.Log as our test function :-)
t.Log(tc.value)
})
}
}
With a better understanding of shadowing, I'm seeing this "hiding" was talking about shadowing the caller scope variable of tc by assigning inside the loop, thereby shadowing.
This seems like a good use case, though I still feel it is being "clever" rather if not commented, and violates the idiomatic Go goals of being clear and readable with no "magic".
After reviewing all the feedback and writing I've seen I'm going to summarize the findings here.
If you are investigating this behavior after seeing Go linting alerts from a tool like Goland, hopefully this answer will save you same time and make clear that it's ok, idiomatic, and only in some cases of reusing the actual package calls after initializing would any issues be experienced.
Shadowing Package Names With Local Variables
This is a matter of opinion, there is no official statement indicating this is considered non-idiomatic code.
Opinions seem to overall lean towards avoiding shadowing unless intentionally done for clarity & readability, but this is again opinion, not a requirement.
Once overridden, the package would be unavailable in that scope as the package name has been shadowed by the local variable.
I've observed that this behavior seems more likely in Go than some languages, because Go prompts package names that are short, not multi-word, and easy to type. It seems inevitable that assert := assert.New(t) could result when this happens.
Consistency, as always in matters like this, is the key. If a team determines to never shadow the package name, then assertions := assert.New(t) could be used, or as mentioned the package could be aliased such as import tassert "github.com/stretchr/testify/assert". This is an opinion standard, and either way is legal and considered idiomatic.
In the case of testing, this is commonly done as further usage of the package after the initial variable set isn't used further. Example below using the is is package. Package author comment on this (again this is opinionated, but it doesn't break anything to use it with is := is.New(t).
package package_test
import (
"testing"
"package"
iz "github.com/matryer/is"
)
func TestFuncName(t *testing.T) {
is := iz.New(t)
got := FuncName()
want := ""
is.Equal(got,want) // AssertMessage
}
Shadowing Behavior Can Address Goroutine Variable Issues
Shadowing is a known behavior and documented clearly in Effective Go.
The bug is that in a Go for loop, the loop variable is reused for each iteration, so the req variable is shared across all goroutines. That's not what we want.
It may seem odd to write req := req but it's legal and idiomatic in Go to do this. You get a fresh version of the variable with the same name, deliberately shadowing the loop variable locally but unique to each goroutine.
This can be solved without shadowing by passing in the variable as a parameter into the embedded func as well, simplifying the code. Both are legal and considered idiomatic per the guide.
Shadowing for Tests
Related to this goroutine behavior, but in the context of a testing, parallel tests run in goroutines, and therefore benefit from this pattern as well.
The tc := tc statement is required in the parallel test example because the closure runs in a goroutine. More generally, the tc := tc idiom used in the context of closures where the closure can be executed after the start of the next loop iteration - credit #gopher in comments
The gist on Be Careful With Table Driven Tests mentions this behavior as well in the How To Solve This.
Detecting
The check go vet can check for shadowing, but is not considered part of the stable package, and was removed here related to GitHub Issue 29260 and GitHub Issue 34053.
The change seems to have been prompted for compatibility purposes due to the requirement of unsafeptr flag. Additional comments seem to point towards also requiring better heuristics before allowing in go vet without being experimental.
Go Vet Shadow
Instructions on running via go vet: Package Variables With Instructions:
go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow
go vet -vettool=$(which shadow)
For those wanting to lint this, golangci-lint does have an option to configure shadowing checks in the configuration (search for check-shadowing as no bookmark to that text block`.
Further Reading
Scope and Shadowing in Go
Scopes and Closures
Wow, that is awful code. While it might not be a compiler enforced rule, if I see this:
import "github.com/stretchr/testify/assert"
Then in that file, as far as I'm concerned, any identifier spelled assert is the top level import from that package, period. Anyone who breaks that pattern, in the name of being "clever" or whatever, is just asking for trouble. People's muscle memory is trained to recognize top level imports, so please, do not do stuff like this. If you want to avoid thinking of a new name, just remove some letters:
asrt := assert.New(t)
or add a letter:
nAssert := assert.New(t)
or alias the import:
import tAssert "github.com/stretchr/testify/assert"
Just please, do not follow the poor example given in that code.
I need to call multiple constants found in another go project, already run the command
go install
and create the executable but I don't know how to import it into the project where I need it
You're going to want to read up on go modules pretty extensively - they're used everywhere in the go environment nowadays, and a very important concept to grasp.
Once you feel comfortable with that, if this code you speak of is not in module form yet, you'll need to make it that way. After that, the constants you need will need to be exported (i.e capitalized variable names) like this:
package mymath
// unexported variable - local scope only
var pi = 3.14159265
// exported variable - global scope when in a module
var Pi = 3.14159265
Now, you can call mymath.Pi to get that constant value.
go get project-github-or-smthelse-which-routes-to-source-code
TL;DR:
Do test written within a package end up in the final exported package? Do they add any garbage or weight to a compiled binary?
Longer version:
Let's say that I have a foo Go package:
pkg/
foo/
bar.go
bar_test.go
I'm aware of the black box vs white box approaches to testing in go. A short recap is that I can either:
have bar_test.go declare a foo_test package, or
have it part of the main foo package.
Approach 1 provides better isolation because it allows to focus on the public API of the package, as one only access the exported identifiers of foo. Also, when application code imports the foo package with import "pkg/foo", only the files containing the main foo package are compiled. That's nice. [1]
However, there are cases where putting the tests in foo is a convenient compromise. I don't particularly like it myself, but I can see it in several codebases and I understand why at times it's necessary.
My question is about what happens to these tests. Since they're part of the package foo, when foo is imported somewhere, I'd expect the tests to be brought along. Or is the compiler smart enough to strip them?
[1] this is not a question on what approach is "better". It's doesn't really matter. Please abstain from commenting with "that approach is not better".
Yes, the Go tool is smart enough not to pass them to the compiler.
https://github.com/golang/go/issues/10184
By analogy with this question about tags I note that there are several uses of comments in go beyond pure commentary.
Examples:
go:generate can be used for code generation.
godoc uses the function name to indicate comments it should interpret
build constraints
Are there any others I've missed?
Is there a definitive list somewhere?
Some third party packages like gocontracts and go-swagger use them as well. How can they avoid conflicting with each other?
As noted comments are directives in go not just comments.
There is at the time of writing no definitive list.
This as logged as an golang issue 28532.
Therefore I propose using this answer to make one.
Uses in the go core language and tools themselves:
go:generate can be used for code generation.
godoc uses the function name to indicate comments it should interpret
Examples - document the expected output of a test (thanks #Butuzov)
build constraints (starting with '// +build')
Import comments e.g. 'package math // import "path"'
Notable uses in third party packages
gocontracts - specify preconditions as comments
go-swagger - document a ReST API using swagger
golangci e.g. //nolint[:linter1,linter2,...]
How can they avoid conflicting with each other?
If you are developing a tool that really needs to treat comments as attributes and wish to avoid conflict with other similar uses prefix your comments with a namespace like "{mytool}: "
There are some conscious attempts at namespacing.
Magic comments built into go use the "go: " prefix as in "go:generate"
(except where they don't)
go-swagger uses "swagger: "
However you still need to approach this with caution and check the list here or any other source you can find.
Also consider whether comments are the best or only approach rather than using functions instead.
Compare for instance (gocontracts):
// SomeFunc ensures:
// * !strings.HasSuffix(result, "smth")
func SomeFunc(x int) (result string) {
// ...
}
with (godbc)
func SomeFunc(x int) (result string) {
godbc.Require(strings.HasSuffix(result,"smth");
}
Examples - Allow to test function for example output.
Copy/Paste from link above.
package stringutil_test
import (
"fmt"
"github.com/golang/example/stringutil"
)
func ExampleReverse() {
fmt.Println(stringutil.Reverse("hello"))
// Output: olleh
}
I've project done in C++ where I used #define macros to give a name of the project, which I used in several places, I don't change this name often but sometimes I may need to change this, then I change this macro and rebuild my code. Now I'm converting this code to Go. Can someone suggest me how to implement this in Go? I'm not interested in using global variables for this purpose because I've many such macros and I doubt this cause my project to occupy more cpu and effect the performance.
Luckily, Go does not support macros.
There are two venues in Go to implement what is done using macros
in other programming languages:
"Meta-programming" is done using code generation.
"Magic variables/constants" are implemented using "symbol substitutions"
at link time.
It appears, the latter is what you're after.
Unfortunately, the help on this feature is nearly undiscoverable
on itself, but it explained in the output of
$ go tool link -help
To cite the relevant bit from it:
-X definition
add string value definition of the form importpath.name=value
So you roll like this:
In any package, where it is convenient,
you define a string constant the value of which you'd like to change at build time.
Let's say, you define constant Bar in package foo.
You pass a special flag to the go build or go install invocation for the linking phase at compile time:
$ go install -ldflags='-X foo.Bar="my super cool string"'
As the result, the produced binary will have the constant foo.Bar
set to the value "my super cool string" in its "read-only data" segment,
and that value will be used by the program's code.
See also the go help build output about the -ldflags option.
Go doesn't support Macros.
but you can use a constants inside a package and refer it where ever you need.
package constant
// constants.go file
const (
ProjectName = "My Project"
Title = "Awesome Title"
)
and in your program
package main
import "<path to project>/constant" // replace the path to project with your path from GOPATH
func main() {
fmt.Println(constant.ProjectName)
}
The project structure would be
project
|- constant
| |- constants.go
|-main.go