القائمة
Runtime verification recipe for biometric_vault - build, launch, and drive the plugin end to end on the iOS simulator with controllable biometry state.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when adding the biometric_vault Flutter package to an app or wiring a feature on top of it - storing tokens, passwords, or keys behind Face ID / Touch ID / fingerprint / device-credential authentication, building an app-lock gate, choosing StorageFileInitOptions, or setting the package up for Android, iOS, macOS, Linux, Windows, or web. Not for debugging an existing integration that fails at runtime (use troubleshoot-biometric-vault) and not for converting an app from the biometric_storage package (use migrate-from-biometric-storage).
Use when a Flutter app that currently uses the biometric_storage package (by authpass / Herbert Poul) should switch to biometric_vault - replacing the dependency, converting BiometricStorage/BiometricStorageFile/IosPromptInfo code, or when stored secrets from biometric_storage must survive the switch. Also applies when biometric_vault reads return null after such a switch. Not for fresh integrations without biometric_storage history (use integrate-biometric-vault).
Use when writing or fixing Dart/Flutter tests for app code that uses the biometric_vault package - unit or widget tests that must run without a device or emulator, tests simulating authentication failures (user cancellation, lockout, storage invalidation), or tests failing with MissingPluginException on the biometric_vault channel. Not for testing the plugin's own native implementations.
Use when an app using the biometric_vault Flutter package misbehaves at runtime - AuthException codes such as failedToStart or lockedOut, StorageInvalidatedException after users change biometric enrollment, SecurityError -34018 on macOS, reads returning null unexpectedly, prompts not appearing or appearing twice, silent-writes stores where writes succeed while reads keep failing, or biometric flows that behave differently on the iOS simulator than on real devices. Not for first-time package setup (use integrate-biometric-vault) and not for converting an app from biometric_storage (use migrate-from-biometric-storage).
| name | verify |
| description | Runtime verification recipe for biometric_vault - build, launch, and drive the plugin end to end on the iOS simulator with controllable biometry state. |
The plugin is a library; its surface is the package boundary exercised by the example app running on a device or simulator.
cd example
flutter run -d <SIM_UDID> 2>&1 | tee /tmp/e2e_run.log # VM service URI + app logs
Pick a simulator UDID from xcrun simctl list devices | grep iPhone.
The example app has no automation package. The proven approach: temporarily
add an auto-run sequence in MyAppState.initState (postFrameCallback calling
the plugin APIs and logging results), run it, read the flutter: log lines,
then REVERT the patch. The StorageActions buttons have stable ValueKeys
(<storeName>.read / .write / .delete) if a tap driver is available.
simctl ui <udid> biometry does NOT exist in current Xcode. Use BiometricKit
notifications instead:
xcrun simctl spawn <UDID> notifyutil -s com.apple.BiometricKit.enrollmentChanged 1 # enroll
xcrun simctl spawn <UDID> notifyutil -p com.apple.BiometricKit.enrollmentChanged
# 0 instead of 1 to unenroll; relaunch the app afterwards.
kSecAttrAccessControl: reads and
writes on authentication-required stores succeed without any Face ID sheet,
even when unenrolled. Prompt, lockout, and errSecAuthFailed paths can only
be observed on real hardware; they are pinned by the RunnerTests suite
(fake keychain + fake LAContext).canAuthenticate DOES reflect enrollment state on the simulator, so the
capability mapping is verifiable live (success vs errorNoBiometricEnrolled).cd example/ios && xcodebuild test -workspace Runner.xcworkspace -scheme Runner -destination 'platform=iOS Simulator,name=iPhone 17' -only-testing:RunnerTests
cd example/macos && xcodebuild test -workspace Runner.xcworkspace -scheme Runner -only-testing:RunnerTests
# Android (system JDK 26 breaks gradle; use the Android Studio JBR):
JAVA_HOME="/Users/omarhanafy/Applications/Android Studio.app/Contents/jbr/Contents/Home" \
sh -c 'cd example/android && ./gradlew :biometric_vault:testDebugUnitTest'
If xcodebuild fails with Module 'biometric_vault' not found, regenerate
the SPM integration first: cd example && flutter build ios --config-only
(and flutter build macos --config-only).