Go Testify AssertExpectations 为什么不能证明调用次数完全正确

如果测试里只写了 mock.On("Save", ...).Return(nil)，最后再调用 AssertExpectations，它证明的是“这条期望至少被满足了”，不是“Save 恰好调用了规定次数”。默认期望没有上限，多调用可能仍然通过；少调用则通常会因为期望未满足而失败。

官方地址：https://pkg.go.dev/github.com/stretchr/testify/mock

把 AssertExpectations 当成“期望完成检查”，把 Once、Times 或 AssertNumberOfCalls 当成“次数约束”。如果还关心某一组参数的次数，必须缩小匹配范围或增加独立计数，不能只看 AssertExpectations 的返回值。

AssertExpectations 实际检查的是什么

Testify 的 mock 把测试拆成两类信息：一类是通过 On 声明的期望，另一类是业务代码调用 mock 后留下的实际记录。AssertExpectations 会逐条检查期望是否已经被调用满足，并且调用顺序默认不重要。

关键点在于，默认的 On(...).Return(...) 不会自动变成“只能调用一次”。官方 API 将 Once、Twice 和 Times 单独定义为次数控制；源码中的默认 Repeatability 为 0，表示没有剩余次数上限需要扣减。于是这两个问题不能混在一起：

• 期望有没有被满足？这是 AssertExpectations 主要回答的问题。
• 方法到底调用了几次？这是 Times、Once 或 AssertNumberOfCalls 要回答的问题。

为什么多调用时 AssertExpectations 仍可能通过

看一个最小场景。下面的服务故意保存两次，但测试只表达了“Save 这个参数组合应该能返回 nil”，没有表达次数上限。

package service_test

import (
    "context"
    "testing"

    "github.com/stretchr/testify/mock"
    "github.com/stretchr/testify/require"
)

type RepoMock struct {
    mock.Mock
}

func (m *RepoMock) Save(ctx context.Context, id string) error {
    // 把实际方法调用交给 Testify 记录，并取回约定的错误值。
    args := m.Called(ctx, id)
    return args.Error(0)
}

func saveTwice(ctx context.Context, repo *RepoMock, id string) error {
    // 这里模拟重复保存；示例重点是调用次数，而不是业务实现。
    if err := repo.Save(ctx, id); err != nil {
        return err
    }
    return repo.Save(ctx, id)
}

func TestAssertExpectationsOnlyChecksSatisfaction(t *testing.T) {
    ctx := context.Background()
    repo := new(RepoMock)

    // 没有 Once 或 Times，默认期望不表达精确次数上限。
    repo.On("Save", ctx, "u-7").Return(nil)

    require.NoError(t, saveTwice(ctx, repo, "u-7"))
    // 这只能说明 Save 的期望被满足，不能说明它只调用了一次。
    require.True(t, repo.AssertExpectations(t))
}

这段测试的风险不是 Testify “漏记”了调用，而是测试没有提出“只能调用一次”的问题。默认期望可以继续提供相同的返回值，AssertExpectations 检查到已有匹配调用后就有了满足依据。

反过来，如果业务一次都没有调用 Save，同一条默认期望通常会失败，因为它是必需期望。Maybe() 又会把期望改成可选：不调用也不导致期望检查失败。因此看到测试通过时，还要确认期望是不是被意外声明成了可选项。

需要精确次数时，把次数写进期望

如果规则是“这个参数组合必须且只能出现一次”，最直接的写法是 Once()。如果规则是固定批量处理两次，就用 Times(2)；两次这种常见情况也可以用 Twice()。

func TestSaveExactlyOnce(t *testing.T) {
    ctx := context.Background()
    repo := new(RepoMock)

    // Once 把“至少调用过”收紧为“这条期望只允许完成一次”。
    repo.On("Save", ctx, "u-7").Return(nil).Once()

    require.NoError(t, repo.Save(ctx, "u-7"))
    // 期望已经耗尽，AssertExpectations 负责确认它没有留下未满足项。
    require.True(t, repo.AssertExpectations(t))
}

需要注意，Once 的作用点是这条期望，不是整个 mock 对象的所有方法。如果另一个参数组合仍然使用默认 On，它依旧可能被调用多次。测试中有多条相似期望时，应逐条确认次数语义是否一致。

func TestSaveExactlyTwice(t *testing.T) {
    ctx := context.Background()
    repo := new(RepoMock)

    // Times(2) 让这条固定参数期望只接受两次调用。
    repo.On("Save", ctx, "u-7").Return(nil).Times(2)

    require.NoError(t, repo.Save(ctx, "u-7"))
    require.NoError(t, repo.Save(ctx, "u-7"))
    // 两次调用完成后，期望的剩余次数应为零。
    require.True(t, repo.AssertExpectations(t))
}

方法总次数和参数维度不是同一个问题

AssertNumberOfCalls 适合回答“这个 mock 的某个方法总共调用了几次”。它按方法名统计实际调用记录，因此可以补上默认 On 没有表达的总次数约束：

func TestSaveMethodTotal(t *testing.T) {
    ctx := context.Background()
    repo := new(RepoMock)

    // Anything 只放宽参数匹配；总次数由下面的断言单独负责。
    repo.On("Save", mock.Anything, mock.Anything).Return(nil)
    require.NoError(t, repo.Save(ctx, "u-7"))
    require.NoError(t, repo.Save(ctx, "u-8"))

    // AssertNumberOfCalls 统计 Save 方法的总调用次数，不区分 id。
    require.True(t, repo.AssertNumberOfCalls(t, "Save", 2))
    // 最后仍检查已声明的期望是否都被满足。
    require.True(t, repo.AssertExpectations(t))
}

这时如果真正的规则是“u-7 一次、u-8 一次”，只断言方法总数仍然不够，因为一次 u-7 加一次 u-8 与两次 u-7 都可能得到总数 2。可以为每个关键参数组合声明独立的 Once 或 Times 期望；参数结构复杂时，使用更窄的匹配器，并在 mock 方法内部维护面向业务的计数。

同理，AssertCalled 只能说明某个方法和参数曾经出现，不是精确次数断言；AssertNotCalled 只适合否定某种调用。不要因为这些断言名字里有 “Assert” 就把它们当作完整调用审计。

几个容易让次数判断失真的边界

使用 mock.Anything 会扩大匹配面

mock.Anything 能让测试更抗变化，但也会把不同 id、不同请求对象甚至不同业务分支折叠到同一条期望中。若次数是按租户、订单或用户维度定义的，就不能只用方法总数证明规则成立。

重复声明同名期望会改变阅读方式

多条 On("Save", ...) 可以对应不同参数，也可以对应相同参数。读测试的人需要知道哪条期望负责哪一段调用；否则即使总断言通过，也很难判断某个调用究竟消耗了哪条次数约束。精确批次建议把参数写得具体，并让每条期望只承担一个清晰场景。

并发调用要先等业务结束

如果被测代码启动 goroutine 后测试函数就直接执行断言，断言看到的调用记录可能还没有收齐。Testify 的 mock 对内部记录有锁保护，但它不会替你等待业务 goroutine 结束。先通过 WaitGroup、结果 channel 或被测服务自己的关闭信号完成收束，再做次数断言。

func waitAndAssert(t *testing.T, repo *RepoMock, done 

一张清单判断测试是否真的覆盖了次数

把以下四个问题放在测试收尾处，通常就能发现“AssertExpectations 通过但调用次数不对”的漏洞：

1. 这条 On 期望是必需的还是 Maybe 可选的？
2. 需要的是至少一次、恰好一次、固定 N 次，还是方法总次数？
3. 匹配范围是否足够窄，是否把多个参数值折叠进了 mock.Anything？
4. 所有 goroutine 是否已经结束，调用记录是否已经稳定？

结论

AssertExpectations 不是全量调用次数证明器，它检查的是已声明期望是否完成。默认 On(...).Return(...) 适合表达“这个调用应该可用”，但不适合表达“只能调用几次”。一旦次数是业务规则，就把规则写进测试：单条期望用 Once 或 Times，方法总量用 AssertNumberOfCalls，参数维度和并发收尾再单独补齐。

相关问题

AssertExpectations 会检查调用顺序吗？

默认不检查，官方文档说明调用可以以任意顺序发生。如果顺序本身是业务约束，需要使用 Testify 提供的顺序约束能力，不能从 AssertExpectations 的通过结果反推出顺序正确。

Times(0) 可以用来禁止调用吗？

它表达的是这条期望不应被消耗，但如果要明确验证某个方法没有发生，也可以使用 AssertNotCalled，并注意参数匹配范围。

为什么 AssertNumberOfCalls 通过了，期望检查仍然失败？

因为方法总数正确不等于每条期望都满足。可能是参数不匹配、必需期望缺失，或者某条期望的固定次数尚未消耗完。两个断言检查的维度不同。