testing: document how to place tests in a _test package

[kisielk]

The current testing package documentation states:

"These TestXxx routines should be declared within the package they are
testing."

There's no mention of the commonly used technique of creating a file with 

package foo_test

instead of 

package foo

for blackbox or example purposes.

[davecheney]

Comment 1:

I reckon it's yours for the taking if you feel like it.

Labels changed: added priority-later, go1.1maybe, suggested, removed priority-triage.

[kisielk]

Comment 2:

I'm willing to, but I'm not sure about the specifics of how the mechanism works.
Does the package name need to end in _test? It seems so, since otherwise go build and go
test complain about multiple packages in the directory.
Any other subtleties I should be aware of?

[davecheney]

Comment 3:

> Does the package name need to end in _test? It seems so, since otherwise go build and
go test complain about multiple packages in the directory.
Yes. It's actually codified in cmd/go/test.go +420, and doc.go +343. These fields are
can be inspected by go list, 
    lucky(~) % go list -f '{{ .TestGoFiles }}' bytes
    [export_test.go]
    lucky(~) % go list -f '{{ .XTestGoFiles }}' bytes
    [buffer_test.go bytes_test.go example_test.go reader_test.go]
But you are correct that package $PKG_test is special. 
> Any other subtleties I should be aware of?
Watch out for the duplication test.go has a description of the command which is part of
the go help output, but doc.go has the godoc string, those two need to be kept in sync.

Status changed to Accepted.

[robpike]

Comment 4:

See mkdoc.sh in that directory, plus this comment in doc.go:
// DO NOT EDIT THIS FILE. GENERATED BY mkdoc.sh.
// Edit the documentation in other files and rerun mkdoc.sh to generate this one.

[adg]

Comment 5:

This issue was closed by revision 091970c.

Status changed to Fixed.