Testing and Debugging Plugins

This page shows how to see what your plugin does, how to test it safely and how to fix each error.

Read the logs

Write log lines in your code:

ctx.log.info("Starting the sync.");
ctx.log.warn("The CRM answered slowly.");
ctx.log.error("The CRM refused the key.");

To read them, go to Application > Plugins, open your plugin and click Logs. The page shows the newest 200 lines, each with its level and hook.

Good to know:

• Lines are kept for 30 days.
• A line can have 2,000 characters.
• Broadcast hides email addresses in logs: ada@example.com becomes a***@example.com. Other personal data is not hidden, so do not log it.
• console.log does not reach this page. Use ctx.log.
• A log line is saved when the call ends. It is saved also when your code throws, so log before the risky step.

Test before you deploy: drafts

A draft is a version that is not live. You can run its hooks against test data, and nothing real happens:

• Subscribers are generated: person1@example.test to person25@example.test, with IDs 1 to 25.
• Writes are simulated. Nothing changes.
• There is no network. fetch answers only from the fixtures you pass.
• Settings and secrets are only the ones you pass.
• Your real data is never read.

To use drafts, you need a plugin developer token:

1. Go to Application > Admin API Tokens.
2. Create a token and turn on Plugin developer. It cannot have other permissions, and it expires within 30 days.

There are two ways to use it: with an AI agent or with the plugin kit.

With an AI agent

Connect your agent to Broadcast as MCP Server explains, with the plugin developer token. The agent then gets these tools:

An agent cannot deploy. Only an admin can do that, in Application > Plugins.

With the plugin kit

The plugin kit is a folder with a command line tool. It needs Node 22 or later, and it has no other dependencies.

From your plugin folder, run the tool with its path. Set your server and token first:

export BROADCAST_URL=https://your-broadcast-server
export BROADCAST_TOKEN=your-plugin-developer-token
node path/to/plugin_kit/cli/broadcast-plugin.mjs push

The output lists each file and ends with this:

Pushed. Next: broadcast-plugin validate, then broadcast-plugin test.

Then check the draft:

node path/to/plugin_kit/cli/broadcast-plugin.mjs validate

{
  "valid": true,
  "errors": [],
  "permissions": []
}

Save the test event in a file named args.json. The arguments are a list, with one item for each argument of the hook:

[{ "id": "evt_1", "type": "subscriber.created", "data": { "subscriber_id": 1 } }]

Run the hook:

node path/to/plugin_kit/cli/broadcast-plugin.mjs test --hook onEvent --args args.json

{
  "ok": true,
  "result": { "ok": true },
  "error": null,
  "ms": 284.941
}

Read the log lines of the test:

node path/to/plugin_kit/cli/broadcast-plugin.mjs logs --limit 5

When you are happy, send it for review with submit.

The kit has other commands too:

Hook names for a test

Use these names with --hook or in plugin_draft_test. Some are not the same as the name in your code:

Fixtures: fake network answers

A test has no network. To test code that uses fetch, pass a list of answers. A URL that ends in * matches any address that starts the same way.

node path/to/plugin_kit/cli/broadcast-plugin.mjs test --hook onEvent --args args.json \
  --fixtures '[{"method":"POST","url":"https://hooks.slack.com/*","status":200,"body":"ok"}]' \
  --secrets '{"webhook_url":"https://hooks.slack.com/services/T0/B0/X"}'

If no fixture matches, fetch fails with No fixture for POST https://....

What drafts simulate

• ctx.store.forSubscriber works on the 25 test people only. Another id answers not_found, as the live store does for a person outside the channel.
• A tag or custom field that holds a topic is refused, as in a live call.
• An event with webhook: true sends nothing. The test writes a log line that says what would go out.

What drafts cannot test

• Pages do not open from a draft.
• Merge tags, filters and links in a real email need a live plugin.

For these, deploy the plugin to a channel that has only your own test subscribers.

Check that it is really running

Use this list when a live plugin does nothing:

1. Application > Plugins says the runtime is running.
2. The list shows a version, not Not deployed.
3. The channel shows On.
4. The hook is in the manifest, and the function name matches it.
5. The logs show a line for the call.

A plugin that failed too often shows Turned off after repeated errors, with the last error. Deploy a version to turn it on again.

Errors from a call

A failed call in the logs or test output has a code. A refused ctx call throws an error with the same code.

These codes come from Broadcast, and they are not the plugin’s fault. They do not count toward the 20 failures: safe_mode, not_enabled, runtime_unavailable, busy and incompatible.

Messages you may see

Errors from an upload

Broadcast shows these when you upload a plugin or validate a draft. The text in <angle brackets> changes.

The package

The version

Identity and requires

Settings

Permissions

Hooks

Pages

Code

These start with dist/main.js:.

Events and segment rules have their own messages. They name the field and say what it needs. See Plugin Events and Segment Rules.

Turning a plugin on