test: add Jest config, unit tests, and CI workflow

.github/workflows/test.yml

@@ -0,0 +1,45 @@
+name: Test
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '.github/workflows/test.yml'
+      - 'src/**'
+      - 'package.json'
+      - 'yarn.lock'
+      - 'tsconfig*.json'
+      - 'jest.config.js'
+      - 'jest.setup.ts'
+  pull_request:
+    paths:
+      - '.github/workflows/test.yml'
+      - 'src/**'
+      - 'package.json'
+      - 'yarn.lock'
+      - 'tsconfig*.json'
+      - 'jest.config.js'
+      - 'jest.setup.ts'
+  workflow_dispatch:
+
+jobs:
+  unit-tests:
+    name: Run unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run Jest with coverage
+        run: yarn test:coverage

.gitignore

@@ -75,4 +75,8 @@ android/keystores/debug.keystore
 # generated by bob
 lib/
 tsconfig.tsbuildinfo
-nitrogen/
+nitrogen/
+
+
+# Testing
+coverage/

README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/react-native-sensitive-info)](https://www.npmjs.com/package/react-native-sensitive-info)
 [![npm downloads](https://img.shields.io/npm/dm/react-native-sensitive-info)](https://www.npmjs.com/package/react-native-sensitive-info)
+[![Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen)](https://github.com/mcodex/react-native-sensitive-info)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 Modern secure storage for React Native, powered by Nitro Modules. Version 6 ships a new headless API surface, stronger security defaults, and a fully revamped example app.
@@ -53,6 +54,7 @@ Modern secure storage for React Native, powered by Nitro Modules. Version 6 ship
 
 | Platform | Minimum OS | Notes |
 | --- | --- | --- |
+| React Native | 0.76.0 | Requires `react-native-nitro-modules` for Nitro hybrid core. |
 | iOS | 13.0 | Requires Face ID usage string when biometrics are enabled. |
 | Android | API 23 (Marshmallow) | StrongBox detection requires API 28+; biometrics fall back to device credential when unavailable. |
 | Windows | ❌ | Removed in v6. Earlier versions may still work but are no longer maintained. |

jest.config.js

@@ -0,0 +1,35 @@
+/** @type {import('jest').Config} */
+const config = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/tsconfig.test.json',
+        isolatedModules: false,
+      },
+    ],
+  },
+  moduleNameMapper: {
+    '^react-native$': '<rootDir>/src/__tests__/__mocks__/react-native.ts',
+  },
+  collectCoverage: true,
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/__tests__/**',
+    '!src/**/*.nitro.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      statements: 95,
+      branches: 90,
+      functions: 90,
+      lines: 95,
+    },
+  },
+  testMatch: ['<rootDir>/src/**/?(*.)+(spec|test).ts?(x)'],
+}
+
+module.exports = config

package.json

@@ -12,7 +12,9 @@
     "clean": "git clean -dfX",
     "release": "semantic-release",
     "build": "npm run typecheck && bob build",
-    "codegen": "nitrogen --logLevel=\"debug\" && npm run build && node post-script.js"
+    "codegen": "nitrogen --logLevel=\"debug\" && npm run build && node post-script.js",
+    "test": "jest",
+    "test:coverage": "jest --coverage"
   },
   "keywords": [
     "react-native",
@@ -57,7 +59,9 @@
     "@jamesacarr/eslint-formatter-github-actions": "^0.2.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@types/jest": "^30.0.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.0.0",
+    "@types/jest": "^29.5.12",
     "@types/react": "19.2.x",
     "babel-plugin-react-compiler": "^1.0.0",
     "conventional-changelog-conventionalcommits": "^9.1.0",
@@ -72,14 +76,19 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
     "globals": "^16.4.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "jiti": "^2.6.1",
     "nitrogen": "0.31.2",
     "prettier": "^3.6.2",
     "react": "19.1.1",
+    "react-dom": "19.1.1",
     "react-native": "0.82",
     "react-native-builder-bob": "^0.40.13",
     "react-native-nitro-modules": "0.31.2",
     "semantic-release": "^25.0.1",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.2"
   },

src/__tests__/__mocks__/react-native-nitro-modules.ts

@@ -0,0 +1,23 @@
+export class MockHybridObject {
+  static instances: MockHybridObject[] = []
+
+  constructor() {
+    MockHybridObject.instances.push(this)
+  }
+}
+
+export const getHybridObjectConstructor = jest
+  .fn(() => MockHybridObject)
+  .mockName('getHybridObjectConstructor')
+
+export const __resetMocks = () => {
+  MockHybridObject.instances = []
+  getHybridObjectConstructor.mockReset()
+  getHybridObjectConstructor.mockReturnValue(MockHybridObject)
+}
+
+__resetMocks()
+
+export default {
+  getHybridObjectConstructor,
+}

src/__tests__/__mocks__/react-native.ts

@@ -0,0 +1,5 @@
+export const NativeModules = {}
+
+export default {
+  NativeModules,
+}

src/__tests__/core.storage.test.ts

@@ -0,0 +1,206 @@
+import type {
+  SensitiveInfoDeleteRequest,
+  SensitiveInfoEnumerateRequest,
+  SensitiveInfoGetRequest,
+  SensitiveInfoHasRequest,
+  SensitiveInfoOptions,
+  SensitiveInfoSetRequest,
+} from '../sensitive-info.nitro'
+
+describe('core/storage', () => {
+  const nativeHandle = {
+    setItem: jest.fn(),
+    getItem: jest.fn(),
+    hasItem: jest.fn(),
+    deleteItem: jest.fn(),
+    getAllItems: jest.fn(),
+    clearService: jest.fn(),
+    getSupportedSecurityLevels: jest.fn(),
+  }
+
+  const normalizeOptions = jest
+    .fn<
+      ReturnType<typeof import('../internal/options').normalizeOptions>,
+      [SensitiveInfoOptions | undefined]
+    >()
+    .mockReturnValue({
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    })
+
+  const isNotFoundError = jest.fn()
+
+  const loadModule = async () => {
+    jest.resetModules()
+
+    jest.doMock('../internal/native', () => ({
+      __esModule: true,
+      default: jest.fn(() => nativeHandle),
+    }))
+
+    jest.doMock('../internal/options', () => ({
+      normalizeOptions,
+    }))
+
+    jest.doMock('../internal/errors', () => ({
+      isNotFoundError,
+    }))
+
+    return import('../core/storage')
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    Object.values(nativeHandle).forEach((value) => {
+      if (typeof value === 'function') {
+        value.mockReset()
+      }
+    })
+    normalizeOptions.mockClear()
+    normalizeOptions.mockReturnValue({
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    })
+    isNotFoundError.mockReset()
+  })
+
+  it('delegates setItem to the native layer', async () => {
+    const { setItem } = await loadModule()
+
+    nativeHandle.setItem.mockResolvedValue({ metadata: {} })
+
+    await setItem('token', 'secret', { service: 'service' })
+
+    expect(normalizeOptions).toHaveBeenCalledWith({ service: 'service' })
+    expect(nativeHandle.setItem).toHaveBeenCalledWith({
+      key: 'token',
+      value: 'secret',
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    } as SensitiveInfoSetRequest)
+  })
+
+  it('returns null when a key is missing', async () => {
+    const { getItem } = await loadModule()
+
+    const error = new Error('Missing [E_NOT_FOUND] key')
+    nativeHandle.getItem.mockRejectedValueOnce(error)
+    isNotFoundError.mockReturnValueOnce(true)
+
+    const result = await getItem('token', { service: 'service' })
+
+    expect(result).toBeNull()
+    expect(normalizeOptions).toHaveBeenCalled()
+  })
+
+  it('rethrows unexpected errors during getItem', async () => {
+    const { getItem } = await loadModule()
+
+    const error = new Error('Boom')
+    nativeHandle.getItem.mockRejectedValueOnce(error)
+    isNotFoundError.mockReturnValueOnce(false)
+
+    await expect(getItem('token')).rejects.toBe(error)
+  })
+
+  it('passes includeValue defaults to getItem', async () => {
+    const { getItem } = await loadModule()
+
+    nativeHandle.getItem.mockResolvedValueOnce({ key: 'token' })
+
+    await getItem('token')
+
+    expect(nativeHandle.getItem).toHaveBeenCalledWith({
+      key: 'token',
+      includeValue: true,
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    } as SensitiveInfoGetRequest)
+  })
+
+  it('delegates hasItem to the native layer', async () => {
+    const { hasItem } = await loadModule()
+
+    nativeHandle.hasItem.mockResolvedValueOnce(true)
+
+    const result = await hasItem('token', { service: 'service' })
+
+    expect(result).toBe(true)
+    expect(nativeHandle.hasItem).toHaveBeenCalledWith({
+      key: 'token',
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    } as SensitiveInfoHasRequest)
+  })
+
+  it('delegates deleteItem to the native layer', async () => {
+    const { deleteItem } = await loadModule()
+
+    nativeHandle.deleteItem.mockResolvedValueOnce(true)
+
+    const result = await deleteItem('token', { service: 'service' })
+
+    expect(result).toBe(true)
+    expect(nativeHandle.deleteItem).toHaveBeenCalledWith({
+      key: 'token',
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    } as SensitiveInfoDeleteRequest)
+  })
+
+  it('returns entries using getAllItems with includeValues default', async () => {
+    const { getAllItems } = await loadModule()
+
+    nativeHandle.getAllItems.mockResolvedValueOnce([])
+
+    await getAllItems({ includeValues: true })
+
+    expect(nativeHandle.getAllItems).toHaveBeenCalledWith({
+      includeValues: true,
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    } as SensitiveInfoEnumerateRequest)
+  })
+
+  it('clears a service via native call', async () => {
+    const { clearService } = await loadModule()
+
+    nativeHandle.clearService.mockResolvedValueOnce(undefined)
+
+    await clearService({ service: 'auth' })
+
+    expect(nativeHandle.clearService).toHaveBeenCalledWith({
+      service: 'normalized',
+      accessControl: 'secureEnclaveBiometry',
+    })
+  })
+
+  it('forwards getSupportedSecurityLevels', async () => {
+    const { getSupportedSecurityLevels } = await loadModule()
+
+    nativeHandle.getSupportedSecurityLevels.mockResolvedValueOnce({
+      secureEnclave: true,
+      strongBox: true,
+      biometry: true,
+      deviceCredential: false,
+    })
+
+    const result = await getSupportedSecurityLevels()
+
+    expect(result).toEqual({
+      secureEnclave: true,
+      strongBox: true,
+      biometry: true,
+      deviceCredential: false,
+    })
+    expect(nativeHandle.getSupportedSecurityLevels).toHaveBeenCalled()
+  })
+
+  it('exposes a namespace mirroring the helpers', async () => {
+    const module = await loadModule()
+
+    expect(module.SensitiveInfo.setItem).toBe(module.setItem)
+    expect(module.SensitiveInfo.getItem).toBe(module.getItem)
+    expect(module.SensitiveInfo.clearService).toBe(module.clearService)
+  })
+})