expo-sqlite-mock

library4.0.0jsnpmunverified

A Jest mock for expo-sqlite that allows testing SQLite-dependent code without a device or emulator. Current stable version is 4.0.0, compatible with expo-sqlite (expo-sqlite >=55) and expo >=55. It replaces expo-sqlite's native calls with better-sqlite3, enabling real SQLite database operations in test environments. Supports custom database file paths via the EXPO_SQLITE_MOCK environment variable for concurrent test isolation. Differentiates from simple mocks by executing actual SQL, catching constraint errors, and integrating with ORMs like drizzle. Release cadence is tied to expo-sqlite major versions, with breaking changes on major version bumps.

testing database

npm install expo-sqlite-mock

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPO-SQLITE-MOCK

expo-sqlite-mock

testingjavascriptv4.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

setup file

✓ jest config: setupFilesAfterEnv: ['expo-sqlite-mock/src/setup.ts']

✗ no setup file or incorrect path like 'expo-sqlite-mock'

The mock is activated by including the setup file in Jest configuration, not by importing a module directly in test files.

process.env.EXPO_SQLITE_MOCK

✓ process.env.EXPO_SQLITE_MOCK = 'path/to/test.db';

✗ import { EXPO_SQLITE_MOCK } from 'expo-sqlite-mock'

The custom database path is set via environment variable, not imported. Useful for per-test database files.

mock/clear/reset

✓ jest.clearAllMocks() or delete process.env.EXPO_SQLITE_MOCK

✗ import { resetMock } from 'expo-sqlite-mock'

There is no explicit reset function; to isolate tests, set or delete the environment variable as needed.

Shows installation, jest configuration, and a basic test using expo-sqlite API with custom database per test worker.

// Install: npm install -D expo-sqlite-mock // In jest config (package.json or jest.config): "setupFilesAfterEnv": ["expo-sqlite-mock/src/setup.ts"], "testTimeout": 10000 // Test file example: import * as SQLite from 'expo-sqlite'; it('should insert and read data', async () => { process.env.EXPO_SQLITE_MOCK = `${__dirname}/test_${process.env.JEST_WORKER_ID}.db`; const db = await SQLite.openDatabaseAsync('test.db'); await db.execAsync(`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)`); await db.runAsync('INSERT INTO users (name) VALUES (?)', 'Alice'); const result = await db.getAllAsync('SELECT * FROM users'); expect(result).toEqual([{ id: 1, name: 'Alice' }]); delete process.env.EXPO_SQLITE_MOCK; });

Debug

Known issues

breakingv4.0.0 drops support for expo-sqlite versions below 55 (expo >=55). If you are on expo <55, stick to v3.x.

fix

Downgrade to expo-sqlite-mock@3 if using expo 53-54; or upgrade expo to >=55.

affects: >=4.0.0

breakingv3.0.0 requires expo-sqlite ~15 and expo ~53. Existing tests may break if using older expo versions.

fix

If on expo 51-52, use v2.x instead.

affects: >=3.0.0 <4.0.0

breakingv2.0.0 updates for expo-sqlite ~52, breaking compatibility with expo-sqlite ~51.

fix

Use v1.x for expo-sqlite ~51.

affects: >=2.0.0 <3.0.0

gotchaConcurrent test files writing to the same custom database file can cause data races and flaky tests.

fix

Use console.JEST_WORKER_ID in the database path to isolate per-worker databases (e.g., ${__dirname}/test_${process.env.JEST_WORKER_ID}.db).

affects: >=2.1.0

gotchaThe mock does not simulate all native SQLite features (e.g., FTS, WAL mode); behavior may differ from real devices/emulators.

fix

For critical native-specific tests, supplement with integration tests on actual devices.

affects: all

Errors

Common errors & fixes

Cannot find module 'expo-sqlite-mock'

Package not installed or incorrect path in jest config.

fix

npm install -D expo-sqlite-mock and ensure setupFilesAfterEnv includes 'expo-sqlite-mock/src/setup.ts'.

TypeError: expo_sqlite.openDatabaseAsync is not a function

The setup file may not be loaded; mock is not applied.

fix

Add 'expo-sqlite-mock/src/setup.ts' to setupFilesAfterEnv and restart Jest.

Error: SQLITE_ERROR: no such table: users

Table creation SQL not executed or test order issue.

fix

Ensure CREATE TABLE is called before any queries, e.g., using db.execAsync in beforeAll.

Error: UNIQUE constraint failed: users.id

Db file from previous test persists, causing duplicates.

fix

Use a fresh database per test or delete the file: delete process.env.EXPO_SQLITE_MOCK or set a unique path with process.env.JEST_WORKER_ID.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

better-sqlite3requiredProvides the real SQLite engine used by the mock for actual query execution in tests.

exporequiredPeer dependency; the mock expects expo runtime and configuration to be available.

expo-sqliterequiredPeer dependency; the mock replaces expo-sqlite's native module with better-sqlite3.

jestrequiredPeer dependency; the mock relies on Jest's global setup and test environment.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/zfben/expo-sqlite-mock ↗

packageexpo-sqlite-mock ↗

homepagehttps://github.com/zfben/expo-sqlite-mock ↗