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

`toHaveClarityType`

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

Parameters

The Clarity type that the expected value should have.

Examples

Checking for an ok response:

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

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

Source code:

(define-data-var count uint u0)

(define-public (increment)
  (begin
    (var-set count (+ (var-get count) u1))
    (ok (var-get count))
  )
)

Schema:

toHaveClarityType(expectedType: ClarityType)

`toBeOk`

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

Parameters

The ClarityValue that the expected value should have.

Examples

Checking for an ok response with a specific value:

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

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

Source code:

(define-data-var count uint u0)

(define-public (increment)
  (begin
    (var-set count (+ (var-get count) u1))
    (ok (var-get count))
  )
)

Schema:

toBeOk(expected: ClarityValue)

`toBeErr`

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

Parameters

The ClarityValue that the expected value should have.

Examples

Checking for an err response with a specific value:

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

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

Source code:

(define-constant TOO_BIG u10)
(define-data-var count uint u0)

(define-public (add (amount uint))
  (begin
    (let ((new-count (+ (var-get count) amount)))
      (if (<= new-count TOO_BIG)
        (begin
          (var-set count new-count)
          (ok (var-get count))
        )
        (err u500)
      )
    )
  )
)

Schema:

toBeErr(expected: ClarityValue)

`toBeSome`

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

Parameters

The ClarityValue that the expected value should have.

Examples

Checking for an optional value:

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

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

Source code:

(define-map Participants principal bool)
(define-map ParticipantStatus principal { enrollmentBlock: uint, contributionAmount: uint })

(define-read-only (get-participant (who principal))
  (map-get? ParticipantStatus who)
)

(map-set Participants 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5 true)
(map-set ParticipantStatus 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5 { enrollmentBlock: u1, contributionAmount: u19000000 })

Schema:

toBeSome(expected: ClarityValue)

`toBeNone`

Check that a response is (none).

Examples

Checking for a none value:

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

expect(result).toBeNone();

Source code:

(define-map Participants principal bool)
(define-map ParticipantStatus principal { enrollmentBlock: uint, contributionAmount: uint })

(define-read-only (get-participant (who principal))
  (map-get? ParticipantStatus who)
)

Schema:

toBeNone()

`toBeBool`

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

Parameters

The boolean that the expected value should have.

Examples

Checking for a boolean value:

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

expect(result).toBeBool(true);

Source code:

(define-map ParticipantStatus principal { enrollmentBlock: uint, contributionAmount: uint })

(define-read-only (has-contributed (who principal))
  (is-some (get contributionAmount (map-get? ParticipantStatus who)))
)

(map-set ParticipantStatus tx-sender { enrollmentBlock: u1, contributionAmount: u19000000 })

Schema:

toBeBool(expected: boolean)

`toBeInt`

Asserts the value of a Clarity integer.

Parameters

The integer that the expected value should have.

Examples

Checking for an integer value:

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

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

Source code:

(define-data-var count int 0)

(define-public (increment)
  (begin
    (var-set count (+ (var-get count) 1))
    (ok (var-get count))
  )
)

Schema:

toBeInt(expected: number | bigint)

`toBeUint`

Asserts the value of a Clarity unsigned integer.

Parameters

The unsigned integer that the expected value should have.

Examples

Checking for an unsigned integer value:

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

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

Source code:

(define-data-var count uint u0)

(define-public (increment)
  (begin
    (var-set count (+ (var-get count) u1))
    (ok (var-get count))
  )
)

Schema:

toBeUint(expected: number | bigint)

`toBeAscii`

Asserts the value of a Clarity string-ascii.

Parameters

The string that the expected value should have.

Examples

Checking for a string-ascii value:

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

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

Source code:

(define-read-only (say-hi)
  "Hello World"
)

Schema:

toBeAscii(expected: string)

`toBeUtf8`

Asserts the value of a Clarity string-utf8.

Parameters

The string that the expected value should have.

Examples

Checking for a string-utf8 value:

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

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

Source code:

(define-read-only (say-hi)
  u"Hello World"
)

Schema:

toBeUtf8(expected: string)

`toBePrincipal`

Asserts the value of a Clarity principal.

The principal can be a standard or a contract principal.

Parameters

The string that the expected value should have.

Examples

Checking for a standard principal:

const deployer = simnet.deployer;

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

Schema:

toBePrincipal(expected: string)

Checking for a contract principal:

const contract = `${simnet.deployer}.hello-world`;

expect(Cl.contractPrincipal(contract)).toBePrincipal(contract);

Schema:

toBePrincipal(expected: string)

`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

The Uint8Array buffer that the expected value should have.

Examples

Checking for a Uint8Array buffer:

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

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

Source code:

(define-constant BUFFER 0x01020304)

(define-read-only (get-byte-array)
  BUFFER
)

Schema:

toBeBuff(expected: Uint8Array)

Checking for an ASCII string buffer:

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

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

const btc = Cl.bufferFromAscii('btc'); // or Cl.bufferFromUtf8('btc')

expect(result).toBeBuff(btc.buffer);

Source code:

(define-constant ASCII_BTC 0x627463)

(define-read-only (get-btc-buffer)
  ASCII_BTC
)

Checking for a hex string buffer:

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

const { result } = simnet.callReadOnlyFn(
  "helpers",
  "get-tx-hash",
  [],
  simnet.deployer
);

const tx = Cl.bufferFromHex(
  "73e951acd451060f13bdab7bd947136efd80511309a295e876a682ab8a423a7e"
);

expect(result).toBeBuff(tx.buffer);

Source code:

(define-constant TX_HASH 0x73e951acd451060f13bdab7bd947136efd80511309a295e876a682ab8a423a7e)

(define-read-only (get-tx-hash)
  TX_HASH
)

`toBeList`

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

Parameters

The Uint8Array buffer that the expected value should have.

Examples

Checking for a list of Clarity values:

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')
  ]
);

Source code:

(define-read-only (get-addresses)
  (list
    'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
    'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5
    'ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG
  )
)

Schema:

toBeList(expected: ClarityValue[])

`toBeTuple`

Asserts the value of a Clarity tuple.

Parameters

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

Examples

Checking for a tuple:

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)),
});

Source code:

(define-map ParticipantStatus principal { enrollmentBlock: uint, contributionAmount: uint })

(define-read-only (get-participant (who principal))
  (map-get? ParticipantStatus who)
)

(define-read-only (get-participant-data (who principal))
  {
    enrollmentBlock: (get enrollmentBlock (map-get? ParticipantStatus who)),
    contributionAmount: (get contributionAmount (map-get? ParticipantStatus who))
  }
)

(map-set ParticipantStatus tx-sender { enrollmentBlock: u1, contributionAmount: u19000000 })

Schema:

toBeTuple(expected: Record<string, ClarityValue>)

Custom Matchers