Skip to main content

Overview

The ClarkOS SDK includes a comprehensive Jest test framework with 179 tests across 7 test suites, providing full coverage of core functionality.

Test Suite

See the complete test suite on GitHub

Quick Start

Test Coverage

ModuleTestsDescription
core/tick25Routine calculation, health drift, tick execution, tick runner
core/config22Configuration validation, environment loading, Zod schemas
memory/deduplication343-tier dedup strategy, type thresholds, similarity
backend/memory22In-memory backend, state management, CRUD operations
plugins/loader26Plugin validation, dependency sorting, cycle detection
llm/embeddings32Cosine similarity, find similar, provider configurations
services/news21Service lifecycle, caching, deduplication
Total179All passing

Test Structure

Writing Tests

Basic Test Structure

Using MemoryBackend for Tests

The MemoryBackend is ideal for testing without a real Convex deployment:

Testing Plugins

Mocking External APIs

For tests that call external APIs (LLM, embeddings), mock the fetch function:

Test Configuration

The framework uses Jest with ESM support:

Running Specific Tests

Coverage Reports

After running npm run test:coverage:
  • coverage/lcov-report/index.html - HTML report (open in browser)
  • coverage/lcov.info - LCOV format for CI integration
  • Terminal output shows summary

What’s Tested

Tick System

  • Routine boundaries (6am, 12pm, 6pm, 12am)
  • Health drift calculations with mean reversion toward 75
  • Cryo mode behavior
  • Plugin hook execution
  • Error handling and recovery

Deduplication

  • All 5 memory type thresholds:
    • Episodic: 0.92
    • Semantic: 0.95
    • Emotional: 0.88
    • Procedural: 0.97
    • Reflection: 0.90
  • 3-tier strategy:
    1. Exact content match
    2. Jaccard similarity (word overlap > 0.85)
    3. Embedding similarity (type-specific)

Plugin System

  • Plugin validation rules
  • Dependency resolution (topological sort)
  • Circular dependency detection
  • Lifecycle hooks (init, cleanup, onTick)

Embeddings

  • Cosine similarity calculations
  • Provider configuration (Gemini, OpenAI, custom)
  • Batch embedding support
  • Error handling for API failures

Best Practices

Each test should be independent. Use beforeEach to reset state and afterEach for cleanup.
Focus on what the function does, not how it does it. This makes tests more resilient to refactoring.
Test names should describe the expected behavior: “returns error when agent is in cryo mode” not “test cryo”.
Mock external dependencies. Use MemoryBackend instead of real Convex connections.
Include tests for error conditions, empty inputs, and boundary values.

CI Integration

Example GitHub Actions workflow:

Next Steps

Custom Plugins

Build plugins with testable hooks.

Deployment

Deploy your tested agent.