Testing

Test your add-on locally and in draft mode before publishing to the marketplace.

Local Development Setup

Configure the SDK for local testing

src/main.tsx

import { SyncBooksProvider, configureClient } from '@syncbooks/addon-sdk'

// Override API URL and token for local development
if (import.meta.env.DEV) {
  configureClient({
    baseUrl: 'http://localhost:5000/api/addon/v1',
    token: 'YOUR_TEST_TOKEN', // See step 2 for how to get this
  })
}

Get a test token

To get a valid session token:

Register your add-on on the marketplace (draft mode)
Install it on your organization
Open browser DevTools → Network tab
Click your add-on in SyncBooks to open it
In Network tab, find the iframe request
The URL contains syncbooks_token=eyJhbG...
Copy that token value into your configureClient call

Tokens expire after 1 hour

You'll need a fresh token each development session. To avoid this, keep SyncBooks open in another tab and get a new token when yours expires.

Run your dev server

Terminal

npm run dev
# Addon runs at http://localhost:5173
# API calls go to http://localhost:5000 (your local backend)

Draft Mode Testing

The best way to test is in draft mode within SyncBooks itself:

Deploy your add-on (even to a preview URL)
Register it in the marketplace with status "Draft"
Install it on your org — only you can see draft add-ons
Open it from the Add-ons page
Everything works with real data and real authentication

Use Vercel preview deployments

Push a branch to GitHub with Vercel connected. Each push creates a preview URL you can use as the Launch URL for testing. No need to wait for production deploys.

Testing Without SyncBooks (Standalone)

For rapid iteration without the iframe:

src/test-setup.ts

import { configureClient } from '@syncbooks/addon-sdk'

// Mock the context that SyncBooksProvider normally provides
configureClient({
  baseUrl: 'http://localhost:5000/api/addon/v1',
  token: 'your-test-token',
})

// Your components will work standalone — API calls go through,
// but postMessage features (navigation, toasts) won't work outside SyncBooks

Common Testing Scenarios

Test with no data

Use a fresh organization to verify your empty states work correctly.

Test with missing permissions

Install your add-on but deselect some scopes. Verify your add-on handles 403 errors gracefully and shows appropriate messages.

Test token expiry

Wait 1 hour (or use an expired token) to verify your add-on shows a "session expired" message instead of crashing.

Test responsive layout

The iframe can be as narrow as 300px on mobile. Test your add-on at small widths.

Debugging Tips

// Check if the bridge is connected
import { getContext } from '@syncbooks/addon-sdk'
const ctx = getContext()
console.log('Context:', ctx)  // null if not connected yet

// Check granted scopes
const { scopes } = useSyncBooks()
console.log('Scopes:', scopes)

// Check API responses
import { customers } from '@syncbooks/addon-sdk'
try {
  const result = await customers.list()
  console.log('Customers:', result)
} catch (e) {
  console.error('API Error:', e.status, e.message, e.response)
}

Next Steps

Deployment — deploy to production hosting
Marketplace — submit for review