@stacks/clarinet-sdk 3.8.1

package/vitest-helpers/src/clarityValuesMatchers.ts

@@ -0,0 +1,389 @@
+import { expect, ExpectStatic, assert } from "vitest";
+import {
+  Cl,
+  ClarityValue,
+  ClarityType,
+  ResponseOkCV,
+  NoneCV,
+  SomeCV,
+  ResponseErrorCV,
+  IntCV,
+  UIntCV,
+  StringAsciiCV,
+  StringUtf8CV,
+  ContractPrincipalCV,
+  StandardPrincipalCV,
+  ListCV,
+  TupleCV,
+  BufferCV,
+  TrueCV,
+  FalseCV,
+  BooleanCV,
+  cvToString,
+} from "@stacks/transactions";
+
+import { MatcherState } from "@vitest/expect";
+
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json
+// @ts-ignore
+BigInt.prototype.toJSON = function () {
+  return this.toString();
+};
+
+function notStr(isNot: boolean) {
+  return isNot ? "not " : "";
+}
+
+function formatMessage(this: MatcherState, received: string, expected: string) {
+  return `expected ${received} ${notStr(this.isNot)}to be ${expected}`;
+}
+
+export class ClarityTypeError extends Error {
+  actual?: any;
+  expected?: any;
+
+  constructor({ message, actual, expected }: { message: string; actual?: any; expected?: any }) {
+    super(message);
+    this.actual = actual;
+    this.expected = expected;
+
+    Object.setPrototypeOf(this, ClarityTypeError.prototype);
+  }
+}
+
+type ClarityTypetoValue = {
+  [ClarityType.OptionalNone]: NoneCV;
+  [ClarityType.OptionalSome]: SomeCV;
+  [ClarityType.ResponseOk]: ResponseOkCV;
+  [ClarityType.ResponseErr]: ResponseErrorCV;
+  [ClarityType.BoolTrue]: TrueCV;
+  [ClarityType.BoolFalse]: FalseCV;
+  [ClarityType.Int]: IntCV;
+  [ClarityType.UInt]: UIntCV;
+  [ClarityType.StringASCII]: StringAsciiCV;
+  [ClarityType.StringUTF8]: StringUtf8CV;
+  [ClarityType.PrincipalStandard]: StandardPrincipalCV;
+  [ClarityType.PrincipalContract]: ContractPrincipalCV;
+  [ClarityType.List]: ListCV;
+  [ClarityType.Tuple]: TupleCV;
+  [ClarityType.Buffer]: BufferCV;
+};
+
+const ClarityTypeReversed = Object.fromEntries(Object.entries(ClarityType).map(([k, v]) => [v, k]));
+
+// the "simple clarity values" are CVs that can't be nested and have `value` property
+type SimpleCV = BooleanCV | IntCV | UIntCV | StringAsciiCV | StringUtf8CV;
+type SimpleCVTypes =
+  | ClarityType.BoolFalse
+  | ClarityType.BoolTrue
+  | ClarityType.Int
+  | ClarityType.UInt
+  | ClarityType.StringASCII
+  | ClarityType.StringUTF8;
+
+const validClarityTypes = Object.values(ClarityType).filter(
+  (t) => typeof t === "string",
+) as string[];
+
+function isClarityValue(input: unknown): input is ClarityValue {
+  if (!input || typeof input !== "object") return false;
+  if (!("type" in input) || typeof input.type !== "string") return false;
+  if (!validClarityTypes.includes(input.type)) return false;
+
+  return true;
+}
+
+function isClarityValueWithType<T extends ClarityType>(
+  input: unknown,
+  withType: T,
+): input is ClarityTypetoValue[T] {
+  if (!isClarityValue(input)) return false;
+  if (input.type !== withType) return false;
+
+  return true;
+}
+
+function checkCVType<T extends ClarityType>(
+  actual: unknown,
+  expectedType: T,
+  isNot: boolean,
+): actual is ClarityTypetoValue[T] {
+  const isCV = isClarityValue(actual);
+
+  if (!isCV) {
+    throw new ClarityTypeError({
+      message: `actual value must ${notStr(isNot)}be a Clarity "${
+        ClarityTypeReversed[expectedType]
+      }", received "${typeof actual}"`,
+    });
+  }
+
+  const isCVWithType = isClarityValueWithType(actual, expectedType);
+
+  if (!isCVWithType) {
+    // for readability, the error diff is kept short if the developers uses the wrong `expect<ClarityType>`
+    // ideally, we should have a way to display short message diffs even if the actual and/or expected data are big lists/tuples/buffers
+
+    // for now, we make an exception and display the full error message if the actual value is a ResponseErr
+    const errorCode = actual.type === ClarityType.ResponseErr ? ` ${Cl.prettyPrint(actual)}` : "";
+
+    throw new ClarityTypeError({
+      // generic and short message
+      message: `actual value must ${notStr(isNot)}be a Clarity "${
+        ClarityTypeReversed[expectedType]
+      }", received "${ClarityTypeReversed[actual.type]}"${errorCode}`,
+      actual: ClarityTypeReversed[actual.type],
+      expected: ClarityTypeReversed[expectedType],
+    });
+  }
+
+  return true;
+}
+
+function errorToAssertionResult(this: MatcherState, err: any) {
+  return {
+    pass: false,
+    message: () => err.message,
+    actual: err.actual,
+    expected: err.expected,
+  };
+}
+
+function simpleAssertion(
+  this: MatcherState,
+  cvType: SimpleCVTypes,
+  actualRaw: unknown,
+  expectedRaw: SimpleCV,
+) {
+  try {
+    const isCV = checkCVType(actualRaw, cvType, this.isNot);
+    assert(isCV);
+  } catch (e: any) {
+    return errorToAssertionResult.call(this, e);
+  }
+
+  return {
+    pass: this.equals(actualRaw, expectedRaw, undefined, true),
+    message: () =>
+      `expected ${Cl.prettyPrint(actualRaw)} ${notStr(this.isNot)}to be ${Cl.prettyPrint(
+        expectedRaw,
+      )}`,
+    actual: Cl.prettyPrint(actualRaw, 2),
+    expected: Cl.prettyPrint(expectedRaw, 2),
+  };
+}
+
+const typeToCvMethod = {
+  [ClarityType.ResponseOk]: Cl.ok,
+  [ClarityType.ResponseErr]: Cl.error,
+  [ClarityType.OptionalSome]: Cl.some,
+};
+
+// simple composite types are `ok`, `err`, `some`
+function simpleCompositeAssertion(
+  this: MatcherState,
+  expectedType: ClarityType.ResponseOk | ClarityType.ResponseErr | ClarityType.OptionalSome,
+  actualRaw: unknown,
+  expectedValue: ClarityValue | ExpectStatic,
+) {
+  try {
+    const isCV = checkCVType(actualRaw, expectedType, this.isNot);
+    assert(isCV);
+  } catch (e: any) {
+    return errorToAssertionResult.call(this, e);
+  }
+
+  const clMethod = typeToCvMethod[expectedType];
+
+  const expectedIsCV = isClarityValue(expectedValue);
+  const expectedOneLine = expectedIsCV
+    ? Cl.prettyPrint(clMethod(expectedValue))
+    : JSON.stringify(expectedValue);
+  const expected = expectedIsCV
+    ? Cl.prettyPrint(clMethod(expectedValue), 2)
+    : JSON.stringify(expectedValue);
+
+  return {
+    pass: this.equals(actualRaw.value, expectedValue, undefined, true),
+    message: () => formatMessage.call(this, Cl.prettyPrint(actualRaw), expectedOneLine),
+    actual: Cl.prettyPrint(actualRaw, 2),
+    expected,
+  };
+}
+
+expect.extend({
+  toHaveClarityType(actual: unknown, expectedType: ClarityType) {
+    try {
+      const isCV = checkCVType(actual, expectedType, this.isNot);
+      assert(isCV);
+    } catch (e: any) {
+      return errorToAssertionResult.call(this, e);
+    }
+
+    return {
+      pass: true,
+      message: () =>
+        `actual value must ${notStr(this.isNot)}be a Clarity "${ClarityTypeReversed[expectedType]}"`,
+    };
+  },
+
+  toBeBool(actual: unknown, expected: boolean) {
+    const expectedType = expected ? ClarityType.BoolTrue : ClarityType.BoolFalse;
+    return simpleAssertion.call(this, expectedType, actual, Cl.bool(expected));
+  },
+
+  toBeInt(actual: unknown, expected: number | bigint) {
+    return simpleAssertion.call(this, ClarityType.Int, actual, Cl.int(expected));
+  },
+
+  toBeUint(actual: unknown, expected: number | bigint) {
+    return simpleAssertion.call(this, ClarityType.UInt, actual, Cl.uint(expected));
+  },
+
+  toBeAscii(actual: unknown, expected: string) {
+    return simpleAssertion.call(this, ClarityType.StringASCII, actual, Cl.stringAscii(expected));
+  },
+
+  toBeUtf8(actual: unknown, expected: string) {
+    return simpleAssertion.call(this, ClarityType.StringUTF8, actual, Cl.stringUtf8(expected));
+  },
+
+  toBeOk(actual: unknown, expectedValue: ExpectStatic | ClarityValue) {
+    return simpleCompositeAssertion.call(this, ClarityType.ResponseOk, actual, expectedValue);
+  },
+
+  toBeErr(actual: unknown, expectedValue: ExpectStatic | ClarityValue) {
+    return simpleCompositeAssertion.call(this, ClarityType.ResponseErr, actual, expectedValue);
+  },
+
+  toBeSome(actual: unknown, expectedValue: ExpectStatic | ClarityValue) {
+    return simpleCompositeAssertion.call(this, ClarityType.OptionalSome, actual, expectedValue);
+  },
+
+  toBeNone(actual: unknown) {
+    const expectedType = ClarityType.OptionalNone;
+    try {
+      const isCV = checkCVType(actual, expectedType, this.isNot);
+      assert(isCV);
+    } catch (e: any) {
+      return errorToAssertionResult.call(this, e);
+    }
+
+    const expected = Cl.none();
+    return {
+      pass: this.equals(actual, expected, undefined, true),
+      message: () => formatMessage.call(this, Cl.prettyPrint(actual), Cl.prettyPrint(actual)),
+      actual: Cl.prettyPrint(actual, 2),
+      expected: Cl.prettyPrint(actual, 2),
+    };
+  },
+
+  toBePrincipal(actual: unknown, expectedString: string) {
+    const isStandard = !expectedString.includes(".");
+    let expected: StandardPrincipalCV | ContractPrincipalCV;
+
+    const expectedType = isStandard ? ClarityType.PrincipalStandard : ClarityType.PrincipalContract;
+    try {
+      const isCV = checkCVType(actual, expectedType, this.isNot);
+      assert(isCV);
+    } catch (e: any) {
+      return errorToAssertionResult.call(this, e);
+    }
+
+    const actualString = cvToString(actual, "tryAscii");
+
+    try {
+      expected = isStandard
+        ? Cl.standardPrincipal(expectedString)
+        : Cl.contractPrincipal(...(expectedString.split(".") as [string, string]));
+    } catch {
+      return {
+        pass: false,
+        message: () => `expected ${expectedString} ${notStr(this.isNot)}to be a principal`,
+        actual: actualString,
+        expected: expectedString,
+      };
+    }
+
+    return {
+      pass: this.equals(actual, expected, undefined, true),
+      message: () => formatMessage.call(this, actualString, expectedString),
+      actual: Cl.prettyPrint(actual, 2),
+      expected: Cl.prettyPrint(expected, 2),
+    };
+  },
+
+  toBeBuff(actual: unknown, expectedRaw: Uint8Array) {
+    const expectedType = ClarityType.Buffer;
+    try {
+      const isCV = checkCVType(actual, expectedType, this.isNot);
+      assert(isCV);
+    } catch (e: any) {
+      return errorToAssertionResult.call(this, e);
+    }
+
+    const expected = Cl.buffer(expectedRaw);
+    return {
+      pass: this.equals(actual, expected, undefined, true),
+      // note: throw a simple message and rely on `actual` and `expected` to display the diff
+      message: () => `the received Buffer does ${this.isNot ? "" : "not "}match the expected one`,
+      actual: Cl.prettyPrint(actual, 2),
+      expected: Cl.prettyPrint(expected, 2),
+    };
+  },
+
+  toBeList(actual: unknown, expectedItems: ExpectStatic[] | ClarityValue[]) {
+    const expectedType = ClarityType.List;
+    try {
+      const isCV = checkCVType(actual, expectedType, this.isNot);
+      assert(isCV);
+    } catch (e: any) {
+      return errorToAssertionResult.call(this, e);
+    }
+
+    const isListArray = checkIsListArray(expectedItems);
+    const expected = isListArray ? Cl.prettyPrint(Cl.list(expectedItems), 2) : expectedItems;
+
+    return {
+      pass: this.equals(actual.value, expectedItems, undefined, true),
+      // note: throw a simple message and rely on `actual` and `expected` to display the diff
+      message: () => `the received List does ${this.isNot ? "" : "not "}match the expected one`,
+      actual: Cl.prettyPrint(actual, 2),
+      expected,
+    };
+  },
+
+  toBeTuple(actual: unknown, expectedData: Record<string, ExpectStatic | ClarityValue>) {
+    const expectedType = ClarityType.Tuple;
+    try {
+      const isCV = checkCVType(actual, expectedType, this.isNot);
+      assert(isCV);
+    } catch (e: any) {
+      return errorToAssertionResult.call(this, e);
+    }
+
+    const isTupleData = checkIsTupleData(expectedData);
+    const expected = isTupleData ? Cl.prettyPrint(Cl.tuple(expectedData), 2) : expectedData;
+
+    return {
+      pass: this.equals(actual.value, expectedData, undefined, true),
+      // note: throw a simple message and rely on `actual` and `expected` to display the diff
+      message: () => `the received Tuple does ${this.isNot ? "" : "not "}match the expected one`,
+      actual: Cl.prettyPrint(actual, 2),
+      expected,
+    };
+  },
+});
+
+// for composite types, matchers need to narrow the type of the expected value
+// to know if it contains AsymmetricMatchers or if it's only ClarityValues
+
+function checkIsTupleData(
+  expected: Record<string, ExpectStatic | ClarityValue>,
+): expected is Record<string, ClarityValue> {
+  return Object.values(expected).every((v) => isClarityValue(v));
+}
+
+function checkIsListArray(expected: ExpectStatic[] | ClarityValue[]): expected is ClarityValue[] {
+  return expected.every((v) => isClarityValue(v));
+}

package/vitest-helpers/src/global.d.ts

@@ -0,0 +1,20 @@
+import type { Simnet } from "../../dist/esm/node/src";
+
+declare global {
+  var simnet: Simnet;
+  var testEnvironment: string;
+  var coverageReports: string[];
+  var costsReports: string[];
+  var options: {
+    clarinet: {
+      manifestPath: string;
+      initBeforeEach: boolean;
+      coverage: boolean;
+      coverageFilename: string;
+      costs: boolean;
+      costsFilename: string;
+      includeBootContracts: boolean;
+      bootContractsPath: string;
+    };
+  };
+}

package/vitest-helpers/src/vitest.d.ts

@@ -0,0 +1,28 @@
+import type { Assertion, AsymmetricMatchersContaining, ExpectStatic } from "vitest";
+import type { ClarityType, ClarityValue } from "@stacks/transactions";
+
+interface ClarityValuesMatchers<R = unknown> {
+  toHaveClarityType(expectedType: ClarityType): R;
+
+  toBeOk(expected: ExpectStatic | ClarityValue): R;
+  toBeErr(expected: ExpectStatic | ClarityValue): R;
+
+  toBeSome(expected: ExpectStatic | ClarityValue): R;
+  toBeNone(): R;
+
+  toBeBool(expected: boolean): R;
+  toBeInt(rexpected: number | bigint): R;
+  toBeUint(expected: number | bigint): R;
+  toBeAscii(expected: string): R;
+  toBeUtf8(expected: string): R;
+  toBePrincipal(expected: string): R;
+  toBeBuff(expected: Uint8Array): R;
+
+  toBeList(expected: ExpectStatic[] | ClarityValue[]): R;
+  toBeTuple(expected: Record<string, ExpectStatic | ClarityValue>): R;
+}
+
+declare module "vitest" {
+  interface Assertion<T = any> extends ClarityValuesMatchers<T> {}
+  interface AsymmetricMatchersContaining extends ClarityValuesMatchers<ExpectStatic> {}
+}

package/vitest-helpers/src/vitest.setup.ts

@@ -0,0 +1,69 @@
+import { afterAll, beforeAll, beforeEach, afterEach, RunnerTask } from "vitest";
+
+import "./clarityValuesMatchers";
+
+function getFullTestName(task: RunnerTask, names: string[]) {
+  const fullNames = [task.name, ...names];
+  if (task.suite?.name) {
+    return getFullTestName(task.suite, fullNames);
+  }
+  return fullNames;
+}
+
+/*
+  The `initBeforeEach` options controls the initialisation of the session.
+  If the session is initialised before each test, the reports are collected after each test.
+  If the session is not initialised before each test, it'll be initialized in the `beforeAll`, which
+  will run for all test file. In that case reports are collected in the after all.
+*/
+
+beforeEach(async (ctx) => {
+  const { coverage, initBeforeEach, manifestPath } = global.options.clarinet;
+
+  if (initBeforeEach) {
+    await simnet.initSession(process.cwd(), manifestPath);
+  }
+
+  if (coverage) {
+    const suiteTestNames = getFullTestName(ctx.task, []);
+    const fullName = [ctx.task.file?.name || "", ...suiteTestNames].join("__");
+    simnet.setCurrentTestName(fullName);
+  }
+});
+
+afterEach(async (ctx) => {
+  const { coverage, costs, initBeforeEach, includeBootContracts, bootContractsPath } =
+    global.options.clarinet;
+
+  if (ctx.task.result?.state === "fail") {
+    const stackTrace = simnet.getLastContractCallTrace();
+    if (stackTrace) {
+      console.log(stackTrace);
+    }
+  }
+
+  if (initBeforeEach && (coverage || costs)) {
+    const report = simnet.collectReport(includeBootContracts || false, bootContractsPath || "");
+    if (coverage) coverageReports.push(report.coverage);
+    if (costs) costsReports.push(report.costs);
+  }
+});
+
+beforeAll(async () => {
+  const { initBeforeEach, manifestPath } = global.options.clarinet;
+
+  if (!initBeforeEach) {
+    await simnet.initSession(process.cwd(), manifestPath);
+  }
+});
+
+afterAll(() => {
+  const { coverage, costs, initBeforeEach, includeBootContracts, bootContractsPath } =
+    global.options.clarinet;
+
+  if (!initBeforeEach && (coverage || costs)) {
+    const report = simnet.collectReport(includeBootContracts || false, bootContractsPath || "");
+    if (coverage) coverageReports.push(report.coverage);
+    if (costs) costsReports.push(report.costs);
+  }
+});