Usage

This chapter explains how to use Rendezvous in different situations. By the end, you'll know when and how to use its features effectively.

What's Inside

Running Rendezvous

• Positional Arguments
• Options
• Summary

Understanding Rendezvous

• Example

The Rendezvous Context

• How the Context Works
• Using the context to write invariants

Discarding Property-Based Tests

• Discard Function
• In-Place Discarding
• Discarding summary

Custom Manifest Files

• Why use a custom manifest?
• A test double for sbtc-registry
• A Custom Manifest File
• How It Works

Running Rendezvous

To run Rendezvous, use the following command:

rv <path-to-clarinet-project> <contract-name> <type> [--seed] [--runs] [--dial]

Let's break down each part of the command.

Positional Arguments

Consider this example Clarinet project structure:

root
├── Clarinet.toml
├── contracts
│   ├── contract.clar
│   ├── contract.tests.clar
└── settings
    └── Devnet.toml

1. Path to the Clarinet Project

The <path-to-clarinet-project> is the relative or absolute path to the root directory of the Clarinet project. This is where the Clarinet.toml file exists. It is not the path to the Clarinet.toml file itself.

For example, if you're in the parent directory of root, the correct relative path would be:

rv ./root <contract-name> <type>

2. Contract Name

The <contract-name> is the name of the contract to be tested, as defined in Clarinet.toml.

For example, if Clarinet.toml contains:

[contracts.contract]
path = "contracts/contract.clar"

To test the contract named contract, you would run:

rv ./root contract <type>

3. Testing Type

The <type> argument specifies the testing technique to use. The available options are:

• test – Runs property-based tests.
• invariant – Runs invariant tests.

For a deeper understanding of these techniques and when to use each, see Testing Methodologies.

Running property-based tests

To run property-based tests for the contract contract, ensure that your test functions are defined in:

./root/contracts/contract.tests.clar

Then, execute:

rv ./root contract test

This tells Rendezvous to:

• Load the Clarinet project located in ./root.
• Target the contract named contract as defined in Clarinet.toml by executing property-based tests defined in contract.tests.clar.

Running invariant tests

To run invariant tests for the contract contract, ensure that your invariant functions are defined in:

./root/contracts/contract.tests.clar

To run invariant tests, use:

rv ./root contract invariant

With this command, Rendezvous will:

• Randomly execute public function calls in the contract contract.
• Randomly check the defined invariants to ensure the contract's internal state remains valid.

If an invariant check fails, it means the contract's state has deviated from expected behavior, revealing potential bugs.

Options

Rendezvous also provides additional options to customize test execution:

1. Customizing the Number of Runs

By default, Rendezvous runs 100 test iterations. You can modify this using the --runs option:

rv root contract test --runs=500

This increases the number of test cases to 500.

2. Replaying a Specific Sequence of Events

To reproduce a previous test sequence, you can use the --seed option. This ensures that the same random values are used across test runs:

rv root contract test --seed=12345

How to Find the Replay Seed

When Rendezvous detects an issue, it includes the seed needed to reproduce the test in the failure report. Here’s an example of a failure report with the seed:

Error: Property failed after 2 tests.
Seed : 426141810

Counterexample:
...

What happened? Rendezvous went on a rampage and found a weak spot:
...

In this case, the seed is 426141810. You can use it to rerun the exact same test scenario:

rv root contract test --seed=426141810

3. Using Dialers

Dialers allow you to define pre- and post-execution functions using JavaScript during invariant testing. To use a custom dialer file, run:

rv root contract invariant --dial=./custom-dialer.js

A good example of a dialer can be found in the Rendezvous repository, within the example Clarinet project, inside the sip010.js file.

In that file, you’ll find a post-dialer designed as a sanity check for SIP-010 token contracts. It ensures that the transfer function correctly emits the required print event containing the memo, as specified in SIP-010.

How Dialers Work

During invariant testing, Rendezvous picks up dialers when executing public function calls:

• Pre-dialers run before each public function call.
• Post-dialers run after each public function call.

Both have access to an object containing:

• selectedFunction – The function being executed.
• functionCall – The result of the function call (undefined for pre-dialers).
• clarityValueArguments – The generated Clarity values used as arguments.

Example: Post-Dialer for SIP-010

Below is a post-dialer that verifies SIP-010 compliance by ensuring that the transfer function emits a print event containing the memo.

async function postTransferSip010PrintEvent(context) {
  const { selectedFunction, functionCall, clarityValueArguments } = context;

  // Ensure this check runs only for the "transfer" function.
  if (selectedFunction.name !== "transfer") return;

  const functionCallEvents = functionCall.events;
  const memoParameterIndex = 3; // The memo parameter is the fourth argument.

  const memoGeneratedArgumentCV = clarityValueArguments[memoParameterIndex];

  // If the memo argument is `none`, there's nothing to validate.
  if (memoGeneratedArgumentCV.type === 9) return;

  // Ensure the memo argument is an option (`some`).
  if (memoGeneratedArgumentCV.type !== 10) {
    throw new Error("The memo argument must be an option type!");
  }

  // Convert the `some` value to hex for comparison.
  const hexMemoArgumentValue = cvToHex(memoGeneratedArgumentCV.value);

  // Find the print event in the function call events.
  const sip010PrintEvent = functionCallEvents.find(
    (ev) => ev.event === "print_event"
  );

  if (!sip010PrintEvent) {
    throw new Error(
      "No print event found. The transfer function must emit the SIP-010 print event containing the memo!"
    );
  }

  const sip010PrintEventValue = sip010PrintEvent.data.raw_value;

  // Validate that the emitted print event matches the memo argument.
  if (sip010PrintEventValue !== hexMemoArgumentValue) {
    throw new Error(
      `Print event memo value does not match the memo argument: ${hexMemoArgumentValue} !== ${sip010PrintEventValue}`
    );
  }
}

This dialer ensures that any SIP-010 token contract properly emits the memo print event during transfers, helping to catch deviations from the standard.

Summary

Understanding Rendezvous

Rendezvous makes property-based tests and invariant tests first-class. Tests are written in the same language as the system under test. This helps developers master the contract language. It also pushes boundaries—programmers shape their thoughts first, then express them using the language's tools.

When Rendezvous initializes a Simnet session using a given Clarinet project, it does not modify any contract listed in Clarinet.toml—except for the target contract. During testing, Rendezvous updates the target contract by merging:

1. The original contract source code
2. The test contract (which includes property-based tests and invariants)
3. The Rendezvous context, which helps track function calls and execution details

Example

Let’s say we have a contract named checker with the following source:

;; checker.clar

(define-public (check-it (flag bool))
  (if flag (ok 1) (err u100))
)

And its test contract, checker.tests:

;; checker.tests.clar

(define-public (test-1)
  (ok true)
)

(define-read-only (invariant-1)
  true
)

When Rendezvous runs the tests, it automatically generates a modified contract that includes the original contract, the tests, and an additional context for tracking execution. The final contract source deployed in the Simnet session will look like this:

(define-public (check-it (flag bool))
  (if flag (ok 1) (err u100))
)

(define-map context (string-ascii 100) {
    called: uint
    ;; other data
  }
)

(define-public (update-context (function-name (string-ascii 100)) (called uint))
  (ok (map-set context function-name {called: called}))
)

(define-public (test-1)
  (ok true)
)

(define-read-only (invariant-1)
  true
)

While the original contract source and test functions are familiar, the context is new. Let's take a closer look at it.

The Rendezvous Context

Rendezvous introduces a context to track function calls and execution details during testing. This allows for better tracking of execution details and invariant validation.

How the Context Works

When a function is successfully executed during a test, Rendezvous records its execution details in a Clarity map. This map helps track how often specific functions are called successfully and can be extended for additional tracking in the future.

Here’s how the context is structured:

(define-map context (string-ascii 100) {
    called: uint
    ;; Additional fields can be added here
})

(define-public (update-context (function-name (string-ascii 100)) (called uint))
  (ok (map-set context function-name {called: called}))
)

Breaking it down

• context map → Keeps track of execution data, storing how many times each function has been called successfully.
• update-context function → Updates the context map whenever a function executes, ensuring accurate tracking.

Using the context to write invariants

By tracking function calls, the context helps invariants ensure stronger correctness guarantees. For example, an invariant can verify that a counter stays above zero by checking the number of successful increment and decrement calls.

Example invariant using the context

(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)
    )
  )
)

By embedding execution tracking into the contract, Rendezvous enables more effective smart contract testing, making it easier to catch bugs and check the contract correctness.

Discarding Property-Based Tests

Rendezvous generates a wide range of inputs, but not all inputs are valid for every test. To skip tests with invalid inputs, there are two approaches:

Discard Function

A separate function determines whether a test should run.

Rules for a Discard Function:

• Must be read-only.
• Name must match the property test function, prefixed with "can-".
• Parameters must mirror the property test’s parameters.
• Must return true only if inputs are valid, allowing the test to run.

Discard function example

(define-read-only (can-test-add (n uint))
  (> n u1)  ;; Only allow tests where n > 1
)

(define-public (test-add (n uint))
  (let
    ((counter-before (get-counter)))
    (try! (add n))
    (asserts! (is-eq (get-counter) (+ counter-before n)) (err u403))
    (ok true)
  )
)

Here, can-test-add ensures that the test never executes for n <= 1.

In-Place Discarding

Instead of using a separate function, the test itself decides whether to run. If the inputs are invalid, the test returns (ok false), discarding itself.

In-place discarding example

(define-public (test-add (n uint))
  (let
    ((counter-before (get-counter)))
    (ok
      (if
        (<= n u1)  ;; If n <= 1, discard the test.
        false
        (begin
          (try! (add n))
          (asserts! (is-eq (get-counter) (+ counter-before n)) (err u403))
          true
        )
      )
    )
  )
)

In this case, if n <= 1, the test discards itself by returning (ok false), skipping execution.

Discarding summary

In general, in-place discarding is preferred because it keeps test logic together and is easier to maintain. Use a discard function only when it's important to prevent execution entirely.

Custom Manifest Files

Some smart contracts need a special Clarinet.toml file to allow Rendezvous to create state transitions in the contract. Rendezvous supports this feature by automatically searching for Clarinet-<target-contract-name>.toml first. This allows you to use test doubles while keeping tests easy to manage.

Why use a custom manifest?

A great example is the sBTC contract suite.

For testing the sbtc-token contract, the sbtc-registry authorization function is-protocol-caller is too restrictive. Normally, it only allows calls from protocol contracts, making it impossible to directly test certain state transitions in sbtc-token.

To work around this, you need two things:

A test double for sbtc-registry

You can create an sbtc-registry test double called sbtc-registry-double.clar:

;; contracts/sbtc-registry-double.clar

...

(define-constant deployer tx-sender)

;; Allows the deployer to act as a protocol contract for testing
(define-read-only (is-protocol-caller (contract-flag (buff 1)) (contract principal))
  (begin
    (asserts! (is-eq tx-sender deployer) (err u1234567))  ;; Enforces deployer check
    (ok true)
  )
)

...

This loosens the restriction just enough for testing by allowing the deployer to act as a protocol caller, while still enforcing an access check.

A Custom Manifest File

Next, create Clarinet-sbtc-token.toml to tell Rendezvous to use the test double only when targeting sbtc-token:

# Clarinet-sbtc-token.toml

...

[contracts.sbtc-registry]
path = 'contracts/sbtc-registry-double.clar'
clarity_version = 3
epoch = 3.0

...

How It Works

• When testing sbtc-token, Rendezvous first checks if Clarinet-sbtc-token.toml exists.
• If found, it uses this file to initialize Simnet.
• If not, it falls back to the standard Clarinet.toml.

This ensures that the test double is only used when testing sbtc-token, keeping tests realistic while allowing necessary state transitions.