Vitest Environment for Clarinet Projects

Common errors

• Error: Failed to load environment "clarinet". Make sure it is installed and exported correctly.

  cause The `vitest-environment-clarinet` package is not installed, or Vitest cannot find it in your `node_modules`.
  fix Ensure `vitest-environment-clarinet` is installed: `npm install --save-dev vitest-environment-clarinet` or `yarn add --dev vitest-environment-clarinet`.

• ReferenceError: clarity is not defined

  cause The `@stacks/clarinet-sdk` package, which provides the global `clarity` object, is either not installed or an incompatible version, or the Vitest environment is not correctly configured.
  fix 1. Check your `vitest.config.ts` to ensure `environment: 'clarinet'` is set. 2. Verify `@stacks/clarinet-sdk` is installed and meets the `vitest-environment-clarinet` peer dependency requirements: `npm install --save-dev @stacks/clarinet-sdk`.

• TypeError: Cannot read properties of undefined (reading 'contract')

  cause This usually indicates that the `clarity` object is available but not properly initialized, or there's an issue with the underlying Clarinet simnet setup, preventing contract access.
  fix Ensure your Clarinet project is correctly configured (e.g., `Clarinet.toml`, contract files are present and compiled). Sometimes, clearing Vitest cache (`vitest --clearCache`) or reinstalling `node_modules` can help resolve transient issues.

Warnings

• breaking Major versions of `vitest-environment-clarinet` often introduce breaking changes primarily related to compatibility with new major versions of Vitest. For example, v2.6.0 added support for Vitest 4.x, and v3.0.0 was a major release often aligning with Vitest's own versioning for compatibility. Always review the changelog when upgrading Vitest or this environment.
  Fix: Consult the `vitest-environment-clarinet` changelog and Vitest migration guide for specific steps. Ensure `vitest` and `@stacks/clarinet-sdk` peer dependencies match the requirements.
• gotcha Mismatching Vitest versions with `vitest-environment-clarinet` can lead to unexpected behavior or test failures, as the environment relies on internal Vitest APIs. The `peerDependencies` are critical.
  Fix: Ensure your `vitest` installation strictly adheres to the `peerDependencies` range specified by `vitest-environment-clarinet`. Upgrade or downgrade Vitest as necessary.
• gotcha The `clarity` object, essential for interacting with the Clarinet simnet, is provided by `@stacks/clarinet-sdk`, which is a peer dependency. If `@stacks/clarinet-sdk` is not installed or its version is incompatible, tests will fail with `clarity is undefined` errors.
  Fix: Verify that `@stacks/clarinet-sdk` is correctly installed in your project and meets the required version range of `vitest-environment-clarinet`'s `peerDependencies`.

Install

• npm install vitest-environment-clarinet npm
• yarn add vitest-environment-clarinet yarn
• pnpm add vitest-environment-clarinet pnpm

Imports

• environment: 'clarinet'
  wrong:

  import { Clarinet } from 'vitest-environment-clarinet';

  correct:

  // vitest.config.ts
  import { defineConfig } from 'vitest/config';
  
  export default defineConfig({
    test: {
      environment: 'clarinet',
    },
  });

  This package primarily functions as a custom Vitest environment specified in configuration, not as a module exporting symbols for direct import into test files. The `clarinet` string is resolved by Vitest to load this package.
• clarity (global/context)

  // my-contract.test.ts
  describe('MyContract', () => {
    test('should do something', async () => {
      const response = await clarity.contract.myContract.read.someFunction();
      expect(response.result).toBe('success');
    });
  });

  The `clarity` object, providing access to Clarinet simnet interactions, is made available in the global scope or test context by the `clarinet-sdk` when this environment is active. It is not imported directly from `vitest-environment-clarinet`.
• Vitest types for config

  /// <reference types="vitest/config" />
  import { defineConfig } from 'vitest/config';

  For proper TypeScript support and intellisense in `vitest.config.ts`, especially when using `defineConfig` from `vitest/config`, include the triple-slash reference directive. This is standard Vitest practice.

Quickstart

Demonstrates how to set up `vitest-environment-clarinet` in `vitest.config.ts` and write basic TypeScript tests that interact with Clarinet smart contracts using the globally available `clarity` object provided by `@stacks/clarinet-sdk`.

/* package.json */
{
  "name": "my-clarinet-project",
  "version": "0.1.0",
  "description": "A Clarinet project with Vitest tests",
  "scripts": {
    "test": "vitest"
  },
  "devDependencies": {
    "@stacks/clarinet-sdk": ">=3.8.1",
    "vitest": "^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0",
    "vitest-environment-clarinet": "^3.0.0"
  }
}

/* vitest.config.ts */
/// <reference types="vitest/config" />
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'clarinet',
    // Optional: Specify test file patterns
    include: ['**/*.test.ts'],
  },
});

/* tests/example.test.ts */
import { describe, test, expect } from 'vitest';
// clarity is globally available or via context from @stacks/clarinet-sdk
// when 'clarinet' environment is used.

describe('Clarinet Contract Interaction', () => {
  test('should deploy contracts and read a value', async () => {
    // Assuming 'hello-world' is a contract in your Clarinet project
    const contractAddress = 'ST0000000000000000000000000000000000000001.hello-world';
    
    // Example: Reading a public variable
    const response = await clarity.contract.callReadOnlyFn(
      contractAddress,
      'get-message',
      [], // No arguments
      clarity.deployerWallet.address
    );
    
    expect(response.result).toBe('"Hello, World!"');
  });

  test('should execute a public function', async () => {
    const contractAddress = 'ST0000000000000000000000000000000000000001.hello-world';
    
    const { result } = await clarity.submit.call(
      contractAddress,
      'set-message',
      [clarity.string('New Message')],
      clarity.deployerWallet
    );

    expect(result.isOk).toBe(true);
    // You can also assert on events, transactions, etc.
  });
});