BROWSE / BUILD AND SHARE

Testing and troubleshooting

Validate your manifest, exercise callbacks and diagnose failures in Browse.

Developer preview · macOS · Python SDK 1.1

The developer tools

Download and unzip the SDK, then run these commands from the browse-extension-sdk folder. Substitute your plugin folder for examples/reading-list when testing your own code.

Download the Python SDK and examples (ZIP)

sh bin/browse-ext check examples/reading-list
sh bin/browse-ext run examples/no-shorts --request "https://www.youtube.com/shorts/abc"
sh bin/browse-ext run examples/reading-list --command "Save Tab to Reading List" --panel
sh bin/browse-ext run examples/reading-list --panel reading --click "reading:Save Tab" --panel reading

check validates the manifest and the entry file’s Python syntax. run starts your Python code against a simulated browser. Steps execute in the order you give them.

Flag	Action
--request URL	Ask the navigation hook for a decision.
--page URL	Send a simulated page-load event.
--command TITLE	Run a registered command.
--panel [ID]	Render a panel to text. Omit the ID for the first panel.
--click PANEL:LABEL[=VALUE]	Invoke a button, toggle or field callback.
--wait SECONDS	Allow schedules or tasks to run.
--json	Print raw result data.

Test in Browse

Choose Settings → Extensions → Add… → Add Development Folder… and select the folder containing browse.toml.
Review the requested permissions. Check commands, panels and widgets with an empty window as well as with tabs open.
Save changes to Python, TOML, CSS, JavaScript or JSON files to reload a development extension. Use Reload if needed.
Test both an allowed site and an unrelated site. Test redirect destinations and missing permissions.
Pack the plugin, then install the archive with Add Extension… to verify that every required file is included.

Common problems

Symptom	What to check
Python is missing	Install Python 3.11+ and reopen Browse. Settings → Extensions reports runtime availability.
The plugin will not load	Check browse.toml, the main entry path and Python syntax; read the extension log.
PermissionDenied	Add the specific permission to the manifest, reload and approve the changed permissions.
The hook never runs	Both its match pattern and its granted permission must cover the URL. Page scripts apply to the main frame.
The panel looks stale	Callbacks refresh automatically. For other changes, call panel.refresh() or pass the panel’s explicit ID.
The plugin keeps stopping	Read the traceback or log and fix the error, then Reload. Repeated crashes can leave it stopped.
It works in the harness but fails in Browse	Check sandbox restrictions, resource limits and actual page behaviour. Use storage and net instead of direct files or sockets.
An icon falls back to a symbol	Verify the packaged path, image type, size and dimensions.

← All documentation