Agent skill

plugin-test-framework

Virtual test environment for Claude Code hooks, plugins, and agents. Use when testing or validating plugin components without affecting production.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/plugin-test-framework

SKILL.md

Plugin Test Framework

Create isolated virtual test environments to verify hooks, plugins, and agents work correctly.

Quick Start

bash
# Create test environment
/skillmaker:test-env hook     # Hook test environment
/skillmaker:test-env plugin   # Full plugin test
/skillmaker:test-env agent    # Agent test

# Run tests
/skillmaker:run-tests /tmp/test-env

Test Environment Structure

/tmp/plugin-test-{uuid}/
├── .claude/
│   ├── settings.json          # Hook configurations
│   └── hooks/
│       ├── *.sh               # Hook scripts
│       └── logs/              # Execution logs
├── .claude-plugin/
│   └── plugin.json            # Plugin metadata
├── commands/
│   └── *.md                   # Slash commands
├── skills/
│   └── */SKILL.md             # Skills
├── agents/
│   └── *.md                   # Agent definitions
├── run-tests.sh               # Test runner
└── TEST-RESULTS.md            # Results

Test Types

1. Hook Tests

Verify hook scripts respond correctly to events.

Test Cases:

Test Input Expected
Block dangerous command rm -rf / permissionDecision: "deny"
Modify input npm publish updatedInput with --dry-run
Auto-allow safe echo hello permissionDecision: "allow"
Log success PostToolUse + success success: true in log
Log failure PostToolUse + error success: false in log
Context inject UserPromptSubmit stdout becomes context
Stop control Stop + incomplete decision: "block"

Hook Test JSON Format:

json
{
  "session_id": "test-001",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {"command": "rm -rf /important"},
  "cwd": "/tmp/test"
}

2. Plugin Tests

Verify plugin structure and component registration.

Validation Checks:

  • .claude-plugin/plugin.json exists and valid
  • commands/*.md have correct frontmatter
  • skills/*/SKILL.md have correct structure
  • agents/*.md have correct format
  • hooks/hooks.json is valid (if exists)

Plugin Structure Validation:

bash
# Check required fields in plugin.json
jq -e '.name and .description' .claude-plugin/plugin.json

# Validate command frontmatter
for cmd in commands/*.md; do
  grep -q "^description:" "$cmd"
done

3. Agent Tests

Verify agent definitions and tool access.

Agent Test Cases:

Test Check
Tool list valid All tools exist in Claude Code
Description present Non-empty description
Prompt template Valid prompt structure
Model specification Valid model (sonnet/opus/haiku)

Test Runner API

Create Test Environment

bash
create_test_env() {
    local TYPE="$1"  # hook, plugin, agent, full
    local TEST_DIR="/tmp/plugin-test-$(date +%s)"

    mkdir -p "$TEST_DIR/.claude/hooks/logs"
    mkdir -p "$TEST_DIR/.claude-plugin"
    mkdir -p "$TEST_DIR/commands"
    mkdir -p "$TEST_DIR/skills/test-skill"
    mkdir -p "$TEST_DIR/agents"

    # Generate based on type
    case "$TYPE" in
        hook) generate_hook_tests "$TEST_DIR" ;;
        plugin) generate_plugin_tests "$TEST_DIR" ;;
        agent) generate_agent_tests "$TEST_DIR" ;;
        full) generate_all_tests "$TEST_DIR" ;;
    esac

    echo "$TEST_DIR"
}

Run Tests

bash
run_tests() {
    local TEST_DIR="$1"
    local RESULTS="$TEST_DIR/TEST-RESULTS.md"

    echo "# Test Results" > "$RESULTS"
    echo "Date: $(date)" >> "$RESULTS"

    # Hook tests
    if [ -d "$TEST_DIR/.claude/hooks" ]; then
        run_hook_tests "$TEST_DIR" >> "$RESULTS"
    fi

    # Plugin validation
    if [ -f "$TEST_DIR/.claude-plugin/plugin.json" ]; then
        validate_plugin "$TEST_DIR" >> "$RESULTS"
    fi

    # Agent validation
    if [ -d "$TEST_DIR/agents" ]; then
        validate_agents "$TEST_DIR" >> "$RESULTS"
    fi

    cat "$RESULTS"
}

Hook Test Templates

PreToolUse Guard Hook

bash
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

# Block dangerous patterns
if echo "$COMMAND" | grep -qE "rm\s+-rf\s+/"; then
    jq -n '{
      "hookSpecificOutput": {
        "permissionDecision": "deny"
      },
      "systemMessage": "Dangerous command blocked"
    }'
    exit 0
fi

exit 0

PostToolUse Logger

bash
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
RESPONSE=$(echo "$INPUT" | jq -c '.tool_response // {}')

SUCCESS=true
echo "$RESPONSE" | grep -qiE "(error|failed)" && SUCCESS=false

jq -n --arg tool "$TOOL_NAME" --argjson success "$SUCCESS" \
    '{tool: $tool, success: $success, timestamp: now|todate}'

UserPromptSubmit Context Injector

bash
#!/bin/bash
INPUT=$(cat)

# stdout becomes Claude context
echo "=== Test Context ==="
echo "Environment: TEST"
echo "Time: $(date)"
echo "==================="

exit 0

Plugin Validation

plugin.json Schema

json
{
  "name": "string (required)",
  "description": "string (required)",
  "version": "string (optional)",
  "author": {
    "name": "string",
    "email": "string"
  }
}

Command Frontmatter

yaml
---
description: Required description
argument-hint: Optional hint
allowed-tools: ["Tool1", "Tool2"]
---

Skill Structure

skills/skill-name/
├── SKILL.md          # Required
└── references/       # Optional
    └── *.md

Agent Validation

Agent Format

markdown
---
description: Agent description
allowed-tools: ["Read", "Write", "Bash"]
model: haiku  # or sonnet, opus
---

# Agent Name

Agent prompt content...

Valid Tools List

Read, Write, Edit, Bash, Glob, Grep, Task,
TodoWrite, WebFetch, WebSearch, AskUserQuestion,
NotebookEdit, NotebookRead, KillShell, Skill

Usage Examples

Test a Hook Script

bash
# Simulate PreToolUse event
echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | \
    ./hook-script.sh

Validate Plugin Structure

bash
# Quick validation
test -f .claude-plugin/plugin.json && \
    jq -e '.name' .claude-plugin/plugin.json && \
    echo "Plugin valid"

Test Agent Definition

bash
# Check agent frontmatter
head -10 agents/my-agent.md | grep -E "^(description|allowed-tools|model):"

Test Results Format

markdown
# Test Results
Date: 2026-01-02

## Hook Tests
- ✅ Block dangerous rm
- ✅ Modify npm publish
- ✅ Auto-allow safe commands
- ✅ Log tool usage

## Plugin Validation
- ✅ plugin.json valid
- ✅ Commands have frontmatter
- ✅ Skills structured correctly

## Agent Validation
- ✅ All agents have descriptions
- ✅ Tool lists valid

## Summary
- Passed: 10/10
- Failed: 0/10

Integration with CI

yaml
# .github/workflows/test-plugin.yml
name: Plugin Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create test environment
        run: ./scripts/create-test-env.sh
      - name: Run tests
        run: ./scripts/run-tests.sh
      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: TEST-RESULTS.md

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results