| 1 |
# Adding a New Assertion |
| 2 |
|
| 3 |
Step-by-step workflow for adding a new assertion function to testify. |
| 4 |
|
| 5 |
## Workflow |
| 6 |
|
| 7 |
1. Add function to the appropriate domain file in `internal/assertions/` |
| 8 |
2. Add `// Domain: <domain>` as the first line inside the function body |
| 9 |
3. Add `// Opposite: <Name>` on the next line if a logical opposite exists |
| 10 |
4. Add `Examples:` section to the doc comment |
| 11 |
5. Add tests to the corresponding `*_test.go` file |
| 12 |
6. Run `go generate ./...` to produce all 8 variants + docs |
| 13 |
7. Run `go test work ./...` to verify everything |
| 14 |
|
| 15 |
## Function template |
| 16 |
|
| 17 |
```go |
| 18 |
// FuncName asserts that <what it does>. |
| 19 |
// |
| 20 |
// # Usage |
| 21 |
// |
| 22 |
// assertions.FuncName(t, arg1, arg2) |
| 23 |
// |
| 24 |
// # Examples |
| 25 |
// |
| 26 |
// success: arg1Value, arg2Value |
| 27 |
// failure: arg1Value, arg2Value |
| 28 |
func FuncName(t T, arg1, arg2 any, msgAndArgs ...any) bool { |
| 29 |
// Domain: <domain> |
| 30 |
// Opposite: <OppositeName> (omit if none) |
| 31 |
if h, ok := t.(H); ok { |
| 32 |
h.Helper() |
| 33 |
} |
| 34 |
|
| 35 |
// implementation |
| 36 |
if !condition { |
| 37 |
return Fail(t, "message", msgAndArgs...) |
| 38 |
} |
| 39 |
|
| 40 |
return true |
| 41 |
} |
| 42 |
``` |
| 43 |
|
| 44 |
## Doc comment annotations |
| 45 |
|
| 46 |
### Domain tag (in doc comment header) |
| 47 |
|
| 48 |
```go |
| 49 |
// domain: equality |
| 50 |
``` |
| 51 |
|
| 52 |
Assigns the function to a documentation domain. Add domain descriptions in |
| 53 |
`internal/assertions/doc.go` if creating a new domain. |
| 54 |
|
| 55 |
### Domain comment (inside function body) |
| 56 |
|
| 57 |
```go |
| 58 |
// Domain: equality |
| 59 |
``` |
| 60 |
|
| 61 |
First line inside the function body. Used by the codegen scanner. |
| 62 |
|
| 63 |
### Opposite annotation |
| 64 |
|
| 65 |
```go |
| 66 |
// Opposite: NotEqual |
| 67 |
``` |
| 68 |
|
| 69 |
Second line inside the body (after Domain). Only on the affirmative form |
| 70 |
(e.g., on `Equal`, not on `NotEqual`). |
| 71 |
|
| 72 |
### Examples section |
| 73 |
|
| 74 |
```go |
| 75 |
// # Examples |
| 76 |
// |
| 77 |
// success: 123, 123 |
| 78 |
// failure: 123, 456 |
| 79 |
``` |
| 80 |
|
| 81 |
Drives generated smoke tests for all 8 variants. Three case types: |
| 82 |
- `success: <args>` -- test should pass |
| 83 |
- `failure: <args>` -- test should fail |
| 84 |
- `panic: <args>` followed by `<expected panic message>` on next line |
| 85 |
|
| 86 |
For complex values that can't be represented inline, use `// NOT IMPLEMENTED`: |
| 87 |
```go |
| 88 |
// success: &customStruct{Field: "value"}, // NOT IMPLEMENTED |
| 89 |
``` |
| 90 |
|
| 91 |
**Never use `// TODO`** -- it triggers false positives in code quality tools. |
| 92 |
|
| 93 |
## What gets generated |
| 94 |
|
| 95 |
From a single function, `go generate` produces: |
| 96 |
|
| 97 |
| Variant | Package | Example | |
| 98 |
|---------|---------|---------| |
| 99 |
| Package-level | `assert` | `assert.FuncName(t, ...)` | |
| 100 |
| Formatted | `assert` | `assert.FuncNamef(t, ..., "msg")` | |
| 101 |
| Forward method | `assert` | `a.FuncName(...)` | |
| 102 |
| Forward formatted | `assert` | `a.FuncNamef(..., "msg")` | |
| 103 |
| Package-level | `require` | `require.FuncName(t, ...)` | |
| 104 |
| Formatted | `require` | `require.FuncNamef(t, ..., "msg")` | |
| 105 |
| Forward method | `require` | `r.FuncName(...)` | |
| 106 |
| Forward formatted | `require` | `r.FuncNamef(..., "msg")` | |
| 107 |
|
| 108 |
Plus: tests for all variants, documentation entry in `docs/doc-site/api/<domain>.md`. |
| 109 |
|
| 110 |
Generic assertions (with type params) produce 4 variants (no forward methods -- |
| 111 |
Go limitation). |
| 112 |
|
| 113 |
## Checklist |
| 114 |
|
| 115 |
- [ ] Function in `internal/assertions/<domain>.go` |
| 116 |
- [ ] `// Domain:` and optionally `// Opposite:` inside function body |
| 117 |
- [ ] Doc comment with `# Usage`, `# Examples` sections |
| 118 |
- [ ] Tests in `internal/assertions/<domain>_test.go` |
| 119 |
- [ ] `go generate ./...` succeeds |
| 120 |
- [ ] `go test work ./...` passes |
| 121 |
- [ ] `golangci-lint run --new-from-rev master` clean |