Testing and Troubleshooting

A successful build validates packaging and registration. It does not prove the extension works inside a real workspace, survives offline edits, or upgrades old content safely.

Local checks

Run the starter’s checks from the extension directory:

bun run typecheck
bun run build

Add a test runner when you add behavior worth testing; the minimal starter has no test script. In packages that already define one, run it too. Prefer focused tests for:

• Slot initialization and logical schema validation.
• Every migration step, including invalid input and already-current resources.
• Search extraction, import/export conversion, and worker logic.
• Activation registrations, IDs, matching view requirements, and cleanup.
• UI behavior when loading, read-only, empty, or failing.

Use preparePluginActivation in SDK-based lifecycle tests when you need registration validation and cleanup semantics. Calling activate with mocked registrar methods alone does not exercise the host’s full validation. React tests need host capability mocks or a host harness; do not add private SDK imports to shipped extension code to make a standalone preview work.

Add a first contract test

For the version 1 review-card example, save this as src/index.test.ts. Bun includes a test runner, so this example needs no additional test dependency:

import { expect, test } from "bun:test";
import { preparePluginActivation } from "@lunarisapp/plugin-sdk";
import plugin, { cardPayload } from "./index";
 
test("review card accepts saved booleans and rejects malformed data", () => {
  expect(cardPayload.parse({ reviewed: false })).toEqual({ reviewed: false });
  expect(cardPayload.safeParse({ reviewed: "false" }).success).toBe(false);
  expect(cardPayload.safeParse({}).success).toBe(false);
});
 
test("resource and view registrations pass SDK validation", async () => {
  const prepared = await preparePluginActivation(plugin);
  try {
    await prepared.start();
  } finally {
    await prepared.dispose();
  }
});

Run bun test. If your project’s TypeScript check includes test files, install Bun’s declarations with bun add --dev @types/bun. Keep tests out of runtime imports so they are not bundled into the extension.

This validates the data contract and registration lifecycle. Add historical payload fixtures as soon as you introduce migrations; the installed checks below still cover persistence, host permissions, and UI behavior.

Test the installed artifact

Publish to a test marketplace and install through Lunaris. Test the exact packaged artifact, not just source components.

1. Fresh install: inspect metadata/permissions, install, open the launcher or create the resource.
2. Persistence: edit, close, reopen, and restart the client. Confirm loading never replaces stored content with defaults.
3. Collaboration: edit from two clients and verify both local and remote updates render.
4. Offline: open locally available content, disconnect, edit, reconnect, and verify convergence. Test file metadata whose bytes are not cached.
5. Access: use a read-only member and verify UI plus host rejection of unauthorized writes.
6. Lifecycle: close/reopen views, disable/re-enable the extension, and test required/optional provider removal. Check subscriptions and workers stop.
7. Upgrade: install the prior release, create content, then upgrade. Verify migrations and newer unsupported schema handling.
8. Platforms: test browser and Desktop for networking, CORS, downloads, and navigation capabilities.
9. Accessibility: complete the main task with a keyboard, at narrow width, and with loading/error announcements.

Keep historical payload fixtures in tests. For resource migrations, verify that validation failure leaves the original payload untouched. Never test destructive recovery against someone’s only copy of content.

Diagnose by symptom

Use browser developer tools for the frame’s console and host-side errors. Identify the extension ID/version, resource type/schema version, host platform, and failing operation when reporting an issue. Include a minimal reproduction and sanitized error; avoid logging resource content or credentials.

Next: publishing.