testing

Testing Bundle-Plugins

Overview

Dynamic verification of a bundle-plugin project: install it locally, confirm components are discoverable, validate hooks fire correctly, and run cross-platform smoke tests. Complements bundles-forge:auditing (static analysis) with runtime validation.

Core principle: Audit tells you if the structure is correct; testing tells you if it actually works.

Skill type: Flexible — adapt the test scope based on target platforms and project maturity.

Announce at start: "I'm using the testing skill to verify this plugin works correctly."

Step 1: Resolve Input & Detect Scope

Input Normalization

The target must be a local bundle-plugin project (has package.json + skills/). Remote URLs and archives are not supported — testing requires a local working directory.

Scope Detection

| Target | Mode | |--------|------| | Project root with multiple platforms | Full testing — all 5 test phases | | Project root with single platform | Platform testing — phases 1-4 for the target platform | | Single skill directory | Skill-only testing — phase 3 (component discovery) only |

Phase 1: Local Test Environment

Generate a temporary dev-marketplace for local installation testing.

For Claude Code

1. Create ../dev-marketplace/ adjacent to the project directory
2. Generate .claude-plugin/marketplace.json pointing to the project:

{
  "name": "<project-name>-dev",
  "owner": { "name": "dev" },
  "plugins": [
    {
      "name": "<project-name>",
      "source": "../<project-directory-name>"
    }
  ]
}

1. Instruct the user:

Dev marketplace created at ../dev-marketplace/

To install locally:
  /plugin marketplace add ./dev-marketplace
  /plugin install <project-name>@<project-name>-dev

To reload after changes:
  /plugin marketplace update <project-name>-dev

To clean up when done:
  /plugin marketplace remove <project-name>-dev

For Cursor

Cursor plugins are installed from local paths directly:

To test locally in Cursor:
  1. Open Cursor Settings → Extensions → Install from Path
  2. Select the project root directory
  3. Reload Cursor to pick up changes

For Other Platforms

• Codex: Symlink skills/ into ~/.agents/skills/ per INSTALL.md
• OpenCode: Register the plugin path in .opencode/plugins/
• Gemini CLI: Point the extension config to the local directory

See references/platform-test-guides.md for platform-specific setup instructions.

Phase 2: Hook Smoke Tests

Verify hooks execute without errors by running them directly.

SessionStart Hook

bash hooks/session-start

Expected: Exits 0, prints a one-line prompt containing the project name and available skills. No stderr output.

Verify output format:

• If CLAUDE_PLUGIN_ROOT is set: valid JSON with hookSpecificOutput.additionalContext
• If CURSOR_PLUGIN_ROOT is set: valid JSON with additional_context
• Neither: plain text

Custom Hooks (if configured)

If the project defines PreToolUse or PostToolUse hooks in hooks.json, run each referenced script directly and verify:

• PreToolUse scripts: exit 0 on a valid project, exit 2 to block writes on critical issues
• PostToolUse scripts: always exit 0, warnings go to stderr

OpenClaw Hook-Pack (if present)

Verify hooks/openclaw-bootstrap/HOOK.md has valid YAML frontmatter with events declaration, and handler.js uses ESM export default.

Phase 3: Component Discovery

Verify that all declared components can be found by the host platform.

Skills

For each directory under skills/:

• [ ] Contains SKILL.md
• [ ] Frontmatter has name and description
• [ ] name matches directory name
• [ ] description starts with "Use when..."

Agents

For each .md file under agents/:

• [ ] Has YAML frontmatter
• [ ] Body has 5+ non-empty lines (self-contained protocol)

Platform Manifests

For each target platform:

• [ ] Manifest file exists and is valid JSON
• [ ] Paths in manifest resolve to existing files/directories
• [ ] Version matches package.json version

Phase 4: Cross-Platform Readiness

Generate a platform-specific test checklist based on references/platform-test-guides.md and known limitations from bundles-forge:scaffolding — references/platform-adapters.md.

Known Limitations to Verify

| Platform | Limitation | Test | |----------|-----------|------| | Claude Code | Plugin caching breaks ../ paths | Verify no ../ in hook commands or manifest paths | | Cursor | Bootstrap lost after /clear | Verify session-start runs independently of prior context | | Codex | No hook bootstrap | Verify AGENTS.md or INSTALL.md has manual setup instructions | | OpenCode | Plugin JS must use ESM | Verify export default in .opencode/plugins/*.js | | Gemini CLI | Extension needs contextFileName | Verify gemini-extension.json has contextFileName field | | OpenClaw | Hook-pack wiring uncertain | Document as known risk in test report |

Phase 5: Test Report

Generate a test report summarizing all findings.

Report Structure

# Test Report: <project-name>

**Date:** YYYY-MM-DD
**Scope:** [Full / Platform / Skill-only]
**Platforms tested:** [list]

## Results

| Phase | Status | Details |
|-------|--------|---------|
| 1. Local Environment | PASS/FAIL/SKIP | ... |
| 2. Hook Smoke Tests | PASS/FAIL/SKIP | ... |
| 3. Component Discovery | PASS/FAIL/SKIP | N skills, K agents |
| 4. Cross-Platform | PASS/FAIL/SKIP | ... |

## Issues Found

### Critical
- (blocks release)

### Warnings
- (should fix before release)

## Recommendations

- ...

Report location: .bundles-forge/audits/<timestamp>-test-report.md

Integration with Releasing

In the releasing pipeline, testing runs after auditing and before version bump:

audit → test → version bump → publish

If testing reveals critical issues, the release pipeline is blocked until they are resolved.

Common Mistakes

| Mistake | Fix | |---------|-----| | Skipping local install test | Always test with a real dev-marketplace — file discovery differs from file existence | | Testing only on one platform | Run cross-platform checklist for every target platform | | Ignoring hook exit codes | Hooks must exit 0 to avoid blocking the host; test all code paths | | Not cleaning up dev-marketplace | Always remove dev-marketplace after testing | | Testing after version bump | Test before bumping — avoid releasing a broken version |

Inputs

• project-directory (required) — bundle-plugin project root

Outputs

• test-report — comprehensive test results written to .bundles-forge/audits/
• dev-marketplace (temporary) — local marketplace directory for installation testing

Integration

Called by:

• bundles-forge:releasing — pre-release dynamic verification (after audit, before version bump)
• User directly — standalone local testing during development

Calls:

• (none — testing is a pure executor, does not dispatch other skills)