Testing

How the plugin's own cross-platform behavioral suite is organized and run — useful if you're contributing to the plugin, debugging a platform-specific discrepancy, or benchmarking the plugin inside your own app. Full detail, including the complete regression-coverage policy and release-gating procedure, lives in TESTING.md in the repository.

Overview

Scope	Coverage	Purpose
Automated	401 tests · 75 groups · 12 stress benchmarks · 24 diagnostics	Cross-platform behavioral, compatibility, and performance-regression coverage
Manual	11 scenarios	OS lifecycle, storage-failure, profiler, and native-environment checks outside JS reach

The tests live in the example app (playground/): build and launch it on a target platform, open the Test Suite tab, and press Run All. Throughput/latency benchmarks run separately from the Load Tests tab.

The same test definitions (playground/src/tests/suiteTests.ts, stressBenchmarks.ts, and diagnosticBenchmarks.ts) are shared with CLI runners, so the full suite can run outside the playground UI too — the playground UI and the CLI runners call the exact same test code against a real platform backend, not a copy.

Running from the command line

Command	Platform	How it connects
`npm run test:suite:electron`	Electron (`node:sqlite`)	Runs `ElectronSqliteBackend` in plain Node — no Electron process needed
`npm run test:suite:web`	Web (sqlite-wasm/OPFS)	Starts the playground Vite dev server with COOP/COEP headers, launches Chrome/Chromium with a temporary profile, drives the page over Chrome DevTools Protocol
`npm run test:suite:android`	Android (Kotlin/SQLite)	Builds, installs, and launches the playground on the current emulator/device, then drives its WebView over CDP via `adb forward`
`npm run test:suite:ios`	iOS (Swift/SQLite)	Builds, installs, and launches the playground on the currently booted Simulator, drives its WKWebView over the WebKit Remote Web Inspector protocol (via `appium-remote-debugger`)

Append :stress to also run the stress benchmarks after the suite, or :stress-only to run only the benchmark profile through the same non-UI driver:

npm run test:suite:web:stress
npm run test:suite:android:stress-only

Each command exits non-zero on any test failure, so they're usable as CI gates. Set ANDROID_SERIAL when multiple Android targets are connected.

Performance layer diagnostics

A shorter, 24-case diagnostic profile isolates latency by layer (JS harness cost, platform dispatch, transactional vs. autocommit writes, batch/runMany() wrapping, etc.):

npm run test:suite:web:diagnostics
npm run test:suite:android:diagnostics
npm run test:suite:ios:diagnostics
npm run test:suite:electron:diagnostics

Lightweight regression gate

For a fast local check without building the playground:

npm run test:p2

Runs the JS SQL guard tests, iOS XCTest, Android unit tests, Web/Electron builds, and migration validation tests.

Manual testing

11 scenarios cannot be covered by the JS test layer because they require OS-level timing, filesystem manipulation, or native profiling: close-during-operation races, app lifecycle (background/foreground, activity recreation, iOS suspend/resume), storage failures (disk full, locked file), a deliberately corrupted database, connection/memory leak measurement, Web/WASM persistence edge cases (IndexedDB deletion, private mode), Electron IPC security, iOS backup exclusion, encryption (unsupported — out of scope by design), transaction state across app suspend/resume, and hot-reload/live-reload edge cases. See TESTING.md for the full scenario table.

CI

CI (.github/workflows/ci.yml) runs on every PR and push to main: TypeScript lint/build, the Electron and Web/OPFS suites, Android unit tests + build, and iOS XCTest on a booted simulator.
Release Matrix (.github/workflows/release-matrix.yml) is manually triggered before a release. It runs Electron, Web/OPFS, Android, and iOS as separate jobs, optionally including stress benchmarks, and uploads platform logs as workflow artifacts.

Contributing covers local setup and the pull-request checklist that references these commands.