How to migrate to the SDK

In this guide, you will learn how to:

Migrate your existing Clarinet projects to the Clarinet SDK.
Run your existing tests using the Clarinet SDK.

Note

This guide is for projects that have been created with Clarinet v1 and do not have the v2 boilerplate code auto-generated in their projects.

Executing the migration script

Inside your Clarinet v1 project, run the following command to initialise NPM and Vitest. It will also create a sample test file.

Terminal

npx @hirosystems/clarinet-sdk@latest

Follow the prompts to initialise NPM and Vitest, this can take a few seconds.

Info

The file tests/counter_test.ts that was created by clarinet contract new counter can be deleted.

You can also have a look at tests/contract.test.ts. It's a sample file showing how to use the SDK with Vitest. It can safely be deleted.

Unit test for `counter` example

tests/counter.test.ts

import { Cl } from '@stacks/transactions';
import { describe, expect, it } from 'vitest';

const accounts = simnet.getAccounts();
const address1 = accounts.get('wallet_1')!;

describe('test `increment` public function', () => {
  it('increments the count by the given value', () => {
    const incrementResponse = simnet.callPublicFn('counter', 'increment', [Cl.uint(1)], address1);
    console.log(Cl.prettyPrint(incrementResponse.result)); // (ok u2)
    expect(incrementResponse.result).toBeOk(Cl.uint(2));

    const count1 = simnet.getDataVar('counter', 'count');
    expect(count1).toBeUint(2);

    simnet.callPublicFn('counter', 'increment', [Cl.uint(40)], address1);
    const count2 = simnet.getDataVar('counter', 'count');
    expect(count2).toBeUint(42);
  });

  it('sends a print event', () => {
    const incrementResponse = simnet.callPublicFn('counter', 'increment', [Cl.uint(1)], address1);

    expect(incrementResponse.events).toHaveLength(1);
    const printEvent = incrementResponse.events[0];
    expect(printEvent.event).toBe('print_event');
    expect(printEvent.data.value).toBeTuple({
      object: Cl.stringAscii('count'),
      action: Cl.stringAscii('incremented'),
      value: Cl.uint(2),
    });
  });
});

To run the test, go back to your console and run the test command using your preferred package manager. It should display a report telling you that tests succeeded.

Terminal

npm test

Note

The simnet object is available globally in the tests, and is automatically initialized before each test. You can have a look at the vitest.config.js file at the root of you project for more details.

Getting back to the tests - the first test checks that the increment function returns the new value and saves it to the count variable. The second test checks that an print_event is emitted when the increment function is called.

How to migrate to the SDK

Executing the migration script

Unit test for `counter` example

Next steps

API Reference

Custom matchers

Migrating your tests to Clarinet SDK

On this page

How to migrate to the SDK

Executing the migration script

Unit test for counter example

Next steps

API Reference

Custom matchers

Migrating your tests to Clarinet SDK

On this page

Unit test for `counter` example