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

testing: mention the “_test” package idiom #25223

Closed
bcmills opened this issue May 2, 2018 · 8 comments
Closed

testing: mention the “_test” package idiom #25223

bcmills opened this issue May 2, 2018 · 8 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@bcmills
Copy link
Contributor

bcmills commented May 2, 2018

https://tip.golang.org/cmd/go/#hdr-Test_packages says:

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.

However, https://tip.golang.org/pkg/testing/ omits that detail (emphasis mine):

To write a new test suite, create a file whose name ends _test.go that contains the TestXxx functions as described here. Put the file in the same package as the one being tested.

Tests in a separate _test package provide more realistic examples (and are better for catching awkward package names), so it's important that users be aware of that option. The testing package is an important entry point for users who are new to Go: its documentation should mention both package options or neither.

@bcmills bcmills added this to the Unplanned milestone May 2, 2018
@rillig
Copy link
Contributor

rillig commented Oct 27, 2018

After programming in Go for three years, I learned about this feature in this Stack Overflow answer. If the one sentence mentioning white-box and black-box testing had been in the reference documentation or the Effective Go document, it would have helped me quite a bit.

@gopherbot
Copy link

Change https://golang.org/cl/145279 mentions this issue: testing: mention the "_test" package idiom

@hearot
Copy link
Contributor

hearot commented Oct 28, 2018

At least, now it is a bit mentioned. I may expand its documentation.

@ALTree ALTree added the NeedsFix The path to resolution is known, but the work has not been done. label Feb 3, 2020
camilamacedo86 added a commit to operator-framework/operator-sdk that referenced this issue Sep 15, 2020
**Description of the change:**
- Update the go e2e test to have the suffix `_test` which has [special meaning for the Go compiler](golang/go#25223).
- Cleanup the test in order to make all following the same standard
- Ensure that the test are done using the makefile targets scaffolds as we suggest in our docs. 
- Add tests to ensure the metrics, run the project locally and the bundle sdk features
- fix the target in the doc https://master.sdk.operatorframework.io/docs/olm-integration/generation/#package-manifests-format. Users should use `$(KUSTOMIZE)` instead of kustomize directly.
- Fix Prometheus typo issue 

**Motivation for the change:**

- maintainability, readability and reusability
- ensure that our e2e tests are using the targets commands as we suggested to the users in the docs

NOTE: The first goal is to keep all tests following the same standard. However, it still has a hall for improvements that ought to make horizontally in follow-ups.
@marco-m
Copy link

marco-m commented Jun 4, 2022

hello @bcmills

https://pkg.go.dev/testing now has an additional sentence:

To write a new test suite, create a file whose name ends _test.go that contains the TestXxx functions as described here. Put the file in the same package as the one being tested.

it continues with:

The file will be excluded from regular package builds but will be included when the "go test" command is run.

Does that cover the intent of this issue?

@seankhliao

This comment was marked as outdated.

@rillig
Copy link
Contributor

rillig commented Jun 7, 2022

@marco-m No, that doesn't cover the intent of this issue. The documentation still only mentions the filename convention of adding _test, but not the package name convention of adding _test, just like in 2018.

This issue is about the difference between package pkgname and package pkgname_test.

@seankhliao seankhliao reopened this Jun 7, 2022
byarbrough pushed a commit to byarbrough/go that referenced this issue Aug 1, 2022
The existing documentation did not explain the difference between
placing a _test.go file in the same package as what is being
tested vs. adding it to a seprate _test package. This explains the
distinction and adds an example.

Concept is explained well here:  https://stackoverflow.com/a/31443271

Fixes golang#25223
byarbrough pushed a commit to byarbrough/go that referenced this issue Aug 1, 2022
The existing documentation did not explain the difference between
placing a _test.go file in the same package as what is being
tested vs. adding it to a seprate _test package. This explains the
distinction and adds an example.

Concept is explained well here:  https://stackoverflow.com/a/31443271

Fixes golang#25223
@gopherbot
Copy link

Change https://go.dev/cl/420415 mentions this issue: testing: explain using a _test package

@gopherbot
Copy link

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

7 participants