/
Docs/Developer

Testing & Validation

Validate your plugin before submitting to the Marketplace.

Before submitting your plugin for review, validate it locally. The plugin system provides several levels of validation.

Live testing

The fastest way to test is to edit the plugin file in your workspace:

  1. Create _stoa_plugins/your-plugin.js in any project
  2. Edit the file — output updates in ~100ms
  3. Check both sidebar and full-panel modes (click "Open" on the widget)
  4. Test with real data where possible

Tip

Test with empty data, missing fields, and error conditions. Reviewers will check these cases.

Manifest validation

Check that your plugin header is well-formed:

  • @stoa-plugin marker is present
  • @name is set and descriptive (2-3 words)
  • @type is one of widget, renderer, or agent
  • @icon is a valid Lucide icon name
  • @refresh uses a valid unit (s, m, h)
  • @filetype patterns are valid globs (renderer plugins only)
  • @permissions uses valid network: syntax
  • @toolbar is one of pills, menu, or icons (agent plugins only)

Output validation

Verify your render() return value:

  • Has a type field
  • type is one of the supported output types
  • Required fields are present for the output type (e.g., columns and rows for table)
  • No unexpected fields that would be silently ignored
  • editableTable plugins export an onEdit function
  • editableHtml plugins export an onEdit function and define window.hydrate in the iframe

Checklist before submission

All plugins

  • Plugin loads without errors
  • Output renders correctly in the sidebar
  • Empty and error states are handled gracefully
  • @permissions are minimal — only declare what you actually use
  • @refresh interval is reasonable (don't hammer APIs)
  • @name and @icon are clear and descriptive

Widgets

  • Sidebar mode is compact (3-5 items)
  • Full-panel mode adds meaningful detail
  • Both modes are tested
  • Network errors show { type: 'error' }, not blank output

Renderers

  • Empty files handled: { type: 'empty', message: '...' }
  • Parse errors handled: { type: 'error', message: '...', details: '...' }
  • onEdit returns valid file content (for editable renderers)
  • onEdit handles all edit kinds (cell, addRow, deleteRow)
  • File round-trips: edit a cell, check the raw file content is correct

Agent plugins

  • Prompt text is clear and complete
  • {activeFile} placeholders work with and without a file open
  • Labels are short enough for the toolbar
  • Groups are logical (menu mode)

Performance

Plugins have a 5-second execution timeout. For most plugins this is generous, but keep in mind:

  • fetch() requests count toward the timeout
  • Large data processing should be efficient
  • Avoid unnecessary work in the render function — it runs on every refresh

What reviewers check

When you submit to the Marketplace, a Stoa team member will:

  1. Install your plugin in a real workspace
  2. Test sidebar and full-panel modes
  3. Test with empty/missing data
  4. Review permissions for security
  5. Check that the output uses native types where appropriate
  6. Verify error handling
  7. Give specific, constructive feedback

Most plugins go through 1-2 feedback rounds before approval.