clarity-test-scaffold

Clarity テストのスキャフォールドスキル

Clarinet プロジェクトのテストインフラストラクチャを生成します。vitest の設定、package.json の依存関係、Arrange-Act-Assert 構造のテストファイルのスタブを作成し、必要に応じてプロパティテストと不変条件テストを含む Rendezvous のファズテストファイルも生成します。

使用方法

このスキルはドキュメント専用です。エージェントはこのファイルを読んで利用可能なサブコマンドを確認し、スキルフレームワークを通じて実行します。以下の 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 スキルを参照してください