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:
- 1Migrate your existing Clarinet projects to the Clarinet SDK.
- 2Run 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@latest
Follow 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 test
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.