Testing Strategies in holaOS: A Complete Guide to Monorepo Testing

holaOS employs a layered testing strategy combining unit tests, integration tests, and full-stack E2E tests orchestrated by Turbo across its monorepo architecture.

The holaOS codebase uses a sophisticated, multi-layered approach to testing strategies that covers everything from low-level database operations to full Electron desktop simulations. This open-source monorepo maintained by holaboss-ai validates its core runtime, harnesses, channel-gateway, API server, and desktop application through carefully structured test suites. Understanding these testing strategies is essential for contributors working across the TypeScript-based codebase.

Unit and Integration Testing with node:test

The foundation of holaOS testing strategies rests on unit and integration tests written with Node.js's built-in node:test framework. These tests run in isolated processes and validate individual modules alongside their interactions.

Key test files demonstrate this approach:

• runtime/state-store/src/store.test.ts — validates workspace registry, metadata separation, and schema migrations
• runtime/state-store/src/migrations.test.ts — ensures database schema changes execute correctly
• runtime/harnesses/src/pi.test.ts — verifies the core "π" harness workflow
• runtime/harness-host/src/tool-schema-validation.test.ts — confirms tool contracts are properly validated

These suites use SQLite with better-sqlite3 and sqlite-vec for persistence testing, providing fast, deterministic feedback without external dependencies.

End-to-End Testing for Desktop Applications

holaOS runs E2E tests that simulate real-world desktop usage by launching complete runtime stacks and exercising UI-to-runtime communication. These tests spin up isolated Electron instances and drive them through public APIs.

Critical E2E test files include:

apps/desktop/electron/workspace-runtime-session-routing.test.mjs
apps/desktop/electron/workspace-browser-storage-cleanup.test.mjs

The session routing test specifically confirms that workspace sessions route correctly across the desktop UI, while the storage cleanup test verifies browser storage hygiene between sessions.

Isolated Runtime and Script Testing

Beyond integrated tests, holaOS maintains isolated runtime tests that verify runtime behavior without the desktop frontend. These scripts spawn sandboxed runtime processes to test:

• Launch sequences
• Deployment pipelines
• Runtime-only code paths

Representative files:

• scripts/isolated-runtime-launchers.test.mjs
• scripts/deploy/build_runtime_root.test.mjs

Script and utility tests cover helper tools separately. The scripts/lib/memory-live-utils.test.mjs suite validates utilities for live memory inspection and diagnostic operations.

Monorepo Test Orchestration with Turbo

All testing strategies in holaOS converge through Turbo for parallel execution across workspaces. The top-level package.json defines the orchestration layer:

# Run the entire test matrix across all packages

npm run test

# Filter to specific workspace tests

npm run test --filter=@holaboss/runtime-state-store

# Execute desktop E2E suite only

npm run test --filter=holaboss-local

Under the hood, npm run test invokes bun run test → turbo run test, leveraging Bun as the package manager while using the standard node:test API with test(...), afterEach, and other lifecycle hooks.

Component-Specific Testing Patterns

State Store Validation

The state store tests in runtime/state-store/src/store.test.ts demonstrate comprehensive coverage of workspace registry operations, metadata separation concerns, and migration correctness. This pattern applies to all persistence-critical modules.

Channel-Gateway Messaging

In runtime/channel-gateway/src/gateway.test.ts, tests verify message routing logic and format adapter behavior—essential for the inter-process communication layer that connects desktop UI to runtime services.

API Server Planning

The runtime/api-server/src/workspace-runtime-plan.test.ts validates the planning endpoint, ensuring that workspace runtime configuration generates correctly before execution.

Summary

• Unit and integration tests use node:test with SQLite-backed persistence for fast, isolated validation
• E2E tests launch full Electron instances to verify complete user workflows
• Isolated runtime tests check launch sequences and deployment scripts without UI dependencies
• Turbo orchestration enables parallel execution across the monorepo via npm run test
• Bun runtime powers the test execution while maintaining compatibility with standard Node.js test APIs

Frequently Asked Questions

What test framework does holaOS use?

holaOS uses Node.js's built-in node:test framework for all test suites, running under the Bun runtime. This provides native TypeScript-compatible testing without external dependencies like Jest or Vitest. The test() and afterEach lifecycle hooks match standard Node.js patterns.

How do I run tests for a specific holaOS package?

Use Turbo's filter flag: npm run test --filter=@holaboss/runtime-state-store for the state store, or npm run test --filter=holaboss-local for desktop E2E tests. The --filter argument accepts workspace names as defined in the monorepo's package.json files.

Are tests in holaOS run in parallel?

Yes. The turbo run test command executes test suites across workspaces in parallel, respecting dependency graphs. Individual test files within a workspace run sequentially by default, though node:test supports parallel test execution via configuration.

What database is used for testing the state store?

Tests use SQLite with better-sqlite3 as the driver and sqlite-vec for vector operations. This provides fast, in-process persistence without requiring external database services, making tests deterministic and CI-friendly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}