Custom Matchers

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

Installation

Terminal
$ 
npm install @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