{"id":15404,"library":"vitest-environment-clarinet","title":"Vitest Environment for Clarinet Projects","description":"The `vitest-environment-clarinet` package provides a specialized Vitest testing environment tailored for developing and testing Clarity smart contracts within Clarinet projects. It enables developers to integrate the Clarinet simulation network (simnet) directly into their Vitest test suites, facilitating interactions with deployed smart contracts in a controlled environment. The current stable version is 3.0.2, with recent releases indicating a focus on maintaining compatibility with new Vitest major versions (e.g., supporting Vitest 4.x in v2.6.0 and v3.0.0). This package differentiates itself by offering a seamless, opinionated integration for Stacks blockchain development, leveraging Vitest's speed and features while providing the necessary Clarinet context. It is typically used alongside `@stacks/clarinet-sdk` to access the `clarity` testing utilities.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/stx-labs/vitest-environment-clarinet","tags":["javascript","clarinet","clarity","test","stacks","vitest"],"install":[{"cmd":"npm install vitest-environment-clarinet","lang":"bash","label":"npm"},{"cmd":"yarn add vitest-environment-clarinet","lang":"bash","label":"yarn"},{"cmd":"pnpm add vitest-environment-clarinet","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core testing framework; this package is a custom environment for Vitest.","package":"vitest","optional":false},{"reason":"Provides the `clarity` object and other utilities for interacting with the Clarinet simnet.","package":"@stacks/clarinet-sdk","optional":false}],"imports":[{"note":"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.","wrong":"import { Clarinet } from 'vitest-environment-clarinet';","symbol":"environment: 'clarinet'","correct":"// vitest.config.ts\nimport { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n  test: {\n    environment: 'clarinet',\n  },\n});"},{"note":"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`.","symbol":"clarity (global/context)","correct":"// my-contract.test.ts\ndescribe('MyContract', () => {\n  test('should do something', async () => {\n    const response = await clarity.contract.myContract.read.someFunction();\n    expect(response.result).toBe('success');\n  });\n});"},{"note":"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.","symbol":"Vitest types for config","correct":"/// <reference types=\"vitest/config\" />\nimport { defineConfig } from 'vitest/config';"}],"quickstart":{"code":"/* package.json */\n{\n  \"name\": \"my-clarinet-project\",\n  \"version\": \"0.1.0\",\n  \"description\": \"A Clarinet project with Vitest tests\",\n  \"scripts\": {\n    \"test\": \"vitest\"\n  },\n  \"devDependencies\": {\n    \"@stacks/clarinet-sdk\": \">=3.8.1\",\n    \"vitest\": \"^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0\",\n    \"vitest-environment-clarinet\": \"^3.0.0\"\n  }\n}\n\n/* vitest.config.ts */\n/// <reference types=\"vitest/config\" />\nimport { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n  test: {\n    environment: 'clarinet',\n    // Optional: Specify test file patterns\n    include: ['**/*.test.ts'],\n  },\n});\n\n/* tests/example.test.ts */\nimport { describe, test, expect } from 'vitest';\n// clarity is globally available or via context from @stacks/clarinet-sdk\n// when 'clarinet' environment is used.\n\ndescribe('Clarinet Contract Interaction', () => {\n  test('should deploy contracts and read a value', async () => {\n    // Assuming 'hello-world' is a contract in your Clarinet project\n    const contractAddress = 'ST0000000000000000000000000000000000000001.hello-world';\n    \n    // Example: Reading a public variable\n    const response = await clarity.contract.callReadOnlyFn(\n      contractAddress,\n      'get-message',\n      [], // No arguments\n      clarity.deployerWallet.address\n    );\n    \n    expect(response.result).toBe('\"Hello, World!\"');\n  });\n\n  test('should execute a public function', async () => {\n    const contractAddress = 'ST0000000000000000000000000000000000000001.hello-world';\n    \n    const { result } = await clarity.submit.call(\n      contractAddress,\n      'set-message',\n      [clarity.string('New Message')],\n      clarity.deployerWallet\n    );\n\n    expect(result.isOk).toBe(true);\n    // You can also assert on events, transactions, etc.\n  });\n});","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.x"},{"fix":"Ensure your `vitest` installation strictly adheres to the `peerDependencies` range specified by `vitest-environment-clarinet`. Upgrade or downgrade Vitest as necessary.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that `@stacks/clarinet-sdk` is correctly installed in your project and meets the required version range of `vitest-environment-clarinet`'s `peerDependencies`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `vitest-environment-clarinet` is installed: `npm install --save-dev vitest-environment-clarinet` or `yarn add --dev vitest-environment-clarinet`.","cause":"The `vitest-environment-clarinet` package is not installed, or Vitest cannot find it in your `node_modules`.","error":"Error: Failed to load environment \"clarinet\". Make sure it is installed and exported correctly."},{"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`.","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.","error":"ReferenceError: clarity is not defined"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'contract')"}],"ecosystem":"npm"}