Testing Methodologies

Rendezvous offers two complementary testing methodologies: property-based testing and invariant testing. This chapter explains both approaches and when to use each.

Property-Based Testing vs. Invariant Testing

Understanding Property-Based Testing

Property-based testing verifies that specific properties of your code hold true across a wide range of inputs. Instead of manually crafting test cases, you define a property, and Rendezvous automatically generates test inputs.

Key Concepts

• Properties: Universal truths about your functions (e.g., "reversing a list twice returns the original list")
• Generators: Automatic creation of random test inputs based on function signatures¹
• Shrinking: Finding the simplest failing input for easier debugging
• Discarding: Skipping invalid inputs to focus on meaningful test scenarios

Best For: Functions that don't modify state (read-only), operations with mathematical properties, functions with well-defined behaviors across varied inputs

Example Property-Based Test

Here's a simple example of a property-based test that verifies the "reversing a list twice returns the original list" property:

(define-public (test-reverse-uint (seq (list 127 uint)))
  (begin
    (asserts!
      (is-eq seq (reverse-uint (reverse-uint seq)))
      ERR_ASSERTION_FAILED
    )
    (ok true)
  )
)

This test demonstrates the key conventions for property-based tests in Rendezvous:

• Function name starts with test-
• Function is declared as public
• Test passes when it returns (ok true)
• Test would be discarded if it returned (ok false)
• Test fails if it returns an error or throws an exception

In this example, seq is automatically generated by Rendezvous with different random values for each test run. The property being tested is that applying reverse-uint twice to any list should return the original list.

Understanding Invariant Testing

Invariant testing ensures that certain conditions about your contract's state remain true regardless of which operations are performed in which order.

Key Concepts

• Invariants: Conditions that must always hold true about your contract's state
• State transitions: Changes triggered by function calls
• Function sequences: Random series of operations to test state consistency
• Context tracking: Recording function call history to enable sophisticated checks

Best For: State management, complex transitions, maintaining relationships between variables, ensuring safety properties

Example Invariant Test

Here's an example of an invariant test that ensures a counter remains positive when increments exceed decrements:

(define-read-only (invariant-counter-gt-zero)
  (let
    (
      (increment-num-calls
        (default-to u0 (get called (map-get? context "increment")))
      )
      (decrement-num-calls
        (default-to u0 (get called (map-get? context "decrement")))
      )
    )
    (if
      (<= increment-num-calls decrement-num-calls)
      true
      (> (var-get counter) u0)
    )
  )
)

This test demonstrates the key conventions for invariant tests in Rendezvous:

• Function name starts with invariant-
• Function is declared as read-only (not public)
• Function returns a boolean value (true if the invariant holds, false if violated)
• The test can use the special context map to access execution history

In this example, the invariant verifies that if increment has been called more times than decrement, the counter should be greater than zero. Rendezvous will randomly call functions in your contract and check this invariant between calls to ensure the contract's state remains valid regardless of the sequence of operations.

Testing from Inside vs. Outside

Testing from Inside

Writing tests in Clarity alongside your contract code provides:

• Direct access to internal state and private functions
• Natural expression of contract properties in the same language

Testing from Outside

Using external tools (like TypeScript libraries) enables:

• Testing integration between multiple contracts
• Examining transaction-level concerns like events
• Using pre- and post-execution functions (see Dialers, Chapter 6)

Practical Testing Strategy

For most contracts, a combined approach yields the best results:

1. Use property-based tests for:

   • Pure functions (read-only operations)
   • Functions with mathematical properties
   • Validating behavior across many input variations

2. Use invariant tests for:

   • Verifying state consistency
   • Testing relationships between state variables
   • Ensuring contracts can't enter invalid states

3. Consider external testing when you need to:

   • Verify event emissions
   • Test interactions across multiple contracts
   • Use pre/post-execution hooks via dialers

By choosing the right testing approach for each aspect of your contract, you can build a comprehensive test suite that ensures correctness under all conditions.

1. Rendezvous currently uses a probabilistic approach to automatically generate inputs based on function signatures. In future versions, there may be support for fine-grained control over the scope of these inputs (which would also relate to the shrinking process). Additionally, if symbolic execution capabilities become available for the Clarity VM, Rendezvous could potentially support formal verification techniques that would exhaustively check all possible execution paths rather than using random sampling. ↩