Testing

This guide covers how to test your mini app during development, from local browser testing to full integration testing in the Alien app.

Local Development

During development, you can run your mini app in a regular browser. The SDK operates in development mode when the bridge is unavailable (i.e., window.__ALIEN_AUTH_TOKEN__ and other host-injected globals are not present).

bun dev
# or: npm run dev

What works in the browser:

• UI rendering and styling
• Application logic and state management
• API calls to your backend
• Navigation and routing

What doesn’t work:

• Bridge communication with the host app
• Native features (payments, clipboard, link opening, haptic feedback)

The SDK logs warnings instead of throwing errors, so your app won’t crash. Bridge functions return graceful fallbacks.

 
// Check if running in Alien app
if (isBridgeAvailable()) {
  // Bridge methods will work
} else {
  // Dev mode - bridge methods log warnings and return gracefully
}

Mock Bridge

For testing bridge interactions without the Alien app, use createMockBridge. It injects a simulated bridge and launch params into window globals, allowing all bridge methods to work.

import { createMockBridge } from '@alien_org/bridge/mock';
 
const mock = createMockBridge({
  launchParams: {
    authToken: 'test-token',
    contractVersion: '1.0.0',
    platform: 'ios',
  },
  handlers: {
    'payment:request': (payload) => ({
      status: 'paid',
      txHash: 'mock-tx-123',
      reqId: payload.reqId,
    }),
  },
  delay: 100,
});
 
// Later: clean up
mock.cleanup();

The mock bridge provides default responses for all request-response methods (payment:request, clipboard:read, wallet methods). Set a handler to false to suppress the response entirely.

See Bridge Reference — Mock Bridge for full documentation.

Testing in the Alien App

To test the full integration with native features, launch your mini app inside the Alien app.

Steps

1. Deploy your app to a publicly accessible URL
2. Go to your mini app dashboard in the Developer Portal 
3. Copy the deeplink for your mini app
4. Open the deeplink on your device — your mini app launches in the Alien app

Launch Parameters

When the Alien app loads your mini app, it provides launch parameters. Use the useLaunchParams hook to access them:

 
function App() {
  const launchParams = useLaunchParams();
 
  if (!launchParams) {
    return <div>Running outside Alien App</div>;
  }
 
  return <div>Platform: {launchParams.platform}</div>;
}

Available parameters:

Deeplink Testing

Share deeplinks to launch your mini app directly:

https://alien.app/miniapp/{slug}

With a custom start parameter:

https://alien.app/miniapp/{slug}?startParam={value}

The startParam value is available via useLaunchParams(). Use this for:

• Referral tracking
• Deep navigation to specific content
• Campaign attribution
• Pre-filling form data

Example:

https://alien.app/miniapp/my-game?startParam=level-5

 
function Game() {
  const launchParams = useLaunchParams();
 
  useEffect(() => {
    if (launchParams?.startParam === 'level-5') {
      navigateToLevel(5);
    }
  }, [launchParams?.startParam]);
 
  // ...
}

Debugging Tips

Check Bridge Availability

 
function DebugInfo() {
  const { isBridgeAvailable } = useAlien();
 
  if (isBridgeAvailable) {
    console.log('Running in Alien app');
  } else {
    console.log('Running in browser (dev mode)');
  }
 
  // ...
}

Log Launch Parameters

 
function DebugInfo() {
  const launchParams = useLaunchParams();
 
  console.log('Launch params:', {
    authToken: launchParams?.authToken ? 'present' : 'missing',
    contractVersion: launchParams?.contractVersion,
    hostVersion: launchParams?.hostAppVersion,
    platform: launchParams?.platform,
    startParam: launchParams?.startParam,
    displayMode: launchParams?.displayMode,
  });
 
  // ...
}

Remote Debugging

iOS: Use Safari Web Inspector to debug the WebView.

1. Enable “Web Inspector” in Safari settings on your device
2. Connect your device to your Mac
3. Open Safari > Develop > [Your Device] > [Your App]

Android: Use Chrome DevTools.

1. Enable USB debugging on your device
2. Connect your device to your computer
3. Open chrome://inspect in Chrome
4. Select your WebView under “Remote Target”

Common Issues

Next Steps

• Authentication — Implement user authentication
• Payments — Accept payments with webhook verification
• React SDK — Full hooks reference