Local native capture and packaging

Debug a native story locally before sending a build to hosted capture.

Local prerequisites#

Install the native uploader described in native CI. Local capture requires the appropriate development tools: Xcode and an installed simulator on macOS for iOS, or Android SDK tools and a suitable emulator for Android.

These local commands do not use Framecheck's hosted API. Your local runtime can render differently from the hosted device, so a local result is not a replacement for the project's CI check.

Capture an Android app#

node framecheck-native.mjs capture --platform android \
  --app ./app-framecheck.apk --app-id com.example.storybook \
  --serial emulator-5554 --out ./framecheck-local

Use your emulator's serial. If you want the CLI to select or start an AVD, use the supported --avd NAME option instead. The app still needs the native capture entry and bundled stories.

Capture an iOS app#

node framecheck-native.mjs capture --platform ios \
  --app ./YourApp.app --udid "$SIMULATOR_UDID" \
  --out ./framecheck-local

Supply the identifier of the simulator you intend to use. Its app must be a compatible simulator build.

Filter and compare#

--only REGEX limits capture to matching stories. --baseline DIR compares with a directory of reference captures. --color-scheme light or dark selects one appearance, and --light-and-dark requests both. Local capture exits nonzero if it finishes with errors or differences.

Keep output directories out of version control unless your team deliberately manages local screenshot references there.

Attach to an existing development app#

Instead of --app, use --open-url URL --app-id ID when the app is already installed and the URL loads your capture-mode bundle. This can support a development client during local debugging. Hosted capture still needs the standalone bundled app; it cannot connect to your laptop's Metro server.

Package without uploading#

node framecheck-native.mjs pack --platform ios \
  --app ./YourApp.app --out ./framecheck-ios.tgz

Use --platform android and an APK for Android. Packaging validates the app format and architecture. --app-id supplies an explicit identifier if it cannot be read from the build. Do not assume the upload --app option accepts an arbitrary archive: the documented hosted upload input is the app/APK and it packages that input for you.