Skip to content

Commit aafd5de

Browse files
lainiolainio
committed
move asserter constant's documentation above of section: go doc way
1 parent efed678 commit aafd5de

File tree

1 file changed

+66
-65
lines changed

1 file changed

+66
-65
lines changed

‎assert/assert.go

Lines changed: 66 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -16,77 +16,78 @@ import (
1616

1717
type defInd = uint32
1818

19+
// Asserters are the way to set what kind of messages assert package outputs if
20+
// assertion is violated.
21+
//
22+
// [Plain] converts asserts just plain K&D error messages without extra
23+
// information. That's useful for apps that want to use assert package to
24+
// validate e.g. command fields:
25+
//
26+
// assert.NotEmpty(c.PoolName, "pool name cannot be empty")
27+
//
28+
// Note, that Plain is only asserter that override auto-generated assertion
29+
// messages with given arguments like 'pool name cannot be empty'. Others add
30+
// given arguments at the end of the auto-generated assert message.
31+
//
32+
// [Production] (pkg's default) is the best asserter for most cases. The
33+
// assertion violations are treated as Go error values. And only a pragmatic
34+
// caller info is included into the error values like source filename, line
35+
// number, and caller function, all in one line:
36+
//
37+
// copy file: main.go:37: CopyFile(): assertion violation: string shouldn't be empty
38+
//
39+
// [Development] is the best asserter for development use. The assertion
40+
// violations are treated as Go error values. And a formatted caller info is
41+
// included to the error message like source filename , line number, and caller
42+
// function. Everything in a noticeable multi-line message:
43+
//
44+
// --------------------------------
45+
// Assertion Fault at:
46+
// main.go:37 CopyFile():
47+
// assertion violation: string shouldn't be empty
48+
// --------------------------------
49+
//
50+
// [Test] minimalistic asserter for unit test use. More pragmatic is the
51+
// TestFull asserter (test default).
52+
//
53+
// Use this asserter if your IDE/editor doesn't support full file names and it
54+
// relies a relative path (Go standard). You can use this also if you need
55+
// temporary problem solving for your programming environment.
56+
//
57+
// [TestFull] asserter (test default). The TestFull asserter includes the caller
58+
// info and the call stack for unit testing, similarly like err2's error traces.
59+
//
60+
// The call stack produced by the test asserts can be used over Go module
61+
// boundaries. For example, if your app and it's sub packages both use
62+
// err2/assert for unit testing and runtime checks, the runtime assertions will
63+
// be automatically converted to test asserts. If any of the runtime asserts of
64+
// the sub packages fails during the app tests, the app test fails as well.
65+
//
66+
// Note, that the cross-module assertions produce long file names (path
67+
// included), and some of the Go test result parsers cannot handle that. A
68+
// proper test result parser like 'github.com/lainio/nvim-go' (fork) works very
69+
// well. Also most of the make result parsers can process the output properly
70+
// and allow traverse of locations of the error trace.
71+
//
72+
// [Debug] asserter transforms assertion violations to panic calls where panic
73+
// object's type is string, i.e., err2 package treats it as a normal panic, not
74+
// an error.
75+
//
76+
// For example, the pattern that e.g. Go's standard library uses:
77+
//
78+
// if p == nil {
79+
// panic("pkg: ptr cannot be nil")
80+
// }
81+
//
82+
// is equal to:
83+
//
84+
// assert.NotNil(p)
1985
const (
20-
// Plain converts asserts just plain K&D error messages without extra
21-
// information. That's useful for apps that want to use assert package to
22-
// validate e.g. command fields:
23-
//
24-
// assert.NotEmpty(c.PoolName, "pool name cannot be empty")
25-
//
26-
// Note, that Plain is only asserter that override auto-generated assertion
27-
// messages with given arguments like 'pool name cannot be empty'. Others
28-
// add given arguments at the end of the auto-generated assert message.
2986
Plain defInd = 0 + iota
30-
31-
// Production (pkg default) is the best asserter for most cases. The
32-
// assertion violations are treated as Go error values. And only a
33-
// pragmatic caller info is included into the error values like source
34-
// filename, line number, and caller function, all in one line:
35-
//
36-
// copy file: main.go:37: CopyFile(): assertion violation: string shouldn't be empty
3787
Production
38-
39-
// Development is the best asserter for development use. The assertion
40-
// violations are treated as Go error values. And a formatted caller info
41-
// is included to the error message like source filename , line number, and
42-
// caller function. Everything in a noticeable multi-line message:
43-
//
44-
// --------------------------------
45-
// Assertion Fault at:
46-
// main.go:37 CopyFile():
47-
// assertion violation: string shouldn't be empty
48-
// --------------------------------
4988
Development
50-
51-
// Test minimalistic asserter for unit test use. More pragmatic is the
52-
// TestFull asserter (test default).
53-
//
54-
// Use this asserter if your IDE/editor doesn't support full file names and
55-
// it relies a relative path (Go standard). You can use this also if you
56-
// need temporary problem solving for your programming environment.
5789
Test
58-
59-
// TestFull asserter (test default). The TestFull asserter includes the
60-
// caller info and the call stack for unit testing, similarly like err2's
61-
// error traces.
62-
//
63-
// The call stack produced by the test asserts can be used over Go module
64-
// boundaries. For example, if your app and it's sub packages both use
65-
// err2/assert for unit testing and runtime checks, the runtime assertions
66-
// will be automatically converted to test asserts. If any of the runtime
67-
// asserts of the sub packages fails during the app tests, the app test
68-
// fails as well.
69-
//
70-
// Note, that the cross-module assertions produce long file names (path
71-
// included), and some of the Go test result parsers cannot handle that.
72-
// A proper test result parser like 'github.com/lainio/nvim-go' (fork)
73-
// works very well. Also most of the make result parsers can process the
74-
// output properly and allow traverse of locations of the error trace.
7590
TestFull
76-
77-
// Debug asserter transforms assertion violations to panic calls where
78-
// panic object's type is string, i.e., err2 package treats it as a normal
79-
// panic, not an error.
80-
//
81-
// For example, the pattern that e.g. Go's standard library uses:
82-
//
83-
// if p == nil {
84-
// panic("pkg: ptr cannot be nil")
85-
// }
86-
//
87-
// is equal to:
88-
//
89-
// assert.NotNil(p)
9091
Debug
9192
)
9293

0 commit comments

Comments
 (0)