clarity-test-scaffold

Clarity 测试脚手架技能

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

用法

这是一项仅包含文档的技能。Agent 会阅读此文件以了解可用的子命令，并通过技能框架调用它们。以下 CLI 接口记录了计划中的实现。

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

子命令

scaffold

为 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 项目根目录的路径（必须包含 Clarinet.toml）
• --include-clarunit（可选）— 同时生成 Clarunit 测试文件（.clar 测试文件）
• --include-fuzz（可选）— 同时生成 Rendezvous 模糊测试文件
• --dry-run（可选）— 显示将要生成的内容，但不写入文件

输出：

{
  "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

为指定合约添加基于属性的 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（可选）— 显示将要生成的内容，但不写入文件

输出：

{
  "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

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

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

选项：

• --project-dir（必需）— Clarinet 项目根目录的路径

输出：

{
  "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
  }
}

生成的测试结构

Vitest 配置

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(),
    },
  },
});

测试文件模板

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

• 每个测试都采用 Arrange-Act-Assert 结构
• 测试辅助函数使用 普通函数而非箭头函数
• 可复用的值使用 常量（部署者、钱包、合约名称）
• 不使用 beforeAll/beforeEach — simnet 会在每次会话中重置
• singleThread: true — simnet 隔离所必需

测试金字塔

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

注意事项

• 读取 Clarinet.toml 以发现合约并生成相应的测试存根
• 分析合约的公开函数以生成测试方法签名
• 不会覆盖现有测试文件 — 只会创建缺失的文件
• 使用 --dry-run 预览将要生成的内容
• 生成的测试是存根 — 请根据合约行为补充断言
• 完整的测试参考请参阅 clarity-patterns 技能