[go] testing: explain using a _test package
Gerrit Bot (Gerrit)
Gerrit Bot has uploaded this change for review.
testing: explain using a _test package
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 #25223
Change-Id: Iebaba15207d8aa24f0b370d8dd4062eadb504b5c
GitHub-Last-Rev: 8e4322ab3c7d927e65741ec190598a011794b5f1
GitHub-Pull-Request: golang/go#54160
---
M src/testing/testing.go
1 file changed, 52 insertions(+), 4 deletions(-)
diff --git a/src/testing/testing.go b/src/testing/testing.go
index ec2d864..f2d454e 100644
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -14,12 +14,19 @@
// Within these functions, use the Error, Fail or related methods to signal failure.
//
// 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. The file will be excluded from regular
+// contains the TestXxx functions as described here.
+// The file will be excluded from regular
// package builds but will be included when the "go test" command is run.
-// For more detail, run "go help test" and "go help testflag".
//
-// A simple test function looks like this:
+// The test file can either be in the same package as the one being tested,
+// or you can place it in a package with the _test suffix.
+//
+// If the test file is in the package you are testing, then you can can access
+// all identifiers within the package, such as in this example:
+//
+// package abs
+//
+// import "testing"
//
// func TestAbs(t *testing.T) {
// got := Abs(-1)
@@ -28,6 +35,27 @@
// }
// }
//
+// If the test files is in a _test package, then you must import the package you
+// wish to test and then reference the exported identifiers.
+// This is known as "black box" testing.
+//
+// package abs_test
+//
+// import (
+// "testing"
+//
+// "path_to_pkg/abs"
+// )
+//
+// func TestAbs(t *testing.T) {
+// got := abs.Abs(-1)
+// if got != 1 {
+// t.Errorf("Abs(-1) = %d; want 1", got)
+// }
+// }
+//
+// For more detail, run "go help test" and "go help testflag".
+//
// # Benchmarks
//
// Functions of the form
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Gopher Robot (Gerrit)
Attention is currently required from: Bryan Mills.
Congratulations on opening your first change. Thank you for your contribution!
Next steps:
A maintainer will review your change and provide feedback. See
https://go.dev/doc/contribute#review for more info and tips to get your
patch through code review.
Most changes in the Go project go through a few rounds of revision. This can be
surprising to people new to the project. The careful, iterative review process
is our way of helping mentor contributors and ensuring that their contributions
have a lasting impact.
During May-July and Nov-Jan the Go project is in a code freeze, during which
little code gets reviewed or merged. If a reviewer responds with a comment like
R=go1.11 or adds a tag like "wait-release", it means that this CL will be
reviewed as part of the next development cycle. See https://go.dev/s/release
for more details.
Bryan Mills (Gerrit)
1 comment:
File src/testing/testing.go:
(nit) The rest of the docs for this package avoid the word “you”, instead preferring the passive voice.
So, something like:
```
// The test file can be in the same package as the one being tested,
// or in a corresponding package with the suffix "_test".
//
// If the test file is in the same package, it may refer to unexported
// identifiers within the package, as in this example:
…
// If the file is in a separate "_test" package, the package being tested
// must be imported explicitly and only its exported identifiers may be used:
…
```
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Gerrit Bot uploaded patch set #2 to this change.
testing: explain using a _test package
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 #25223
Change-Id: Iebaba15207d8aa24f0b370d8dd4062eadb504b5c
GitHub-Last-Rev: 5d6f4fa6e423b57894112a35bd684bf18285380a
GitHub-Pull-Request: golang/go#54160
---
M src/testing/testing.go
1 file changed, 52 insertions(+), 4 deletions(-)
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Brian (Gerrit)
Attention is currently required from: Bryan Mills.
Patch set 2:Code-Review +1
1 comment:
File src/testing/testing.go:
(nit) The rest of the docs for this package avoid the word “you”, instead preferring the passive voi […]
Done. That definitely reads better, thanks!
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Brian (Gerrit)
Attention is currently required from: Bryan Mills.
Patch set 2:-Code-Review
1 comment:
Patchset:
Reverting the accidental self review; apologies for the noise!
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Dan Kortschak (Gerrit)
Attention is currently required from: Bryan Mills.
1 comment:
Commit Message:
Patch Set #2, Line 11:
seprateseparate
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Brian (Gerrit)
Attention is currently required from: Bryan Mills, Dan Kortschak.
1 comment:
Commit Message:
Patch Set #2, Line 11:
seprateseparate
Done. English spelling is the worst.
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Attention is currently required from: Bryan Mills, Dan Kortschak.
Gerrit Bot uploaded patch set #3 to this change.
testing: explain using a _test package
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 separate _test package. This explains the
distinction and adds an example.
Concept is explained well here: https://stackoverflow.com/a/31443271
Fixes #25223
Change-Id: Iebaba15207d8aa24f0b370d8dd4062eadb504b5c
GitHub-Last-Rev: 43cef699ed47cd5cad72253a2f88795e314c7496
GitHub-Pull-Request: golang/go#54160
---
M src/testing/testing.go
1 file changed, 52 insertions(+), 4 deletions(-)
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Bryan Mills (Gerrit)
Attention is currently required from: Dan Kortschak.
Patch set 3:Run-TryBot +1Code-Review +2
2 comments:
File src/testing/testing.go:
//
// import "testing"
//(not sure) Do the blank lines in these code blocks need trailing tabs to keep each snippet in a single block?
s/This/this/ (since the previous line ends in a colon)
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Attention is currently required from: Bryan Mills, Dan Kortschak.
Gerrit Bot uploaded patch set #4 to this change.
The following approvals got outdated and were removed: Run-TryBot+1 by Bryan Mills, TryBot-Result+1 by Gopher Robot
testing: explain using a _test package
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 separate _test package. This explains the
distinction and adds an example.
Concept is explained well here: https://stackoverflow.com/a/31443271
Fixes #25223
Change-Id: Iebaba15207d8aa24f0b370d8dd4062eadb504b5c
GitHub-Last-Rev: 7f49c5f4624b358af8052272da8ac3240751ada0
GitHub-Pull-Request: golang/go#54160
---
M src/testing/testing.go
1 file changed, 52 insertions(+), 4 deletions(-)
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Brian (Gerrit)
Attention is currently required from: Bryan Mills, Dan Kortschak.
2 comments:
File src/testing/testing.go:
//
// import "testing"
//
(not sure) Do the blank lines in these code blocks need trailing tabs to keep each snippet in a sing […]
The codeblock under # Example lower down doesn't have a trailing tab, so I don't think they are needed.
I also built it with `godoc` and it was a single block.
s/This/this/ (since the previous line ends in a colon)
Replaced the colon with a period.
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.
Bryan Mills (Gerrit)
Attention is currently required from: Dan Kortschak.
Patch set 4:Run-TryBot +1Auto-Submit +1Code-Review +2
Heschi Kreinick (Gerrit)
Attention is currently required from: Dan Kortschak.
Patch set 4:Code-Review +1
Gopher Robot (Gerrit)
Gopher Robot submitted this change.
testing: explain using a _test package
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 separate _test package. This explains the
distinction and adds an example.
Concept is explained well here: https://stackoverflow.com/a/31443271
Fixes #25223
Change-Id: Iebaba15207d8aa24f0b370d8dd4062eadb504b5c
GitHub-Last-Rev: 7f49c5f4624b358af8052272da8ac3240751ada0
GitHub-Pull-Request: golang/go#54160
Reviewed-on: https://go-review.googlesource.com/c/go/+/420415
Reviewed-by: Bryan Mills <bcm...@google.com>
TryBot-Result: Gopher Robot <go...@golang.org>
Reviewed-by: Heschi Kreinick <hes...@google.com>
Auto-Submit: Bryan Mills <bcm...@google.com>
Run-TryBot: Bryan Mills <bcm...@google.com>
---
M src/testing/testing.go
1 file changed, 58 insertions(+), 4 deletions(-)
diff --git a/src/testing/testing.go b/src/testing/testing.go
index a38b40e..5fd1539 100644
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -14,12 +14,19 @@
// Within these functions, use the Error, Fail or related methods to signal failure.
//
// 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. The file will be excluded from regular
+// contains the TestXxx functions as described here.
+// The file will be excluded from regular
// package builds but will be included when the "go test" command is run.
-// For more detail, run "go help test" and "go help testflag".
//
-// A simple test function looks like this:
+// The test file can be in the same package as the one being tested,
+// or in a corresponding package with the suffix "_test".
+//
+// If the test file is in the same package, it may refer to unexported
+// identifiers within the package, as in this example:
+//
+// package abs
+//
+// import "testing"
//
// func TestAbs(t *testing.T) {
// got := Abs(-1)
@@ -28,6 +35,27 @@
// }
// }
//
+// If the file is in a separate "_test" package, the package being tested
+// must be imported explicitly and only its exported identifiers may be used.
+// This is known as "black box" testing.
+//
+// package abs_test
+//
+// import (
+// "testing"
+//
+// "path_to_pkg/abs"
+// )
+//
+// func TestAbs(t *testing.T) {
+// got := abs.Abs(-1)
+// if got != 1 {
+// t.Errorf("Abs(-1) = %d; want 1", got)
+// }
+// }
+//
+// For more detail, run "go help test" and "go help testflag".
+//
// # Benchmarks
//
// Functions of the form
To view, visit change 420415. To unsubscribe, or for help writing mail filters, visit settings.