菜单
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).