‹ /jest

Types

Types of /jest

The types of the mock’s controls: the simulated device, a prompt it showed, an item of an old library to plant, and what is left of one after a migration.

Import

import { type KeychainMock, type MockDevice, type MockPrompt } from '@apexnative/keychain/jest';

@apexnative/keychain/jest also exports every type of the package, the same as @apexnative/keychain does; they are on the pages of their sections. These are the types of the mock's own controls, keychainMock.

KeychainMock

The type of keychainMock.

type KeychainMock = {
  reset(): void;
  setDevice(device: Partial<MockDevice>): void;
  failNextAuthentication(code: KeychainErrorCode): void;
  changeBiometry(): void;
  prompts(): MockPrompt[];
  addMigrationSource(item: MockMigrationItem): void;
  migrationSources(): MockMigrationSource[];
};

Method	Type	Description
reset	() => void	Forgets every item, prompt, queued failure and planted old item, and restores the default device. More
setDevice	(device) => void	Changes the fields of the device it is given; the others stay. More
failNextAuthentication	(code) => void	The next prompt fails with the code. Calls queue up; KEY_INVALIDATED also deletes the item. More
changeBiometry	() => void	A new finger or face: biometryCurrentSet* items throw KEY_INVALIDATED at their next read. More
prompts	() => MockPrompt[]	The prompts shown since the last reset, oldest first. More
addMigrationSource	(item) => void	Plants an item of react-native-keychain or expo-secure-store for migrate. More
migrationSources	() => MockMigrationSource[]	The planted items that are still there. More

MockDevice

The device the mock simulates. setDevice takes any part of it.

type MockDevice = {
  defaultService: string;
  biometryTypes: BiometryType[];
  biometryEnrolled: boolean;
  passcodeSet: boolean;
  faceIDUsageDescription: boolean;
  androidApi: number | null;
  hardwareSecurityLevel: HardwareSecurityLevel | null;
};

Field	Type	Description
defaultService	string	The service of the default store, keychain: the bundle identifier or the application id of a real app. A react-native-keychain generic password planted under it is the one migrateFromReactNativeKeychain moves by default. Default 'dev.apexnative.keychain.mock'.
biometryTypes	BiometryType[]	The biometric hardware: what getBiometryTypes returns. [] is a device without a sensor, where the biometric access controls are noHardware. Default ['faceID'].
biometryEnrolled	boolean	Whether biometry is enrolled. Without it getBiometryState() is null, and biometryAny, biometryCurrentSet and biometryCurrentSetOrPasscode are notEnrolled. Default true.
passcodeSet	boolean	Whether the device has a passcode: what isPasscodeSet returns. Without it every access control is passcodeNotSet, and whenPasscodeSetThisDeviceOnly can't be written. Default true.
faceIDUsageDescription	boolean	iOS: whether the app has NSFaceIDUsageDescription in its Info.plist. Without it, on a device with faceID, a biometric write and canUseAccessControl for a biometric access control reject with MISSING_USAGE_DESCRIPTION. Default true.
androidApi	number | null	Android: the API level. null is a device that isn't an Android one. Below 30 the passcode variants are unsupportedOS, and a write with one, or with authValidity above 0, rejects with UNSUPPORTED. Default null.
hardwareSecurityLevel	HardwareSecurityLevel | null	Android: the best hardware a new key can live in, what getHardwareSecurityLevel returns. null is iOS, where keyStorage means nothing. With a level, getItemInfo reports android.securityLevel: tee stays in the TEE even with StrongBox, strongbox falls back to the TEE, and strongboxRequired rejects with HARDWARE_UNAVAILABLE unless the level is strongbox. Default null.

MockPrompt

A prompt the mock showed, as prompts() returns it.

type MockPrompt = {
  key: string;
  title?: string;
  subtitle?: string;
  description?: string;
  cancel?: string;
  fallback?: string;
  confirmationRequired: boolean;
};

Field	Type	Description
key	string	The key of the item the prompt was for. For an old item that migrateItem read: the user name of react-native-keychain, the key of expo-secure-store.
title, subtitle, description, cancel, fallback	string	The texts of the prompt: the store's `prompt` and the call's, merged field by field. A text neither of them set is missing.
confirmationRequired	boolean	Always there: the call's, the store's, or true.

MockMigrationItem

An item of an old library, as that library left it on the device: what addMigrationSource plants. One of three shapes, with three optional fields shared by all of them.

type MockMigrationItem = {
  requiresAuth?: boolean;
  corrupted?: boolean;
  accessGroup?: string;
} & (
  | {
      // A generic password of react-native-keychain.
      library: 'reactNativeKeychain';
      service: string;
      username: string;
      password: string;
    }
  | {
      // Internet credentials of react-native-keychain.
      library: 'reactNativeKeychain';
      server: string;
      username: string;
      password: string;
    }
  | {
      // An item of expo-secure-store.
      library: 'expoSecureStore';
      key: string;
      value: string;
      keychainService?: string;
    }
);

Field	Type	Description
libraryRequired	'reactNativeKeychain' | 'expoSecureStore'	The library that wrote it.
service	string	react-native-keychain, a generic password: its service. It becomes the credentials of the store of that service.
server	string	react-native-keychain, internet credentials: the server. They become the credentials with that server.
username, password	string	react-native-keychain: the credentials.
key, value	string	expo-secure-store: the key and the value. The item keeps its key.
keychainService	string	expo-secure-store: the keychainService the item was stored with. Default 'app'.
requiresAuth	boolean	The old item is protected: migrateFrom… skips it as requiresAuth, and migrateItem reads it with a prompt. Default false.
corrupted	boolean	Reading it fails with DATA_CORRUPTED, as bytes that aren't text do. Default false.
accessGroup	string	iOS: the access group the old item is in. A migration that names an accessGroup finds only the items of that group.

MockMigrationSource

A planted item that is still there, as migrationSources() returns it.

type MockMigrationSource = {
  library: 'reactNativeKeychain' | 'expoSecureStore';
  kind: 'genericPassword' | 'internetPassword' | 'secureStore';
  service: string;
  account: string;
  requiresAuth: boolean;
  migrated: boolean;
};

Field	Type	Description
library	'reactNativeKeychain' | 'expoSecureStore'	The library that wrote it.
kind	'genericPassword' | 'internetPassword' | 'secureStore'	What it becomes in the package: the kinds of a migration report.
service	string	The service or the server; for expo-secure-store, the keychainService.
account	string	The user name; for expo-secure-store, the key.
requiresAuth	boolean	Whether reading it needs a prompt.
migrated	boolean	A run moved it and kept it: a run without removeSource. A later run with removeSource deletes it, if the new item is still there.

See also

keychainMockThe controls these types describe./jestThe mock module and what it simulates.TestingThe guide.