Foreword

Rendezvous originated from an idea conceived in 20221, built upon over a decade of experience in developing and contributing to unit testing and property-based testing tools. This initiative was further driven by the numerous exploits and hacks that have afflicted the crypto industry over the years.

The need for robust testing frameworks in smart contract development cannot be overstated. As blockchain technology continues to evolve, the security implications of smart contracts become increasingly complex. Rendezvous (rv) was created to address these challenges by providing a specialized fuzzing tool for Clarity smart contracts.

Acknowledgements

The idea behind Rendezvous originates from several inspiring sources:

  • John Hughes: For his pioneering work in property-based testing and the creation of QuickCheck, which laid the foundation for modern property testing. His paper, "Testing the Hard Stuff and Staying Sane"2, has been a significant inspiration for our approach in rv.

  • Jude Nelson: For the valuable insights and methods presented in poxl3, demonstrating a way to write tests in Clarity.

  • Nicolas Dubien: For creating fast-check4, the underlying property-based testing framework we currently use in Rendezvous.

  • Jacob Stanley: For his lasting inspiration and contributions to property-based testing and the Hedgehog library5. Jacob's legacy and influence remain a guiding force in our work.

  • Trail of Bits: For creating Echidna6, which initially utilized Hedgehog, furthering the development of smart contract fuzzers.

  • Łukasz Nowicki: For the initial discussions and ideas on this topic in 2022.

We are deeply grateful to the Stacks Open Internet Foundation for supporting our work and providing crucial assistance, and to the open-source community for their continuous support and contributions.

1

Heterogeneous Clarinet Test-Suites: https://github.com/hirosystems/clarinet/issues/398

2

Hughes, J. (2004). "Testing the Hard Stuff and Staying Sane". In Proceedings of the ACM SIGPLAN Workshop on Haskell (Haskell '04).

Introduction

Rendezvous (rv) is a fuzzer designed specifically for Clarity smart contracts. As the name suggests, it serves as a meeting point between your contracts and potential vulnerabilities, allowing you to discover and address issues before they can be exploited in production.

The tool focuses on two primary testing methodologies:

  1. Property-based testing: Verifying that specific properties of your contract hold true across a wide range of possible inputs.
  2. Invariant testing: Ensuring that certain conditions about your contract's state remain true regardless of the sequence of operations performed.

Why You Need Rendezvous

Smart contracts are immutable once deployed, making post-deployment fixes expensive or impossible. Traditional testing methods often fall short in discovering edge cases that might lead to security vulnerabilities or unexpected behavior. Rendezvous addresses these challenges by:

  • Exploring the unexpected: Through fuzzing, Rendezvous generates and tests a diverse range of inputs that developers might not consider during manual testing.
  • Finding edge cases: By repeatedly testing your contract with varying inputs, it can discover boundary conditions and rare scenarios that could cause issues.
  • Validating invariants: It ensures that your contract's core properties remain consistent regardless of the operations performed.
  • Helping reduce impedance mismatch: By testing in Clarity when possible while using TypeScript when needed (e.g., for events). Rendezvous dialers (Chapter 6) bridge the gap.

Project Philosophy

Rendezvous is built on the principles of simplicity, robustness, and developer-friendliness. We value:

  • Clarity first: Testing should happen in the same language as implementation whenever possible.
  • Simple, focused tests: Each test should verify one thing and do it well.
  • Community-driven development: Contributions from the community are essential to the project's success.

As noted in our contributing guidelines, we believe in handcrafted code with a purpose. Each file in the project is maintained with care, focusing on readability and maintainability. Our coding style emphasizes simplicity, clear American English, and concise logic.

Project Structure

Rendezvous integrates seamlessly with Clarinet projects, looking for test files alongside your contract implementations:

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

This structure allows for a natural workflow where tests live close to the code they're testing, making it easier to maintain both in tandem.

In the following chapters, we'll explore why testing directly in Clarity is beneficial, the testing methodologies employed by Rendezvous, how to install and use the tool, and examples of effective testing patterns.

Why Test Clarity Code Directly

Programming In vs. Into a Language

Steve McConnell's Code Complete discusses the concept of "programming in vs. into a language." This distinction is particularly relevant for Clarity smart contract development:

  • Programming into a language: Thinking in one language (like TypeScript) and then translating those thoughts into another language (like Clarity). This approach often leads to code that doesn't fully leverage the target language's strengths.

  • Programming in a language: Thinking directly in the target language, utilizing its unique features and idioms to express solutions naturally. This results in more idiomatic, efficient, and maintainable code.

For Clarity to be treated as a first-class citizen throughout the development lifecycle, we need tools that allow us to think and test directly in Clarity.

Eliminating the Marshaling Overhead

When testing Clarity contracts using TypeScript or other languages, developers must constantly marshal (convert) between different data representations:

  1. Data conversion complexity: Transforming TypeScript data structures to their Clarity equivalents introduces complexity and potential errors.
  2. Type mismatches: Subtle differences in how types work between languages can lead to unexpected behavior.
  3. Mental context switching: Developers must constantly switch between different language paradigms.

By testing directly in Clarity, these issues are eliminated. The same language is used throughout the development process, ensuring consistency and reducing cognitive overhead.

Benefits of Native Clarity Testing

Testing Clarity contracts directly in Clarity offers several significant advantages:

1. True language fidelity

Tests written in Clarity operate under the exact same constraints, rules, and behavior as the production code. There's no risk of tests passing in one environment but failing in another due to language differences.

2. Enhanced developer understanding

By writing tests in Clarity, developers deepen their understanding of the language. This leads to better contract design and implementation, as developers become more familiar with Clarity's strengths and limitations.

3. Direct access to contract internals

Clarity tests can directly access functions and state within contracts, enabling more thorough testing of the invariants without requiring public exposure solely for testing purposes.

4. Reduced testing infrastructure

Testing directly in Clarity reduces the need for complex testing harnesses that bridge between different languages and environments.

Complementary Testing Approaches

While testing directly in Clarity offers many benefits, the Clarinet SDK's TypeScript-based testing capabilities represent a powerful and essential part of a comprehensive testing strategy. Both approaches have their strengths and are complementary rather than competitive.

When TypeScript Testing Excels

The Clarinet SDK provides robust TypeScript-based testing capabilities that are particularly valuable for:

  • Testing from the outside: Simulating how external applications would interact with your contracts, including reading events emitted by contracts (which is why Rendezvous offers the dialers feature as a bridge)
  • User interface testing: Validating how frontend applications interact with contracts
  • Complex orchestration scenarios: Setting up sophisticated test environments with multiple actors and interactions

Finding the Right Balance

Rather than choosing one approach exclusively, consider using both in a complementary fashion:

  • Use Clarity testing with Rendezvous for property-based tests, invariant verification, and internal function validation
  • Use TypeScript testing with Clarinet SDK for external interaction validation, event verification, and complex scenario testing

This combined approach leverages the strengths of both tools to create a more comprehensive testing strategy.

By embracing Clarity as a first-class testing language, Rendezvous enables developers to write more natural, effective, and comprehensive tests for their smart contracts.

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

Property-Based TestingInvariant Testing
Tests individual functionsTests system-wide properties
Generates random inputs for specific functionsGenerates random sequences of function calls
Verifies function behavior is correct for all inputsVerifies state remains valid after any operation sequence
Helps find edge cases in specific functionsHelps find unexpected interactions between functions

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 signatures1
  • 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.

Installation

This chapter covers how to install Rendezvous and set up your environment for effective Clarity contract testing.

What's Inside

Prerequisites

Standard Installation

Global Installation

Development/Contribution Installation

Verifying Your Installation

Project Setup

Troubleshooting Installation Issues

Uninstalling Rendezvous

Next Steps

Prerequisites

Before installing Rendezvous, ensure you have the following prerequisites:

  • Node.js: Rendezvous supports Node.js versions 18, 20, and 22. Other versions may work but are untested.
  • Clarinet: You need a Clarinet project to use Rendezvous. If you don't have Clarinet installed, follow the official Clarinet installation guide.

Standard Installation

To install Rendezvous as a dependency in your project, use npm:

npm install @stacks/rendezvous

This will add Rendezvous to your project's node_modules and update your package.json.

Global Installation

If you prefer to install Rendezvous globally so it's available across all your projects, use:

npm install -g @stacks/rendezvous

With a global installation, you can run the rv command from any directory without prefixing it with npx.

Development/Contribution Installation

If you want to contribute to Rendezvous or run it from source:

  1. Clone the repository:

    git clone https://github.com/stacks-network/rendezvous.git

  2. Navigate to the project directory:

    cd rendezvous

  3. Install dependencies:

    npm install

  4. Build the project:

    npm run build

  5. Link the package globally (optional):

    npm link

Verifying Your Installation

After installing Rendezvous, verify that it's working correctly:

npx rv --help

Or if installed globally:

rv --help

You should see the current version of Rendezvous displayed.

Project Setup

For Rendezvous to work properly, your Clarinet project should have the following structure:

my-project/
├── Clarinet.toml
├── contracts/
│   ├── my-contract.clar       # Your contract implementation.
│   ├── my-contract.tests.clar # Tests for your contract.
└── settings/
    └── Devnet.toml

Key points to note:

  1. The test file (my-contract.tests.clar) must be in the same directory as the contract it tests.
  2. The test file name must match the pattern {contract-name}.tests.clar.
  3. A valid Clarinet.toml file must exist at the project root.

Troubleshooting Installation Issues

Common Issues and Solutions

Node.js Version Conflicts

If you encounter errors related to Node.js versions, ensure you're using a supported version (18, 20, or 22).

node --version

Package Not Found

If the rv command isn't found after installation:

  1. For local installation, use npx rv instead of just rv.
  2. For global installation, ensure your npm global binaries directory is in your PATH.

Clarinet Project Not Recognized

If Rendezvous cannot find your Clarinet project:

  1. Ensure you're running the command from the correct directory.
  2. Verify that your Clarinet.toml file exists and is properly formatted.
  3. Check that your contract and test files are correctly named and located.

Permission Issues

If you encounter permission errors when installing globally, consider using a solution like nvm to manage Node.js installations without requiring elevated permissions.

Uninstalling Rendezvous

If you need to uninstall Rendezvous, the process depends on how you initially installed it.

Removing a Local Installation

To remove Rendezvous from a specific project:

npm uninstall @stacks/rendezvous

This will remove the package from your project's node_modules directory and update your package.json.

Removing a Global Installation

To remove a globally installed version of Rendezvous:

npm uninstall -g @stacks/rendezvous

Removing a Development Installation

If you installed from source:

  1. If you linked the package globally, unlink it first:

    npm unlink -g @stacks/rendezvous

  2. You can then remove the cloned repository directory:

    rm -rf path/to/rendezvous

Next Steps

Now that you have Rendezvous installed, you're ready to start testing your Clarity contracts. In the next chapter, we'll cover how to use Rendezvous effectively with detailed usage examples.

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

Understanding Rendezvous

The Rendezvous Context

Discarding Property-Based Tests

Custom Manifest Files

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

Argument/OptionDescriptionExample
<path-to-clarinet-project>Path to the Clarinet project (where Clarinet.toml is located).rv root contract test
<contract-name>Name of the contract to test (as in Clarinet.toml).rv root contract test
<type>Type of test (test for property-based tests, invariant for invariant tests).rv root contract test
--runs=<num>Sets the number of test iterations (default: 100).rv root contract test --runs=500
--seed=<num>Uses a specific seed for reproducibility.rv root contract test --seed=12345
--dial=<file>Loads JavaScript dialers from a file for pre/post-processing.rv root contract test --dial=./custom-dialer.js

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

Discard MechanismWhen to Use
Discard FunctionWhen skipping execution before running the test is necessary.
In-Place DiscardingWhen discarding logic is simple and part of the test itself.

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.

Examples

The Rendezvous repo has a Clarinet project, example, that shows how to test Clarity smart contracts natively. Each contract, like xyz.clar, has a matching test contract, xyz.tests.clar.

What's Inside

The counter Contract

The cargo Contract

The reverse Contract

The slice Contract

The counter Contract

The counter contract is a simple Clarity example found in the example Clarinet project. It has no known vulnerabilities. However, to see how Rendezvous works, we can introduce a bug into the increment function. This bug resets the counter to 0 when the counter value exceeds 1000. The faulty increment function is already included (but commented out) in the counter contract:

(define-public (increment)
  (let
    (
      (current-counter (var-get counter))
    )
    (if
      (> current-counter u1000) ;; Introduce a bug for large values.
      (ok (var-set counter u0)) ;; Reset counter to zero if it exceeds 1000.
      (ok (var-set counter (+ current-counter u1)))
    )
  )
)

To test the buggy version of the contract, replace the valid increment function with the faulty version. Then, you can write Clarity invariants and property-based tests to detect the issue.

Invariants

One invariant that can detect the introduced bug is:

(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 invariant uses the context utility from Rendezvous, described in the previous chapter. It establishes a fundamental rule for the counter contract:

If, at the time of the check, the increment function has been called successfully more times than decrement, the counter value should be greater than 0.

Invariant logic

increment-num-calls ≤ decrement-num-calls:

  • The invariant automatically holds.
  • This case means decrements occurred at least as many times as increments, so the invariant does not enforce any condition.

increment-num-calls > decrement-num-calls:

  • The invariant asserts that counter > u0.
  • This ensures that, despite more increment calls, the counter remains positive.

Checking the invariants

To check the counter contract's invariants, run:

rv ./example counter invariant

Using this command, Rendezvous will randomly execute public function calls in the counter contract while periodically checking the invariant. If the invariant fails, it indicates that the contract's internal state has deviated from expected behavior, exposing the bug in the faulty increment function.

Property-Based Tests

Another way to detect the introduced bug is by writing this property-based test:

(define-public (test-increment)
  (let
    (
      (counter-before (get-counter))
    )
    (unwrap-panic (increment))
    (asserts! (is-eq (get-counter) (+ counter-before u1)) (err u404))
    (ok true)
  )
)

This test is a property-based test, where a property (a truth, or characteristic) of the increment function is tested across different inputs.

The counter should always increase by 1 after a successful call to increment.

If the test fails, it means the counter did not increment as expected, revealing unintended behavior such as the counter resetting to 0.

Test logic

  1. Record the counter value before calling increment.
  2. Call increment and ensure it does not fail.
  3. Check that the new counter value equals the previous value +1.
    • If this condition does not hold, the test fails with error u404.
    • This catches unexpected changes, such as the counter resetting.

Checking the properties

To run Rendezvous property-based tests against the counter contract, use:

rv ./example counter test

Using this command, Rendezvous will randomly select and execute property-based tests from the counter's test contract. This process will detect the bug in the faulty increment function. However, if the test contract contains only test-increment, the number of runs must be increased. By default, Rendezvous executes 100 runs, which is not sufficient to expose the issue.

To make sure you always catch the bug, set the --runs option to something higher than 1001, e.g. 1002:

rv ./example counter test --runs=1002

This ensures that enough test cases are executed to trigger the counter reset condition.

The cargo Contract

The cargo contract is a decentralized shipment tracker found in the example Clarinet project. Initially, it contained a bug where the last-shipment-id variable was not updated when creating a new shipment. This bug has been fixed, but you can re-introduce it to see how Rendezvous detects it:

(define-public (create-new-shipment (starting-location (string-ascii 25))
                                    (receiver principal))
  (let
    (
      (new-shipment-id (+ (var-get last-shipment-id) u1))
    )
    ;; #[filter(starting-location, receiver)]
    (map-set shipments new-shipment-id {
      location: starting-location,
      status: "In Transit",
      shipper: tx-sender,
      receiver: receiver
    })

    ;; The following line fixes the bug in the original implementation.
    ;; Comment out this line to re-introduce the bug.
    ;; (var-set last-shipment-id new-shipment-id)
    (ok "Shipment created successfully")
  )
)

To test the buggy version of the contract, comment out the line that updates last-shipment-id. Then, use invariants and property-based tests to detect the issue.

Invariants

One invariant that can detect the introduced bug is:

(define-read-only (invariant-last-shipment-id-gt-0-after-create-shipment)
  (let
    (
      (create-shipment-num-calls
        (default-to u0 (get called (map-get? context "create-new-shipment")))
      )
    )
    (if
      (is-eq create-shipment-num-calls u0)
      true
      (> (var-get last-shipment-id) u0)
    )
  )
)

This invariant uses the context utility from Rendezvous, described in the previous chapter. It enforces a fundamental rule of the cargo contract:

If at least one shipment has been created, the last-shipment-id must be greater than 0.

Invariant logic

create-shipment-num-calls = 0:

  • The invariant holds automatically (no shipments created, so no condition to check).

create-shipment-num-calls > 0:

  • The invariant asserts that last-shipment-id > 0.
  • If this check fails, it means last-shipment-id was not updated after creating a shipment, exposing the bug.

Checking the invariants

To run Rendezvous invariant testing against the cargo contract, use:

rv ./example cargo invariant

Using this command, Rendezvous will randomly execute public function calls in the cargo contract while periodically checking the invariant. If the invariant fails, it signals that last-shipment-id was not updated as expected, revealing the bug.

Property-Based Tests

A property-based test that can detect the introduced bug is:

(define-public (test-get-last-shipment-id
    (starting-location (string-ascii 25))
    (receiver principal)
  )
  (let
    ((shipment-id-before (get-last-shipment-id)))
    (unwrap!
      (create-new-shipment starting-location receiver)
      ERR_CONTRACT_CALL_FAILED
    )
    ;; Verify the last shipment ID is incremented by 1.
    (asserts!
      (is-eq (get-last-shipment-id) (+ u1 shipment-id-before))
      ERR_ASSERTION_FAILED
    )
    (ok true)
  )
)

This test follows a property-based testing approach, verifying a key property of create-new-shipment:

Creating a new shipment should always increment last-shipment-id by 1.

Test logic

  1. Record the current shipment ID before calling create-new-shipment.
  2. Call create-new-shipment, ensuring it does not fail.
  3. Verify that last-shipment-id has increased by 1.
    • If this check fails, it means last-shipment-id was not updated, exposing the bug.

Checking the properties

To run Rendezvous property-based tests against the cargo contract, use:

rv ./example cargo test

Using this command, Rendezvous will randomly select and execute property-based tests from the cargo's test contract. If test-get-last-shipment-id is the only test in the contract, Rendezvous will immediately detect the bug.

The reverse Contract

The reverse contract included in the example Clarinet project contains Clarity utilities for reversing lists of various types. Since it lacks public functions, invariant testing doesn’t apply. However, it serves as an ideal "Hello World" example for property testing using native Clarity—reversing a list twice should always return the original list.

Introducing a bug and detecting it with Rendezvous property-based tests is insightful, not just for finding the issue but for demonstrating the power of shrinking. Below is an example of how to introduce a bug into one of the reverse-uint private utilities:

(define-read-only (reverse-uint (seq (list 127 uint)))
 (reverse-list1 seq)
)

(define-private (reverse-list1 (seq (list 127 uint)))
  (fold reverse-redx-unsigned-list seq (list))
)

(define-private (reverse-redx-unsigned-list (item uint) (seq (list 127 uint)))
  (unwrap-panic
    (as-max-len?
      (concat (list item) seq)
      u4 ;; Introduces a bug by limiting max length incorrectly.
    )
  )
)

This bug reduces the maximum supported list length in a private function, leading to an unwrap failure runtime error when the list exceeds the new, incorrect limit.

Property-Based Tests

A property-based test that can detect the introduced bug is:

(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 follows a property-based testing approach, verifying the "Hello World" of property testing:

Reversing a list twice should always return the original list.

This test example accepts a parameter, which is randomly generated for each run.

Test logic

  1. Verify that reversing a passed list twice is always equal to the passed list.

Checking the properties

To run Rendezvous property-based tests against the reverse contract, use:

rv ./example reverse test

Shrinking at its finest

When a property-based test fails, Rendezvous automatically shrinks the failing test case to find the smallest possible counterexample. This process helps pinpoint the root cause of the bug by removing unnecessary complexity. Sample Rendezvous output showcasing the shrinking process:

₿     3494 Ӿ     3526   wallet_3 [FAIL] reverse test-reverse-uint [332420496,1825325546,120054597,1173935866,164214015] (runtime)
₿     3494 Ӿ     3527   wallet_3 [PASS] reverse test-reverse-uint [120054597,1173935866,164214015]
₿     3494 Ӿ     3529   wallet_3 [FAIL] reverse test-reverse-uint [0,1825325546,120054597,1173935866,164214015] (runtime)
₿     3494 Ӿ     3530   wallet_3 [PASS] reverse test-reverse-uint [120054597,1173935866,164214015]
₿     3494 Ӿ     3532   wallet_3 [PASS] reverse test-reverse-uint [0]
₿     3494 Ӿ     3533   wallet_3 [PASS] reverse test-reverse-uint [0,1173935866,164214015]
₿     3494 Ӿ     3534   wallet_3 [PASS] reverse test-reverse-uint [0,120054597,1173935866,164214015]
₿     3494 Ӿ     3535   wallet_3 [FAIL] reverse test-reverse-uint [0,0,120054597,1173935866,164214015] (runtime)
...
₿     3494 Ӿ     3537   wallet_3 [PASS] reverse test-reverse-uint [0,120054597,1173935866,164214015]
₿     3494 Ӿ     3538   wallet_3 [PASS] reverse test-reverse-uint [0]
₿     3494 Ӿ     3539   wallet_3 [PASS] reverse test-reverse-uint [0,1173935866,164214015]
₿     3494 Ӿ     3541   wallet_3 [PASS] reverse test-reverse-uint [0,0]
₿     3494 Ӿ     3542   wallet_3 [PASS] reverse test-reverse-uint [0,0,1173935866,164214015]
₿     3494 Ӿ     3543   wallet_3 [FAIL] reverse test-reverse-uint [0,0,0,1173935866,164214015] (runtime)
₿     3494 Ӿ     3545   wallet_3 [PASS] reverse test-reverse-uint [0,0,1173935866,164214015]
₿     3494 Ӿ     3546   wallet_3 [PASS] reverse test-reverse-uint [0]
₿     3494 Ӿ     3547   wallet_3 [PASS] reverse test-reverse-uint [0,1173935866,164214015]
₿     3494 Ӿ     3549   wallet_3 [PASS] reverse test-reverse-uint [0,0]
₿     3494 Ӿ     3550   wallet_3 [PASS] reverse test-reverse-uint [0,0,1173935866,164214015]
₿     3494 Ӿ     3551   wallet_3 [PASS] reverse test-reverse-uint [0,0,0]
₿     3494 Ӿ     3552   wallet_3 [PASS] reverse test-reverse-uint [0,0,0,164214015]
₿     3494 Ӿ     3553   wallet_3 [FAIL] reverse test-reverse-uint [0,0,0,0,164214015] (runtime)
₿     3494 Ӿ     3554   wallet_3 [PASS] reverse test-reverse-uint [0,0,164214015]
...
₿     3494 Ӿ     3562   wallet_3 [PASS] reverse test-reverse-uint [0,0,0,164214015]
₿     3494 Ӿ     3563   wallet_3 [PASS] reverse test-reverse-uint [0,0,0,0]
₿     3494 Ӿ     3564   wallet_3 [FAIL] reverse test-reverse-uint [0,0,0,0,0] (runtime)
₿     3494 Ӿ     3565   wallet_3 [PASS] reverse test-reverse-uint [0,0,0]
...
₿     3494 Ӿ     3574   wallet_3 [PASS] reverse test-reverse-uint [0,0,0,0]

Error: Property failed after 23 tests.
Seed : 869018352

Counterexample:
- Test Contract : reverse
- Test Function : test-reverse-uint (public)
- Arguments     : [[0,0,0,0,0]]
- Caller        : wallet_3
- Outputs       : {"type":{"response":{"ok":"bool","error":"int128"}}}

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

The test function "test-reverse-uint" returned:

    Call contract function error: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.reverse::test-reverse-uint((list u0 u0 u0 u0 u0)) -> Error calling contract function: Runtime error while interpreting ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.reverse: Runtime(UnwrapFailure, Some([FunctionIdentifier { identifier: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.reverse:test-reverse-uint" }, FunctionIdentifier { identifier: "_native_:special_asserts" }, FunctionIdentifier { identifier: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.reverse:reverse-uint" }, FunctionIdentifier { identifier: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.reverse:reverse-list1" }, FunctionIdentifier { identifier: "_native_:special_fold" }, FunctionIdentifier { identifier: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.reverse:reverse-redx-unsigned-list" }, FunctionIdentifier { identifier: "_native_:native_unwrap" }]))

To observe shrinking in action, pay attention to the FAIL logs. The minimal counterexample found is:

[0,0,0,0,0]

This is exactly what we were looking for! The bug we introduced is not related to the values in the list but to the list length.

By starting with larger, more complex failing test cases and shrinking down to a list of five zeros, Rendezvous reveals that the issue is with the number of elements, not their values. This insight is crucial—it tells us that our bug causes failures when the list length exceeds a certain threshold, not when specific numbers are present.

This is the power of shrinking in property-based testing: it strips away distractions and zeroes in on the core problem.

The slice Contract

The slice contract included in the example Clarinet project contains Clarity utilities for slicing lists of various types. Same as reverse, it lacks public functions, so invariant testing doesn’t apply. Using Rendezvous and property-based tests to test this contract will highlight the discarding mechanism of the Clarity property-based tests.

Let's introduce a bug in the slice contract:

(define-read-only (slice-uint (seq (list 127 uint)) (skip int) (n int))
  (begin
    (assert- (and (<= 0 skip) (<= skip 127)) "Out of bounds: skip")
    (assert- (and (<= 0 n) (<= n 127)) "Out of bounds: n")
    (slice-list1 seq skip n)
  )
)

(define-private (slice-list1
                 (seq (list 127 uint))
                 (skip int)
                 (n int))
  (begin
    (assert- (and (<= 0 skip) (<= skip 127)) "Out of bounds: skip")
    (assert- (and (<= 0 n) (<= n 127)) "Out of bounds: n")
    (let
      (
        (end
          (-
            (min-num-integer-integer (+ skip n) (to-int (len seq)))
            1
          )
        )
      )
      (if
        (>= end 1) ;; Introduce a bug that forces `skip` to always be 1 in this comparison.
        (let
          ((i (range-1-integer-integer skip end)))
          (map for-step-integer-list1 i (repeat127-list1 seq))
        )
        (list)
      )
    )
  )
)

The issue lies in the conditional check (>= end 1), where the skip value is hardcoded to 1 instead of using the user-provided input. This leads to unexpected behavior:

  • Lists that should include elements from earlier positions incorrectly skip the first item.
  • Certain inputs may trigger an unwrap failure runtime error when slicing beyond valid bounds.

Property-Based Tests

The following property-based test evaluates the correctness of slice-uint:

(define-public (test-slice-list-uint (seq (list 127 uint)) (skip int) (n int))
  (if
    ;; Discard the test if the input is invalid by returning `(ok false)`.
    (or
      (not (and (<= 0 n) (<= n 127)))
      (not (and (<= 0 skip) (<= skip 127)))
    )
    (ok false)
    (let
      ((result (slice-uint seq skip n)))
      (if
        ;; Case 1: If skip > length of seq, result should be an empty list.
        (> (to-uint skip) (len seq))
        (asserts! (is-eq result (list )) ERR_ASSERTION_FAILED_1)
        (if
          ;; Case 2: If n > length of seq - skip, result length should be
          ;; length of seq - skip.
          (> (to-uint n) (- (len seq) (to-uint skip)))
          (asserts!
            (is-eq (len result) (- (len seq) (to-uint skip)))
            ERR_ASSERTION_FAILED_2
          )
          ;; Case 3: If n <= length of seq - skip, result length should be n.
          (asserts! (is-eq (len result) (to-uint n)) ERR_ASSERTION_FAILED_3)
        )
      )
      (ok true)
    )
  )
)

Test logic

Test Case Discarding:

  • If skip or n are out of valid bounds (0 ≤ skip, n ≤ 127), the test is discarded (returns (ok false)).
  • This ensures only meaningful cases are tested.

Valid Cases and Expected Behavior:

  • Case 1: When skip exceeds the length of the list, the result should be an empty list.
  • Case 2: When n is larger than the remaining elements after skip, the result should contain all the remaining elements.
  • Case 3: When n is within valid bounds, the result should contain exactly n elements.

Checking the properties

To run Rendezvous property-based tests against the reverse contract, use:

rv ./example slice test

Discarding at its finest

A key aspect introduced in this test is the discarding mechanism. Let's revisit the rules for discarding property-based tests in Rendezvous:

A Rendezvous property-based test is considered discarded when one of the following is true:

  1. The test returns (ok false).
  2. The test's discard function returns false (detailed explanation in Chapter 6).

Discarding property-based tests using discard functions

An example of a property-based test with an attached discard function can also be found in slice.tests.clar:

;; Some tests, like 'test-slice-list-int', are valid only for specific inputs.
;; Rendezvous generates a wide range of inputs, which may include values that
;; are unsuitable for those tests.
;; To skip the test when inputs are invalid, the first way is to define a
;; 'discard' function:
;; - Must be read-only.
;; - Name should match the property test function's, prefixed with "can-".
;; - Parameters should mirror those of the property test.
;; - Returns true only if inputs are valid, allowing the test to run.
(define-read-only (can-test-slice-list-int
    (seq (list 127 int))
    (skip int)
    (n int)
  )
  (and
    (and (<= 0 n) (<= n 127))
    (and (<= 0 skip) (<= skip 127))
  )
)

(define-public (test-slice-list-int (seq (list 127 int)) (skip int) (n int))
  (let
    ((result (slice seq skip n)))
    (if
      ;; Case 1: If skip > length of seq, result should be an empty list.
      (> (to-uint skip) (len seq))
      (asserts! (is-eq result (list )) ERR_ASSERTION_FAILED_1)
      (if
        ;; Case 2: If n > length of seq - skip, result length should be
        ;; length of seq - skip.
        (> (to-uint n) (- (len seq) (to-uint skip)))
        (asserts!
          (is-eq (len result) (- (len seq) (to-uint skip)))
          ERR_ASSERTION_FAILED_2
        )
        ;; Case 3: If n <= length of seq - skip, result length should be n.
        (asserts! (is-eq (len result) (to-uint n)) ERR_ASSERTION_FAILED_3)
      )
    )
    (ok true)
  )
)

The discarding mechanism helps filter out invalid test cases, making property-based tests more efficient and ensuring the test results are correctly displayed. Sample output:

₿        5 Ӿ      115   wallet_1 [WARN] slice test-slice-list-bool [true,false,false] -17 -1286688432
₿        5 Ӿ      116   wallet_4 [WARN] slice test-slice-list-bool [false,false] 985789078 1631962668
₿        5 Ӿ      117   wallet_1 [WARN] slice test-slice-string b^:hD\"Y. 1744256708 676842982
₿        5 Ӿ      118   wallet_1 [FAIL] slice test-slice-list-uint [1818238100,1267097220,587282248,376122205,358580924,724240912,1327852627,89884546] 17 22 (runtime)
₿        5 Ӿ      119   wallet_8 [WARN] slice test-slice-buff cfe44 -13 15
₿        5 Ӿ      120   wallet_1 [WARN] slice test-slice-buff cfe44 -13 15
₿        5 Ӿ      121   wallet_1 [WARN] slice test-slice-ascii 33!rt -13 15
₿        5 Ӿ      122   wallet_1 [PASS] slice test-slice-list-uint [] 17 22
₿      105 Ӿ      223   wallet_1 [FAIL] slice test-slice-list-uint [358580924,724240912,1327852627,89884546] 17 22 (runtime)
₿      105 Ӿ      224   wallet_1 [FAIL] slice test-slice-list-uint [1327852627,89884546] 17 22 (runtime)
₿      105 Ӿ      225   wallet_1 [PASS] slice test-slice-list-uint [89884546] 17 22
₿      205 Ӿ      326   wallet_1 [FAIL] slice test-slice-list-uint [0,89884546] 17 22 (runtime)
₿      205 Ӿ      327   wallet_1 [PASS] slice test-slice-list-uint [89884546] 17 22
₿      305 Ӿ      428   wallet_1 [PASS] slice test-slice-list-uint [0] 17 22
₿      405 Ӿ      529   wallet_1 [FAIL] slice test-slice-list-uint [0,0] 17 22 (runtime)

Tests marked as WARN are discarded, meaning they didn’t meet the criteria to be executed. This gives the user a clear view of how often the test actually ran and helps identify patterns in discarded cases.

Contributing

We welcome all contributions. Big or small, every change matters.

To keep things simple and to maintain quality, please follow these guidelines.

Before You Begin

  • Please read our README.md and ACKNOWLEDGEMENTS to understand our work.
  • Familiarize yourself with our directory structure. Each file is hand-crafted.
  • Make sure that you have Node.js LTS 20.18.0 or later.

How to Contribute

  1. Open an issue: If you find a bug or want to suggest an improvement, open an issue. Describe the problem and proposed changes in simple terms.

  2. Create a fork and branch: Work in a dedicated branch. Use short, clear names:

    git checkout -b my-fix

  3. Maintain code style: We value simple, readable code. Follow our coding style:

    • Keep line length <= 79 chars.
    • Use simple American English.
    • Keep comments brief and clear.
    • Keep logic small and focused.

    Example code comment:

    // Good: Explains why, offering crucial context.
// Bad: Focuses on how or adds unnecessary verbosity.

  4. Write tests: Test your changes. Add or update tests in *.tests.ts files. Run tests:

    npm test

    Make sure all tests pass before sending your changes.

  5. Use clear commit messages:

    • Summarize changes in 79 chars or fewer.
    • Use simple language.
    • Example commit message: 
      Fix off-by-one error in property-based test

    Commit messages should be short and clear.

  6. Open a pull request (PR) targeting the master branch: Keep it small and focused. Explain what and why. Example PR description:

    This PR fixes a minor off-by-one error in the property-based tests.
The fuzzing process now produces the expected results.

  7. Be patient and open-minded: Reviewers may ask questions or suggest changes. We believe in polite and constructive discussion.

Tips for a Great Contribution

  • Keep your changes small and do one thing at a time.
  • Make sure your PR is easy to review. Clear code and tests ease the review process.
  • Provide context for your changes. Explain why they are needed.
  • Don't rush. Take time to polish your work.

Thank You

We appreciate your interest in improving Rendezvous (rv). Your contributions help keep rv robust, helpful, and accessible to everyone.

This CONTRIBUTING guide is crafted with inspiration from the following:

(These references also highlight some of our roots and past influences.)