测试
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
func TestLoadConfig(t *testing.T) {
t.Parallel()
files := fstest.MapFS{
"config.json": {Data: []byte(`{"env":"test"}`)},
}
cfg, err := config.Load(files, "config.json")
require.NoError(t, err)
assert.Equal(t, "test", cfg.Env)
}
# Golang Testing
Use this skill when writing, reviewing, or refactoring Go tests.
## When to Use
- Writing new unit, integration, or package-level tests for Go code
- Refactoring tests toward idiomatic Go structure and stronger signal
- Reviewing Go test suites for maintainability, determinism, and coverage gaps
- Designing fakes, mocks, or test seams around external dependencies
## Default Testing Stance
Unless there is a clear reason not to, prefer these defaults:
- Use **black-box tests** with an external test package: `package mypkg_test`
- Test **public behaviour and interfaces**, not internal implementation details
- Use **one top-level test function per public function/method/behaviour**, with **subtests** for scenarios
- Call **`t.Parallel()` by default** in top-level tests and subtests unless shared state, process-wide mutation, timing, or external resources make it unsafe
- Use **`t.Run` subtests by default**, even when not using table-driven tests
- Use **table-driven tests only** when there is a finite, related set of input/output scenarios that benefits from shared structure
- Use **`testify/require`** for preconditions and fatal assertions, and **`testify/assert`** for non-fatal assertions
- Use **`testify/mock`** only for true external-system boundaries or very small/simple seams; otherwise prefer fakes or in-memory implementations
- Keep tests deterministic, hermetic, and readable
## Core Principles
- **Behaviour over implementation** - Assert externally visible outcomes
- **Fast feedback** - Keep most tests cheap enough to run constantly
- **Deterministic** - Avoid sleeps, real clocks, network access, and ambient environment dependence
- **Minimal setup** - Prefer small helpers over deep fixture stacks
- **High signal** - Each failing test should point to one clear behaviour regression
- **Coverage with intent** - Cover important branches, edge cases, and error paths, not just lines
## Package and File Conventions
### Black-Box Test Packages
Prefer:
```go
package user_test
import (
"testing"
"github.com/stretchr/testify/require"
"example.com/project/user"
)
```
Avoid:
```go
package user
```
Use same-package tests only when you intentionally need access to unexported helpers and there is no better public seam. Default to `_test` packages.
### File Organisation
- Group tests by public API surface or behaviour
- Keep helper functions near the tests that use them unless broadly reused
- Prefer `_test.go` files named after the subject under test, such as `service_test.go`, `handler_test.go`, `client_test.go`
- Avoid giant catch-all files once a package grows
## Preferred Test Structure
### One Top-Level Test per Behaviour, Subtests per Scenario
For a public function, prefer one top-level test and scenario subtests instead of many separate `TestXxx_Yyy` functions.
Use `t.Run` even without a table when the scenarios are clearer as explicitly written examples.
```go
func TestCreateUser(t *testing.T) {
t.Parallel()
t.Run("success", func(t *testing.T) {
t.Parallel()
got, err := user.Create("alice@example.com")
require.NoError(t, err)
assert.Equal(t, "alice@example.com", got.Email)
})
t.Run("rejects invalid email", func(t *testing.T) {
t.Parallel()
_, err := user.Create("not-an-email")
require.Error(t, err)
require.ErrorIs(t, err, user.ErrInvalidEmail)
})
}
```
```go
func TestParseUserID(t *testing.T) {
t.Parallel()
tests := []struct {
name string
input string
want int
wantErr string
}{
{name: "valid", input: "42", want: 42},
{name: "empty", input: "", wantErr: "empty user id"},
{name: "invalid", input: "abc", wantErr: "invalid user id"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
got, err := user.ParseUserID(tt.input)
if tt.wantErr != "" {
require.Error(t, err)
assert.Contains(t, err.Error(), tt.wantErr)
return
}
require.NoError(t, err)
assert.Equal(t, tt.want, got)
})
}
}
```
### Why This Pattern
- Keeps all scenarios for one behaviour together
- Makes it easy to add edge cases without duplicating setup
- Produces better output in `go test -run` and CI logs
- Works naturally with table-driven tests and `t.Parallel()`
## Parallel Test Execution
### Default Rule
Call `t.Parallel()` unless there is a concrete reason not to.
Good candidates:
- Pure functions
- Tests using isolated in-memory state
- Tests using `t.TempDir()`
- Tests with per-test `httptest.Server`
- Table-driven subtests with isolated fixtures
Avoid or carefully isolate parallelism when tests:
- Mutate global variables, singleton state, env vars, or process working directory
- Depend on wall-clock timing or `time.Sleep`
- Reuse shared mocks/fakes with non-thread-safe state
- Use fixed ports, shared files, or shared databases without isolation
### Parallel Subtest Safety
In Go 1.22+ modules, loop variables declared in the `for` statement are created per iteration, so rebinding like `tt := tt` is usually not needed.
Still rebind when:
- the module/package targets pre-Go-1.22 semantics
- the variable is declared outside the loop and reused
- you intentionally want compatibility with older Go module targets
For modern Go:
```go
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
// use tt safely in Go 1.22+
})
}
```
For older module targets:
```go
for _, tt := range tests {
tt := tt
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
// use tt safely
})
}
```
## Testify Usage
Prefer Testify for clearer assertions.
```go
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
```
### `require` vs `assert`
- Use **`require`** when the test cannot continue after failure
- Use **`assert`** when you want multiple related checks in one scenario
```go
func TestUserName(t *testing.T) {
t.Parallel()
u, err := user.New("alice")
require.NoError(t, err)
assert.Equal(t, "alice", u.Name())
assert.True(t, u.IsActive())
}
```
Prefer semantic assertions when available:
- `require.ErrorIs`
- `assert.Equal`
- `assert.ElementsMatch`
- `assert.Len`
- `assert.Empty` / `assert.NotEmpty`
- `assert.WithinDuration`
- `assert.JSONEq`
## Error Testing
- Prefer asserting exported sentinel/type behaviour with `ErrorIs` / `ErrorAs`
- Avoid brittle full-string equality unless the exact message is part of the contract
- Assert both success and failure paths for public APIs
```go
require.ErrorIs(t, err, user.ErrNotFound)
```
## Good Coverage Practices
Aim for coverage that reflects risk and behaviour, not vanity percentages.
### Always Cover
- Happy path
- Input validation failures
- Boundary values
- Zero values and empty collections
- Domain-specific edge cases
- External dependency failures
- Serialization/parsing failures
- Context cancellation / timeout paths when relevant
- Idempotency or retry semantics when relevant
### Coverage Heuristics
- Add a test for every bug fix before or with the fix
- Cover each exported public method/function with at least one success and one failure/edge scenario where meaningful
- Prefer focused unit tests for combinatorial logic and a smaller number of integration tests for end-to-end confidence
- If a branch matters to production behaviour, it deserves an assertion
- Remove duplicate tests that do not add behavioural signal
### Coverage Commands
```bash
go test ./...
go test ./... -cover
go test ./... -coverprofile=coverage.out
go tool cover -func=coverage.out
go tool cover -html=coverage.out
```
## Integration vs Unit Tests
Use the lightest test that proves the behaviour.
### Prefer Unit Tests For
- Pure transformations and validation
- Orchestration logic with fake dependencies
- Error mapping and branching logic
### Prefer Integration Tests For
- SQL queries and repository behaviour
- HTTP handlers, middleware, and routing
- Serialization boundaries
- Interactions with real adapters that are cheap and deterministic to run locally/CI
When an integration test gives stronger confidence with similar complexity, prefer it over elaborate mocking.
## Mocking Guidance
### Default Rule
Mock only external systems or very thin boundaries. Prefer fakes and in-memory implementations for richer domain behaviour.
Prefer:
- In-memory repositories
- `httptest.Server`
- Temporary directories
- `fstest.MapFS`
- Fixed clocks / injectable time sources
Reach for `testify/mock` when:
- The dependency is an external system boundary
- A fake would be more complex than the behaviour being tested
- You need precise call assertions on a thin collaborator
Avoid mocks for:
- Your own core domain models
- Simple data containers
- Behaviour that is easier to express with an in-memory fake
- Deep implementation-driven interaction testing
### Testify Mock Pattern
```go
type MockMailer struct {
mock.Mock
}
func (m *MockMailer) Send(ctx context.Context, msg mail.Message) error {
args := m.Called(ctx, msg)
return args.Error(0)
}
func TestService_SendWelcomeEmail(t *testing.T) {
t.Parallel()
mailer := new(MockMailer)
mailer.
On("Send", mock.Anything, mail.Message{To: "alice@example.com"}).
Return(nil).
Once()
svc := user.NewService(mailer)
err := svc.SendWelcomeEmail(context.Background(), "alice@example.com")
require.NoError(t, err)
mailer.AssertExpectations(t)
}
```
Rules:
- One mock per external dependency seam, not everywhere
- Keep expectations minimal and behaviour-focused
- Avoid over-asserting call order unless it is part of the contract
- Do not share mock instances across parallel tests
## Filesystem Testing
Prefer standard-library-friendly seams and hermetic storage.
### Recommended Patterns
1. **Inject an `fs.FS`** for read-only filesystem behaviour
2. Use **`fstest.MapFS`** for small read scenarios
3. Use **`t.TempDir()`** for realistic file creation/update flows
4. Keep filesystem access behind a small adapter if the production code is otherwise hard to isolate
### `fstest.MapFS` Example
```go
func TestLoadConfig(t *testing.T) {
t.Parallel()
files := fstest.MapFS{
"config.json": {Data: []byte(`{"env":"test"}`)},
}
cfg, err := config.Load(files, "config.json")
require.NoError(t, err)
assert.Equal(t, "test", cfg.Env)
}
```
### `t.TempDir()` Example
```go
func TestWriteReport(t *testing.T) {
t.Parallel()
dir := t.TempDir()
path := filepath.Join(dir, "report.txt")
err := report.Write(path, "hello")
require.NoError(t, err)
data, err := os.ReadFile(path)
require.NoError(t, err)
assert.Equal(t, "hello", string(data))
}
```
Avoid mocking `os` calls directly when a temp dir or `fs.FS` seam would be simpler.
## HTTP Client Testing
Prefer real HTTP semantics without real network dependencies.
### Recommended Patterns
1. Use **`httptest.Server`** to test client behaviour against realistic responses
2. Inject `*http.Client` into your code
3. For very small seams, a custom `http.RoundTripper` fake can be enough
4. Mock higher-level gateways only when HTTP itself is not the thing under test
### `httptest.Server` Example
```go
func TestClient_GetUser(t *testing.T) {
t.Parallel()
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
assert.Equal(t, http.MethodGet, r.Method)
assert.Equal(t, "/users/42", r.URL.Path)
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"id":42,"name":"alice"}`))
}))
t.Cleanup(srv.Close)
client := api.NewClient(srv.URL, srv.Client())
got, err := client.GetUser(context.Background(), 42)
require.NoError(t, err)
assert.Equal(t, "alice", got.Name)
}
```
### Custom Transport Fake
For narrow client logic, prefer a tiny fake over a heavyweight mock:
```go
type roundTripFunc func(*http.Request) (*http.Response, error)
func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
return f(r)
}
```
Use this when you only need to simulate one request/response pair and `httptest.Server` would be unnecessary ceremony.
## Time Testing
Do not depend on real time in tests.
### Recommended Patterns
1. Inject time via a function like `now func() time.Time`
2. Or define a tiny clock interface at the boundary that needs it
3. Use fixed timestamps in tests
4. Avoid `time.Sleep` as a synchronisation mechanism
5. Prefer contexts, channels, and explicit signals over waiting for elapsed time
### Function Injection Example
```go
type Service struct {
now func() time.Time
}
func NewService() *Service {
return &Service{now: time.Now}
}
```
```go
func TestTokenExpired(t *testing.T) {
t.Parallel()
fixed := time.Date(2025, 1, 1, 12, 0, 0, 0, time.UTC)
svc := token.NewService(func() time.Time { return fixed })
assert.True(t, svc.IsExpired(fixed.Add(-time.Second)))
assert.False(t, svc.IsExpired(fixed.Add(time.Second)))
}
```
If production code currently calls `time.Now()` directly in many places, first introduce a small seam at the package boundary rather than mocking time per call site.
## Table-Driven Testing Guidance
- Prefer plain `t.Run` subtests first without a table when scenarios are clearer as explicitly written examples
- Use tables when the setup is mostly the same and only inputs/expectations vary
- Name cases for behaviour, not raw input values
- Keep test case structs focused; avoid giant anonymous structs with dozens of fields
- Split unrelated behaviours into separate tests instead of massive tables
Good fit for table-driven tests:
- Parsing and validation matrices
- Boundary-value checks on the same function
- Multiple related input/output combinations for deterministic logic
Poor fit for table-driven tests:
- Scenarios with materially different setup or assertions
- Behaviour tests that read more clearly as individually named `t.Run` blocks
- Large tables that hide intent behind many mostly-empty fields
## Test Helpers
- Prefer helper functions that build valid defaults and allow explicit overrides
- Mark helpers with `t.Helper()`
- Return concrete values rather than hidden global state
- Keep helpers local to the package unless broad reuse justifies promotion
```go
func newTestUser(t *testing.T, opts ...UserOption) user.User {
t.Helper()
u, err := user.New("alice", opts...)
require.NoError(t, err)
return u
}
```
## Anti-Patterns
Avoid these unless there is a strong reason:
- Same-package white-box tests by default
- Multiple top-level tests for each small scenario of one function
- Reaching for table-driven tests when explicit `t.Run` scenarios are clearer
- No `t.Parallel()` without reason
- Real sleeps, real network calls, or dependence on current wall-clock time
- Assertion on internal private fields in black-box tests
- Brittle exact error string checks for wrapped/domain errors
- Massive shared fixtures that hide what the test actually needs
- Mock-heavy tests that mirror implementation rather than behaviour
- Coverage chasing without meaningful assertions
## Review Checklist
When reviewing Go tests, check for:
- Black-box `_test` package usage by default
- `t.Parallel()` in top-level tests and subtests unless unsafe
- Subtests for multiple scenarios of one behaviour
- `testify/assert` and `testify/require` used appropriately
- Fakes preferred over mocks when practical
- `testify/mock` limited to external boundaries or simple seams
- No hidden global state or cross-test coupling
- Deterministic handling of filesystem, HTTP, and time
- Meaningful edge-case and error-path coverage
- Tests that read like executable specifications of public behaviour
---
> Source: [brpaz/agent-skills](https://github.com/brpaz/agent-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
何时使用
默认测试姿势
核心原则
黑盒测试包
文件组织
文件/命令 -> package mypkg_test · t.Parallel() · t.Run · testify/require · testify/assert · testify/mock · _test · _test.go
内容校验值 -> 7a3b920debf1
当前原文的自动摘译,尚未人工审校。
何时使用
为 Go 代码编写新的单元、集成或包级测试 针对惯用的 Go 结构和更强的信号重构测试 审查 Go 测试套件的可维护性、确定性和覆盖范围差距 围绕外部依赖项设计伪造、模拟或测试接缝
默认测试姿势
除非有明确的理由不这样做,否则首选这些默认设置: 使用带有外部测试包的黑盒测试:
package mypkg_test测试公共行为和接口,而不是内部实现细节 每个公共函数/方法/行为使用一个顶级测试函数,并针对场景进行子测试 在顶级测试和子测试中默认调用t.Parallel()除非共享状态、进程范围的突变、计时或外部资源使其不安全核心原则
行为优于实现 - 断言外部可见的结果 快速反馈 - 使大多数测试足够便宜以持续运行 确定性 - 避免睡眠、真实时钟、网络访问和周围环境依赖 最小化设置 - 更喜欢小助手而不是深度夹具堆栈 高信号 - 每个失败的测试都应该指向一个明确的行为回归
黑盒测试包
首选:避免:仅当您有意需要访问未导出的帮助程序并且没有更好的公共接缝时,才使用相同的包测试。默认为
_test包。文件组织
按公共 API 表面或行为对测试进行分组 将辅助函数保留在使用它们的测试附近,除非广泛重用 首选以被测主题命名的
_test.go文件,例如service_test.go、handler_test.go、client_test.go一旦包增长,避免使用巨大的包罗万象的文件