Testing native builds

This page is about testing the native shell: things like windowing, notifications, deep links, the updater, or anything else that only exists once the client is running inside Tauri. If you’re testing an AppView change, you don’t need any of this. Run the web client with pnpm dev:client against your local AppView instead. That loop is much faster than getting a native build to talk to a local AppView, and it’s the only supported way to test AppView-level changes.

The shell renders the client’s built output, so build the client first:

pnpm --filter @colibri-social/client build

Run every Tauri command through pnpm --filter @colibri-social/wrapper tauri ..., not the raw @tauri-apps/cli. It’s wrapped by packages/wrapper/scripts/tauri.mjs, which handles the DISABLE_SENTRY flag documented in packages/wrapper/README.md.

Desktop (macOS, Windows, Linux)

There’s no emulator or device split on desktop. Running the dev server or the built binary on your own machine is the test.

Build:

pnpm dev:tauri                                                 # hot-reloading dev build
pnpm --filter @colibri-social/wrapper tauri build --no-bundle  # quick compile, matches CI's PR job
pnpm --filter @colibri-social/wrapper build:macos:direct       # Developer ID / Homebrew channel
pnpm --filter @colibri-social/wrapper build:macos:appstore     # Mac App Store channel
pnpm --filter @colibri-social/wrapper tauri:windows:build      # MSIX for the Microsoft Store
pnpm --filter @colibri-social/wrapper \
  tauri build --features tauri/devtools                        # With developer tools enabled

A full tauri build needs TAURI_SIGNING_PRIVATE_KEY and TAURI_SIGNING_PRIVATE_KEY_PASSWORD set, since the updater plugin is enabled by default. Generate a throwaway keypair with pnpm --filter @colibri-social/wrapper tauri signer generate if you don’t have one, or build against tauri.appstore.conf.json, which compiles the updater out entirely.

Windows

The bare executable from tauri build --no-bundle does not complete the social.colibri:/oauth/callback deep link, so OAuth sign-in never finishes on it. The browser hands off correctly and the app is simply never brought up. Other deep links such as social.colibri:/invite/<code> do route fine on the same binary, so the app looks healthy right up until you try to log in. Build and sideload an MSIX for anything touching sign-in or deep links.

If you need to test this nonetheless, do the following:

Create packages/wrapper/src-tauri/tauri.windows.conf.json. It is gitignored because the Microsoft Store job generates it at release time, so it won’t exist after a fresh clone:
```
{
  "mainBinaryName": "ColibriSocial"
}
```
This is not optional. The bundler derives the payload executable name from productName with spaces removed, so it looks for ColibriSocial.exe, while Tauri otherwise emits colibri-social.exe. Without the override the bundler silently packages whatever stale ColibriSocial.exe is still sitting in src-tauri/target/x86_64-pc-windows-msvc/release/ from an earlier run, and you spend a while testing a binary that predates your changes.

Delete the file again once you’re done, since it renames the output of ordinary tauri build runs too.

Build the MSIX:

pnpm --filter @colibri-social/wrapper tauri:windows:build

Sideload the loose layout. This needs Developer Mode turned on, and avoids having to sign the package or trust a certificate:
Terminal window
```
powershell -c "Add-AppxPackage -Register packages/wrapper/src-tauri/target/appx/x64/AppxManifest.xml"
```
The package registers against that folder in place rather than copying into C:\Program Files\WindowsApps, so deleting target/appx/x64/ breaks the installed app rather than just removing a build artifact.

Remove it again when you’re finished:

powershell -c "Get-AppxPackage social.colibri.app | Remove-AppxPackage"

Android

Build:

pnpm --filter @colibri-social/wrapper tauri android build --apk --debug

A debug APK is fine for everyday testing and needs no signing setup. It matches what CI builds on every pull request. Only reach for a signed release build (needs packages/wrapper/src-tauri/gen/android/keystore.properties, gitignored) if you’re specifically testing the release signing or bundling path.

Emulator: boot an AVD, then install the APK you just built:

adb install -r src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk

Physical device: enable USB debugging, connect over USB, and run the same adb install -r command against it.

tauri android dev and pnpm dev:tauri:android do not work on the emulator. Dev mode needs a live connection back to a local AppView, which isn’t practical to set up there, so always build and install instead.

If DISABLE_SENTRY is set in your shell, it flows through tauri.mjs as --no-default-features and changes the Cargo feature set. Unset it for a build meant to mirror production behavior.

iOS

Build: open the generated Xcode project rather than building from the CLI alone.

pnpm --filter @colibri-social/wrapper tauri ios build --open

This opens packages/wrapper/src-tauri/gen/apple in Xcode. You can also open the project or workspace there directly if it’s already been generated.

Simulator: pick a Simulator destination in Xcode and Run. Reuse one simulator across test passes rather than creating a new one each time, and prefer reinstalling over the existing app rather than deleting it first: uninstalling wipes the app’s local session and storage.
Physical device: pick the device as the Xcode destination and Run. This needs a development signing certificate and provisioning profile. Automatic signing with an Apple ID is the simplest local setup. Once you already have a built .app, you can reinstall it without going back through Xcode:
Terminal window
```
xcrun devicectl device install app <path-to-app>
xcrun devicectl device process launch --device <device-id> <bundle-id>
```

tauri ios dev and pnpm dev:tauri:ios do not work on the Simulator, for the same reason as Android: dev mode needs a live local AppView connection.

If a Simulator build fails in a way that doesn’t match your changes, clean the gen/apple build output directory first. A stale output directory is a common cause.

Testing native builds

Desktop (macOS, Windows, Linux)

Windows

Android

iOS

See also