Back to Details

property-based-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Property-Based Testing Guide

基于属性的测试（Property-Based Testing）指南

Use this skill proactively during development when you encounter patterns where PBT provides stronger coverage than example-based tests.
在开发过程中，当你遇到PBT比基于示例的测试能提供更强覆盖范围的模式时，主动使用本技能。

When to Invoke (Automatic Detection)

何时调用（自动检测）

Invoke this skill when you detect:
  • Serialization pairs: 
    encode
    /
    decode
    , 
    serialize
    /
    deserialize
    , 
    toJSON
    /
    fromJSON
    , 
    pack
    /
    unpack
  • Parsers: URL parsing, config parsing, protocol parsing, string-to-structured-data
  • Normalization: 
    normalize
    , 
    sanitize
    , 
    clean
    , 
    canonicalize
    , 
    format
  • Validators: 
    is_valid
    , 
    validate
    , 
    check_*
    (especially with normalizers)
  • Data structures: Custom collections with 
    add
    /
    remove
    /
    get
    operations
  • Mathematical/algorithmic: Pure functions, sorting, ordering, comparators
  • Smart contracts: Solidity/Vyper contracts, token operations, state invariants, access control
Priority by pattern:
PatternPropertyPriority
encode/decode pairRoundtripHIGH
Pure functionMultipleHIGH
ValidatorValid after normalizeMEDIUM
Sorting/orderingIdempotence + orderingMEDIUM
NormalizationIdempotenceMEDIUM
Builder/factoryOutput invariantsLOW
Smart contractState invariantsHIGH
检测到以下情况时调用本技能：
  • 序列化配对：
    encode
    /
    decode
    , 
    serialize
    /
    deserialize
    , 
    toJSON
    /
    fromJSON
    , 
    pack
    /
    unpack
  • 解析器：URL解析、配置解析、协议解析、字符串转结构化数据
  • 标准化：
    normalize
    , 
    sanitize
    , 
    clean
    , 
    canonicalize
    , 
    format
  • 验证器：
    is_valid
    , 
    validate
    , 
    check_*
    （尤其搭配标准化工具时）
  • 数据结构：包含
    add
    /
    remove
    /
    get
    操作的自定义集合
  • 数学/算法类：纯函数、排序、排序规则、比较器
  • 智能合约：Solidity/Vyper合约、代币操作、状态不变量、访问控制
按模式优先级排序：
模式属性优先级
encode/decode配对往返一致性（Roundtrip）高
纯函数多属性验证高
验证器标准化后验证有效中
排序/排序规则幂等性 + 排序规则中
标准化幂等性中
构建器/工厂输出不变量低
智能合约状态不变量高

When NOT to Use

何时不使用

Do NOT use this skill for:
  • Simple CRUD operations without transformation logic
  • One-off scripts or throwaway code
  • Code with side effects that cannot be isolated (network calls, database writes)
  • Tests where specific example cases are sufficient and edge cases are well-understood
  • Integration or end-to-end testing (PBT is best for unit/component testing)
请勿在以下场景使用本技能：
  • 无转换逻辑的简单CRUD操作
  • 一次性脚本或临时代码
  • 包含无法隔离的副作用的代码（网络调用、数据库写入）
  • 特定示例用例已足够且边界情况已充分理解的测试
  • 集成或端到端测试（PBT最适用于单元/组件测试）

Property Catalog (Quick Reference)

属性目录（快速参考）

PropertyFormulaWhen to Use
Roundtrip
decode(encode(x)) == x
Serialization, conversion pairs
Idempotence
f(f(x)) == f(x)
Normalization, formatting, sorting
InvariantProperty holds before/afterAny transformation
Commutativity
f(a, b) == f(b, a)
Binary/set operations
Associativity
f(f(a,b), c) == f(a, f(b,c))
Combining operations
Identity
f(x, identity) == x
Operations with neutral element
Inverse
f(g(x)) == x
encrypt/decrypt, compress/decompress
Oracle
new_impl(x) == reference(x)
Optimization, refactoring
Easy to Verify
is_sorted(sort(x))
Complex algorithms
No ExceptionNo crash on valid inputBaseline property
Strength hierarchy (weakest to strongest): No Exception → Type Preservation → Invariant → Idempotence → Roundtrip
属性公式适用场景
往返一致性（Roundtrip）
decode(encode(x)) == x
序列化、转换配对
幂等性（Idempotence）
f(f(x)) == f(x)
标准化、格式化、排序
不变量（Invariant）属性在转换前后保持不变任何转换操作
交换律（Commutativity）
f(a, b) == f(b, a)
二元/集合操作
结合律（Associativity）
f(f(a,b), c) == f(a, f(b,c))
组合操作
恒等性（Identity）
f(x, identity) == x
包含中性元素的操作
逆运算（Inverse）
f(g(x)) == x
加密/解密、压缩/解压缩
参照验证（Oracle）
new_impl(x) == reference(x)
优化、重构
易验证性（Easy to Verify）
is_sorted(sort(x))
复杂算法
无异常（No Exception）有效输入下无崩溃基础属性
强度层级（从弱到强）： 无异常 → 类型保留 → 不变量 → 幂等性 → 往返一致性

Decision Tree

决策树

Based on the current task, read the appropriate section:
TASK: Writing new tests
  → Read [{baseDir}/references/generating.md]({baseDir}/references/generating.md) (test generation patterns and examples)
  → Then [{baseDir}/references/strategies.md]({baseDir}/references/strategies.md) if input generation is complex

TASK: Designing a new feature
  → Read [{baseDir}/references/design.md]({baseDir}/references/design.md) (Property-Driven Development approach)

TASK: Code is difficult to test (mixed I/O, missing inverses)
  → Read [{baseDir}/references/refactoring.md]({baseDir}/references/refactoring.md) (refactoring patterns for testability)

TASK: Reviewing existing PBT tests
  → Read [{baseDir}/references/reviewing.md]({baseDir}/references/reviewing.md) (quality checklist and anti-patterns)

TASK: Need library reference
  → Read [{baseDir}/references/libraries.md]({baseDir}/references/libraries.md) (PBT libraries by language, includes smart contract tools)
根据当前任务，阅读相应章节：
TASK: Writing new tests
  → Read [{baseDir}/references/generating.md]({baseDir}/references/generating.md) (test generation patterns and examples)
  → Then [{baseDir}/references/strategies.md]({baseDir}/references/strategies.md) if input generation is complex

TASK: Designing a new feature
  → Read [{baseDir}/references/design.md]({baseDir}/references/design.md) (Property-Driven Development approach)

TASK: Code is difficult to test (mixed I/O, missing inverses)
  → Read [{baseDir}/references/refactoring.md]({baseDir}/references/refactoring.md) (refactoring patterns for testability)

TASK: Reviewing existing PBT tests
  → Read [{baseDir}/references/reviewing.md]({baseDir}/references/reviewing.md) (quality checklist and anti-patterns)

TASK: Need library reference
  → Read [{baseDir}/references/libraries.md]({baseDir}/references/libraries.md) (PBT libraries by language, includes smart contract tools)

How to Suggest PBT

如何推荐PBT

When you detect a high-value pattern while writing tests, offer PBT as an option:
"I notice 
encode_message
/
decode_message
is a serialization pair. Property-based testing with a roundtrip property would provide stronger coverage than example tests. Want me to use that approach?"
If codebase already uses a PBT library (Hypothesis, fast-check, proptest, Echidna), be more direct:
"This codebase uses Hypothesis. I'll write property-based tests for this serialization pair using a roundtrip property."
If user declines, write good example-based tests without further prompting.
当你在编写测试时检测到高价值模式，主动提供PBT作为选项：
"我注意到
encode_message
/
decode_message
是一个序列化配对。基于属性的测试的往返一致性属性会比示例测试提供更强的覆盖范围。需要我采用这种方法吗？"
如果代码库已使用PBT库（Hypothesis、fast-check、proptest、Echidna），则直接说明：
"此代码库使用Hypothesis。我将为这个序列化配对编写基于属性的测试，采用往返一致性属性。"
如果用户拒绝，则编写优质的基于示例的测试，无需进一步提示。

When NOT to Use PBT

何时不使用PBT

  • Simple CRUD without complex validation
  • UI/presentation logic
  • Integration tests requiring complex external setup
  • Prototyping where requirements are fluid
  • User explicitly requests example-based tests only
  • 无复杂验证的简单CRUD操作
  • UI/展示逻辑
  • 需要复杂外部设置的集成测试
  • 需求不明确的原型开发
  • 用户明确要求仅使用基于示例的测试

Red Flags

注意事项

  • Recommending trivial getters/setters
  • Missing paired operations (encode without decode)
  • Ignoring type hints (well-typed = easier to test)
  • Overwhelming user with candidates (limit to top 5-10)
  • Being pushy after user declines
  • 不要推荐为简单的getter/setter编写PBT
  • 不要遗漏配对操作（只有encode没有decode的情况）
  • 不要忽略类型提示（类型定义完善的代码更易测试）
  • 不要向用户推荐过多候选方案（限制在5-10个以内）
  • 用户拒绝后不要继续推销