testing: document how to export unexported identifiers in *_test.go

[changkun]

While I am trying to introduce the usage of export_test.go to someone new to Go, I failed to find a document regarding this feature neither in testing nor in go command, not even in the wiki.

I am not sure if I overlooked somewhere, but I would propose documenting this somewhere more visible, such as the testing package's document.

[ianlancetaylor]

To me this sounds like something more for a blog post or a wiki page than the testing package documentation. The export_test.go approach follows from the way that cmd/go works.

[seankhliao]

From the cmd/go docs there is

Test files that declare a package with the suffix "_test" will be compiled as a separate package, and then linked and run with the main test binary.

[changkun]

The actual format may be different, I think the problem here is there is no official introduction about this, and if I search google export_test.go the source that introduces it is from a third-person blog.

I don't really remember how I learned that it is possible to use export_test.go with package pkg instead of package pkg_test to export internal objects of a package to test. Maybe the cmd/go docs mean in this way, but it is too obscure for a person to be aware of the special existence of export_test.go other than external_test.go.

[seankhliao]

I just realized, dup of #25223
it's on tip: https://pkg.go.dev/testing@master

[changkun]

It might have some overlaps with #25223, but I think my original intention for opening this issue is about the existence of export_test as a special case. The general *_test.go is something different.

[seankhliao]

It adds an entire section with examples on using an package abs_test.
Isn't that what this issue is about?

[changkun]

Oh, that's interesting. I thought for exporting purpose, internal members must use the special name export_test, but it seems can be any name:

$ cat a.go
package xxx

var a = 1

$ cat b_test.go
package xxx

var A = a

$ cat c_test.go
package xxx_test

import (
        "testing"

        "./xxx"
)

func TestXXX(t *testing.T) {
        t.Log(xxx.A)
}

The overall usage is a bit tricky because from the current doc f3a1f92

// ... and only its exported identifiers may be used.
// This is known as "black box" testing.

It is a bit hard to realize the mixture of two kinds of *_test files, where one is package xxx and the other is package xxx_test

[ianlancetaylor]

@seankhliao Thanks. @changkun Can we improve the comments there?

There is nothing special about "export_test.go". The way it behaves just follows from the rules about _test.go files and about the package name.

[gopherbot]

Change https://go.dev/cl/454335 mentions this issue: testing: document how to export unexported identifiers in *_test.go

[MartinKosicky]

I don't get it. I always get that "blablabla" is undeclared