clarity-test-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clarity Test Scaffold Skill

Generates test infrastructure for Clarinet projects. Creates vitest configs, package.json dependencies, test file stubs with arrange-act-assert structure, and optionally Rendezvous fuzz test files with property and invariant tests.

为Clarinet项目生成测试基础设施。创建vitest配置、package.json依赖项、包含arrange-act-assert结构的测试文件桩，还可选择性生成带有属性测试和不变量测试的Rendezvous模糊测试文件。

Usage

使用方法

This is a doc-only skill. Agents read this file to understand available subcommands and invoke them through the skill framework. The CLI interface below documents the planned implementation.

bun run clarity-test-scaffold/clarity-test-scaffold.ts <subcommand> [options]

这是一个仅文档型Skill。Agent会读取此文件以了解可用的子命令，并通过Skill框架调用它们。下方的CLI接口记录了规划中的实现方案。

bun run clarity-test-scaffold/clarity-test-scaffold.ts <subcommand> [options]

Subcommands

子命令

scaffold

Generate full test infrastructure for a Clarinet project. Creates or updates vitest config, package.json, tsconfig, and test stubs for all contracts.

bun run clarity-test-scaffold/clarity-test-scaffold.ts scaffold --project-dir <path> [--include-clarunit] [--include-fuzz] [--dry-run]

Options:

```
--project-dir
```
(required) — Path to the Clarinet project root (must contain
```
Clarinet.toml
```
)
```
--include-clarunit
```
(optional) — Also generate Clarunit test files (
```
.clar
```
test files)
```
--include-fuzz
```
(optional) — Also generate Rendezvous fuzz test files
```
--dry-run
```
(optional) — Show what would be generated without writing files

Output:

json

{
  "projectDir": "/path/to/project",
  "contracts": ["my-contract", "helper-contract"],
  "filesGenerated": [
    {"path": "vitest.config.js", "action": "created"},
    {"path": "package.json", "action": "updated"},
    {"path": "tsconfig.json", "action": "created"},
    {"path": "tests/my-contract.test.ts", "action": "created"},
    {"path": "tests/helper-contract.test.ts", "action": "created"}
  ],
  "dependencies": {
    "@hirosystems/clarinet-sdk": "^2.0.0",
    "vitest": "^1.0.0",
    "vitest-environment-clarinet": "^2.0.0"
  },
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

为Clarinet项目生成完整的测试基础设施。创建或更新vitest配置、package.json、tsconfig以及所有合约的测试桩。

bun run clarity-test-scaffold/clarity-test-scaffold.ts scaffold --project-dir <path> [--include-clarunit] [--include-fuzz] [--dry-run]

选项：

```
--project-dir
```
（必填）——项目根目录的路径（必须包含
```
Clarinet.toml
```
）
```
--include-clarunit
```
（可选）——同时生成Clarunit测试文件（
```
.clar
```
测试文件）
```
--include-fuzz
```
（可选）——同时生成Rendezvous模糊测试文件
```
--dry-run
```
（可选）——显示将生成的内容但不写入文件

输出：

json

{
  "projectDir": "/path/to/project",
  "contracts": ["my-contract", "helper-contract"],
  "filesGenerated": [
    {"path": "vitest.config.js", "action": "created"},
    {"path": "package.json", "action": "updated"},
    {"path": "tsconfig.json", "action": "created"},
    {"path": "tests/my-contract.test.ts", "action": "created"},
    {"path": "tests/helper-contract.test.ts", "action": "created"}
  ],
  "dependencies": {
    "@hirosystems/clarinet-sdk": "^2.0.0",
    "vitest": "^1.0.0",
    "vitest-environment-clarinet": "^2.0.0"
  },
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

add-fuzz

Add Rendezvous property-based fuzz tests for a specific contract.

bun run clarity-test-scaffold/clarity-test-scaffold.ts add-fuzz --project-dir <path> --contract <contract-name> [--dry-run]

Options:

```
--project-dir
```
(required) — Path to the Clarinet project root
```
--contract
```
(required) — Contract name to generate fuzz tests for
```
--dry-run
```
(optional) — Show what would be generated without writing

Output:

json

{
  "contract": "my-contract",
  "filesGenerated": [
    {"path": "contracts/my-contract.tests.clar", "action": "created"}
  ],
  "dependencies": {
    "@stacks/rendezvous": "^1.0.0"
  },
  "scripts": {
    "test:rv": "npx rv . my-contract test",
    "test:rv:invariant": "npx rv . my-contract invariant"
  },
  "publicFunctions": ["transfer", "set-value"],
  "propertyTests": ["test-transfer", "test-set-value"],
  "invariantTests": ["invariant-supply-capped"]
}

为特定合约添加Rendezvous基于属性的模糊测试。

bun run clarity-test-scaffold/clarity-test-scaffold.ts add-fuzz --project-dir <path> --contract <contract-name> [--dry-run]

选项：

```
--project-dir
```
（必填）——Clarinet项目根目录的路径
```
--contract
```
（必填）——要为其生成模糊测试的合约名称
```
--dry-run
```
（可选）——显示将生成的内容但不写入文件

输出：

json

{
  "contract": "my-contract",
  "filesGenerated": [
    {"path": "contracts/my-contract.tests.clar", "action": "created"}
  ],
  "dependencies": {
    "@stacks/rendezvous": "^1.0.0"
  },
  "scripts": {
    "test:rv": "npx rv . my-contract test",
    "test:rv:invariant": "npx rv . my-contract invariant"
  },
  "publicFunctions": ["transfer", "set-value"],
  "propertyTests": ["test-transfer", "test-set-value"],
  "invariantTests": ["invariant-supply-capped"]
}

check

Verify an existing test setup is complete and correct.

bun run clarity-test-scaffold/clarity-test-scaffold.ts check --project-dir <path>

Options:

```
--project-dir
```
(required) — Path to the Clarinet project root

Output:

json

{
  "projectDir": "/path/to/project",
  "complete": false,
  "contracts": ["my-contract", "helper-contract"],
  "findings": [
    {"type": "missing", "description": "No test file for helper-contract"},
    {"type": "config", "description": "vitest.config.js missing singleThread: true"},
    {"type": "dependency", "description": "@hirosystems/clarinet-sdk not in package.json"}
  ],
  "coverage": {
    "contractsWithTests": 1,
    "contractsTotal": 2,
    "percentage": 50
  }
}

验证现有测试设置是否完整且正确。

bun run clarity-test-scaffold/clarity-test-scaffold.ts check --project-dir <path>

选项：

```
--project-dir
```
（必填）——Clarinet项目根目录的路径

输出：

json

{
  "projectDir": "/path/to/project",
  "complete": false,
  "contracts": ["my-contract", "helper-contract"],
  "findings": [
    {"type": "missing", "description": "No test file for helper-contract"},
    {"type": "config", "description": "vitest.config.js missing singleThread: true"},
    {"type": "dependency", "description": "@hirosystems/clarinet-sdk not in package.json"}
  ],
  "coverage": {
    "contractsWithTests": 1,
    "contractsTotal": 2,
    "percentage": 50
  }
}

Generated Test Structure

生成的测试结构

Vitest Config

Vitest配置

javascript

import { defineConfig } from "vitest/config";
import { vitestSetupFilePath, getClarinetVitestsArgv } from "@hirosystems/clarinet-sdk/vitest";

export default defineConfig({
  test: {
    environment: "clarinet",
    singleThread: true,
    setupFiles: [vitestSetupFilePath],
    environmentOptions: {
      clarinet: getClarinetVitestsArgv(),
    },
  },
});

javascript

import { defineConfig } from "vitest/config";
import { vitestSetupFilePath, getClarinetVitestsArgv } from "@hirosystems/clarinet-sdk/vitest";

export default defineConfig({
  test: {
    environment: "clarinet",
    singleThread: true,
    setupFiles: [vitestSetupFilePath],
    environmentOptions: {
      clarinet: getClarinetVitestsArgv(),
    },
  },
});

Test File Template

测试文件模板

Generated test files follow these conventions:

Arrange-Act-Assert structure in every test
Functions over arrow functions for test helpers
Constants for reusable values (deployer, wallets, contract name)
NO
beforeAll
/
beforeEach
— simnet resets each session
singleThread: true
— required for simnet isolation

生成的测试文件遵循以下约定：

每个测试均采用arrange-act-assert结构
测试辅助函数使用普通函数而非箭头函数
可复用值（部署者、钱包、合约名称）使用常量定义
禁止使用
beforeAll
/
beforeEach
——simnet会重置每个会话
singleThread: true
——为simnet隔离所必需

Testing Pyramid

测试金字塔

Stxer (Historical Simulation)      — Pre-mainnet validation
RV (Property-Based Fuzzing)        — Invariants, edge cases
Vitest + Clarinet SDK              — Integration tests (default)
Clarunit                           — Unit tests in Clarity

Stxer（历史模拟）      — 主网前验证
RV（基于属性的模糊测试）        — 不变量、边缘情况
Vitest + Clarinet SDK              — 集成测试（默认）
Clarunit                           — Clarity单元测试

Notes

注意事项

Reads
```
Clarinet.toml
```
to discover contracts and generate appropriate test stubs
Analyzes contract public functions to generate test method signatures
Does not overwrite existing test files — only creates missing ones
Use
```
--dry-run
```
first to preview what will be generated
Generated tests are stubs — fill in assertions based on contract behavior
For complete testing reference, see the
```
clarity-patterns
```
skill

读取
```
Clarinet.toml
```
以发现合约并生成对应的测试桩
分析合约的公开函数以生成测试方法签名
不会覆盖现有测试文件——仅创建缺失的文件
先使用
```
--dry-run
```
预览将生成的内容
生成的测试为桩文件——需根据合约行为补充断言逻辑
如需完整的测试参考，请查看
```
clarity-patterns
```
Skill