Debian Codegraph @

.claude/skills/add-assertion/SKILL.md

raw
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