Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• PLAN.md
• README.md
• package.json
• CHANGELOG.md
• packages/shared/src/index.ts

KamehaDB employs a multi-tiered testing strategy designed to ensure the reliability of its local-first database management capabilities across multiple database engines, including PostgreSQL, MySQL, SQLite, MongoDB, and Redis. The strategy spans unit testing of shared logic, integration testing with live database containers, and end-to-end (E2E) verification of the Tauri-based desktop application.

The testing framework is integrated into the project's monorepo structure, utilizing a shared set of tools and scripts to maintain high code quality and prevent regressions in core features such as SQL safety guards, schema browsing, and AI-assisted query generation.

Sources: AGENTS.md:12-25, PLAN.md:10-25, README.md:15-30

Testing Architecture and Methodology

The project utilizes a structured testing hierarchy that moves from isolated logic to full system integration. This approach ensures that core utilities in packages/shared are validated before being utilized by the apps/sidecar (backend) and apps/desktop (frontend).

Testing Tiers

Tier	Scope	Primary Tools	Key Focus Areas
Unit Tests	Isolated functions and classes	Vitest	Zod schemas, SQL safety guards, state reducers, result normalization
Integration Tests	Component interactions	Testcontainers	Database adapters, schema listing, query execution, connection health
UI/E2E Tests	Full user workflows	Playwright	Connection creation, table browsing, SQL editor usage, AI chat interactions
Static Analysis	Code structure and types	TypeScript, ESLint	Type safety across package boundaries, linting rules

Sources: PLAN.md:210-235, package.json:20-30, CHANGELOG.md:160-175

Data Flow for Test Verification

The following diagram illustrates the flow of a test execution, particularly for integration tests involving the database adapters.

This flow ensures that data retrieved from various database engines conforms to the shared contracts defined in the project.
Sources: PLAN.md:210-220, AGENTS.md:130-145

Core Testing Components

Shared Logic and Safety Guards

A critical component of the testing strategy is the validation of the isQuerySafe utility and Zod schemas located in packages/shared. Tests verify that destructive SQL keywords are correctly identified and blocked when the application is in read-only mode.

// Example of logic under test in packages/shared/src/index.ts
export const DESTRUCTIVE_KEYWORDS = ['DROP', 'TRUNCATE', 'ALTER', 'CREATE', 'INSERT', 'UPDATE', 'DELETE', 'MERGE', 'GRANT', 'REVOKE'];

export function isQuerySafe(sql: string): { safe: boolean; reason?: string } {
  // Logic to block keywords like DROP or DELETE in read-only mode
}

Sources: packages/shared/src/index.ts:544-578

Database Integration Testing

Integration tests rely on docker-compose.yml to spin up local instances of PostgreSQL, MySQL, MariaDB, and Redis. These tests verify the SqlAdapter, RedisAdapter, and MongoAdapter contracts.

Automation and CI/CD Integration

Testing is enforced through Git hooks and GitHub Actions. The project uses husky to run linting and formatting checks before commits, and the CI pipeline executes the full suite of tests on every push.

Execution Commands

Command	Action
pnpm test	Runs unit tests across all workspace packages
pnpm typecheck	Validates TypeScript types across the monorepo
pnpm lint	Executes linting checks
pnpm --filter @kamehadb/desktop test	Runs targeted Vitest tests for the desktop package

Sources: package.json:7-16, AGENTS.md:40-65

CI/CD Workflow

The GitHub Actions workflow (defined in .github/workflows/release.yml) performs the following sequence to ensure build stability:

1. Lint & Format: Ensures code adheres to Prettier and ESLint rules.
2. Typecheck: Verifies cross-package type consistency (e.g., between sidecar and desktop).
3. Unit & Integration Tests: Runs the test suite via pnpm test.
4. Build Verification: Performs tauri build for various platforms (macOS, Windows, Linux) to ensure the application packages correctly.

Sources: AGENTS.md:135-150, README.md:65-85

Conclusion

The KamehaDB testing strategy prioritizes the integrity of the local-first architecture by rigorously validating shared types and safety logic. By combining static analysis, unit tests, and containerized integration tests, the project ensures that database operations remain safe and predictable across its diverse range of supported database engines.