Custom Matchers

A set of Vitest matchers that can be used to make assertions on Clarity values with the Clarinet JS SDK.

Installation

npx @hirosystems/clarinet-sdk

toHaveClarityType

Check that a value has the right Clarity type, without checking its value.

Parameters

expectedType
Required
ClarityType

The Clarity type that the expected value should have.

const { result } = simnet.callPublicFn(
  'counter',
  'increment',
  [],
  simnet.deployer
);

expect(result).toHaveClarityType(ClarityType.ResponseOk);

toBeOk

Check that a response is (ok <ok-type>) and has the expected value. Any Clarity value can be passed.

Parameters

expected
Required
ClarityValue

The ClarityValue that the expected value should have.

const { result } = simnet.callPublicFn(
  'counter',
  'increment',
  [],
  simnet.deployer
);

expect(result).toBeOk(Cl.uint(1));

toBeErr

Check that a response is (err <error-type>) and has the expected value. Any Clarity value can be passed.

Parameters

expected
Required
ClarityValue

The ClarityValue that the expected value should have.

const { result } = simnet.callPublicFn(
  'counter',
  'add',
  [Cl.uint(19)],
  simnet.deployer
);

expect(result).toBeErr(Cl.uint(500));

toBeSome

Check that a response is (some <value>) and has the expected value. Any Clarity value can be passed.

Parameters

expected
Required
ClarityValue

The ClarityValue that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'pool',
  'get-participant',
  [Cl.standardPrincipal('ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5')],
  simnet.deployer
);

expect(result).toBeSome(Cl.bool(true));

toBeNone

Check that a response is (none).

const { result } = simnet.callReadOnlyFn(
  'pool',
  'get-participant',
  [Cl.standardPrincipal('ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5')],
  simnet.deployer
);

expect(result).toBeNone();

toBeBool

Asserts the value of Clarity boolean (true or false).

Parameters

expected
Required
boolean

The boolean that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'pool',
  'has-contributed',
  [Cl.standardPrincipal('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM')],
  simnet.deployer
);

expect(result).toBeBool(true);

toBeInt

Asserts the value of a Clarity integer.

Parameters

expected
Required
boolean

The integer that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'counter',
  'increment',
  [],
  simnet.deployer
);

expect(result).toBeInt(1); // or `1n`

toBeUint

Asserts the value of a Clarity unsigned integer.

Parameters

expected
Required
boolean

The unsigned integer that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'counter',
  'increment',
  [],
  simnet.deployer
);

expect(result).toBeUint(1); // or `1n`

toBeAscii

Asserts the value of a Clarity string-ascii.

Parameters

expected
Required
string

The string that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'hello-world',
  'say-hi',
  [],
  simnet.deployer
);

expect(result).toBeAscii('Hello World');

toBeUtf8

Asserts the value of a Clarity string-utf8.

Parameters

expected
Required
string

The string that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'hello-world',
  'say-hi',
  [],
  simnet.deployer
);

expect(result).toBeUtf8('Hello World');

toBePrincipal

Asserts the value of a Clarity principal.

The principal can be a standard or a contract principal.

Parameters

expected
Required
string

The string that the expected value should have.

const deployer = simnet.deployer;

expect(Cl.standardPrincipal(deployer)).toBePrincipal(deployer);

toBeBuff

Asserts the value of a Clarity buffer. It takes an ArrayBuffer as an input.

For building a buffer, @stacks/transactions provides some helper functions:

  • bufferFromAscii
  • bufferFromUtf8
  • bufferFromHex

Parameters

expected
Required
Uint8Array

The Uint8Array buffer that the expected value should have.

const { result } = simnet.callReadOnlyFn(
  'helpers',
  'get-byte-array',
  [],
  simnet.deployer
);

const buffer = Uint8Array.from([1, 2, 3, 4]);
expect(result).toBeBuff(buffer);

toBeList

Asserts the value of a Clarity list containing an array of Clarity values.

Parameters

expected
Required
ClarityValue[]

The Uint8Array buffer that the expected value should have.

import { Cl } from '@stacks/transactions';

const { result } = simnet.callReadOnlyFn(
  'helpers',
  'get-addresses',
  [],
  simnet.deployer
);

expect(result).toBeList(
  [
    Cl.standardPrincipal('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'),
    Cl.standardPrincipal('ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5'),
    Cl.standardPrincipal('ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG')
  ]
);

toBeTuple

Asserts the value of a Clarity tuple.

Parameters

expected
Required
object

The object of Clarity values that the expected value should have.

import { Cl } from '@stacks/transactions';

const { result } = simnet.callReadOnlyFn(
  'pool',
  'get-participant-data',
  [Cl.standardPrincipal(simnet.deployer)],
  simnet.deployer
);

expect(result).toBeTuple({
  enrollmentBlock: Cl.some(Cl.uint(1)),
  contributionAmount: Cl.some(Cl.uint(19000000)),
});

Methods