run-tests

Run Tests Skill

This skill runs Clarity contract tests using Vitest + Clarinet SDK and helps diagnose common errors.

When to Use

• User wants to run tests
• User asks about test coverage
• User encounters test failures or errors
• After implementing contract changes to verify correctness

Instructions

Step 1: Verify Project Setup

Check for Clarinet project:

ls Clarinet.toml 2>/dev/null && echo "Clarinet project found" || echo "No Clarinet.toml found"

If no Clarinet.toml, check common monorepo locations:

• clarity/Clarinet.toml
• contracts/Clarinet.toml
• packages/contracts/Clarinet.toml

If found in subdirectory, cd there first.

Check test setup exists:

ls vitest.config.js vitest.config.ts 2>/dev/null
ls package.json 2>/dev/null

If missing vitest config, tell the user: "I don't see a Vitest configuration. Would you like me to set up the testing environment? I'll create:

• vitest.config.js with Clarinet SDK setup
• Test scripts in package.json
• A sample test file"

Step 2: Run Contract Check First

Always run clarinet check before tests to compile contracts:

clarinet check

Common errors:

• Syntax errors - Show the error and offer to fix
• Unknown function - Contract may reference undefined function
• Type mismatch - Function argument types don't match

If clarinet check fails, diagnose and fix before proceeding to tests.

Step 3: Run Tests

Detect test command from package.json:

cat package.json | grep -A 5 '"scripts"'

Run tests (in order of preference):

1. If test script exists: npm run test
2. Otherwise: npx vitest run

npm run test

Step 4: Diagnose Common Errors

Error: "toBeOk is not a function" or "toBeErr is not a function"

This means the Clarinet SDK vitest setup file is missing.

Check vitest.config.js:

cat vitest.config.js

Fix: Ensure setupFiles includes the Clarinet SDK setup:

import { vitestSetupFilePath } from "@hirosystems/clarinet-sdk/vitest";

export default defineConfig({
  test: {
    setupFiles: [vitestSetupFilePath],
    // ...
  }
});