Clarinet unit tests revamp POC

[hugocaillard]

Context

Some initial context in this discussion

TL;DR

• Clarinet currently embeds Deno to run clarinet tests
• This dependency is heavy, painful to maintain, and comes with build issues
• We decided to explore another approach for Clarinet test

The POC

Clarinet will expose a JS library (through wasm) that will allow to test smart contracts in any JS/WASM environment (Node, Deno, Web Browers, etc).

• The package could be called @stacks/clarinet-sdk/unit-tests (introducing the clarinet SDK package Add support to retrieve the observable events from the contracts in a given Clarinet project #1034)

• The POC will be mostly tested with Node 20 test runner

• here as a working template representing what's feasible at the end of this POC

import { main } from "../../../../hiro/clarinet/components/clarinet-sdk/dist/index.js";
import { before, describe, it } from "node:test";
import assert from "node:assert/strict";
import { Cl } from "@stacks/transactions";

let sender = "ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5";

describe("test counter", () => {
  let session;

  before(async () => {
    session = await main();
    await session.initSession(process.cwd(), "./Clarinet.toml");
  });

  it("gets counter value", () => {
    const res = session.callReadOnlyFn("counter", "get-counter", [], sender);
    assert.deepEqual(Cl.int(0), res.result);
    assert.equal(session.blockHeight, 1);
  });

  it("increments counter value", () => {
    const incrRes = session.callPublicFn("counter", "increment", [], sender);
    assert.deepEqual(incrRes.result, Cl.ok(Cl.bool(true)));
    assert.equal(session.blockHeight, 2);

    let res = session.callReadOnlyFn("counter", "get-counter", [], sender);
    assert.deepEqual(res.result, Cl.int(1));
    assert.equal(session.blockHeight, 2);
  });

  it("add any value", () => {
    const addRes = session.callPublicFn("counter", "add", [Cl.int(10)], sender);
    assert.deepEqual(addRes.result, Cl.ok(Cl.bool(true)));
    assert.equal(session.blockHeight, 3);

    let res = session.callReadOnlyFn("counter", "get-counter", [], sender);
    assert.deepEqual(res.result, Cl.int(11));
    assert.equal(session.blockHeight, 3);
  });
});

Going further

A lot of features and improvements have to be considered in the next iteration (Q3). This is just a list of ideas, not all of them will be implemented

• specify which command will clarinet test run (default will be node test)
• throw errors on clarity run time error Runtime error in read-only function but test passes #998
• access to data-vars and maps Deno library support for reading data-vars and maps #970
• access to private functions Allow clarinet to access functions that are private (to enable unit testing) #547

[hugocaillard]

This POC is now considered done.
Conclusion:

• clarity sessions can easily be initiated in JS through wasm
• developer can easily interact with the session (call contracts, interact with raw clarity values and (de)serialize it with stacks.js)

Let's pursue in this direction to build a enjoyable testing experience!

Closing in favor of #1065