# Testing Strategies in holaOS: A Complete Guide to Monorepo Testing

> Discover holaOS testing strategies, including unit integration and E2E tests, orchestrated by Turbo within its monorepo. Learn how to ensure robust code quality.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.test.ts) — validates workspace registry, metadata separation, and schema migrations
- [`runtime/state-store/src/migrations.test.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/migrations.test.ts) — ensures database schema changes execute correctly
- [`runtime/harnesses/src/pi.test.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/pi.test.ts) — verifies the core "π" harness workflow
- [`runtime/harness-host/src/tool-schema-validation.test.ts`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) defines the orchestration layer:

```bash

# 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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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.