Registry /
testing / vitest-environment-clarinet
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
environment: 'clarinet'
✓ // vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'clarinet',
},
});
✗ import { Clarinet } from 'vitest-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.
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.
});
});
Errors
Common errors & fixes
Error: Failed to load environment "clarinet". Make sure it is installed and exported correctly.
The `vitest-environment-clarinet` package is not installed, or Vitest cannot find it in your `node_modules`.
fixEnsure `vitest-environment-clarinet` is installed: `npm install --save-dev vitest-environment-clarinet` or `yarn add --dev vitest-environment-clarinet`.
ReferenceError: clarity is not defined
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.
fix1. 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')
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.
fixEnsure 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.
Audit
Dependencies
vitestrequiredCore testing framework; this package is a custom environment for Vitest.
@stacks/clarinet-sdkrequiredProvides the `clarity` object and other utilities for interacting with the Clarinet simnet.