How to migrate to the SDK
Learn how to migrate your existing Clarinet projects to the Clarinet 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.
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.
npx @hirosystems/clarinet-sdk@latestFollow the prompts to initialise NPM and Vitest, this can take a few seconds.
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
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.
npm testThe 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.