Copy page

SDK Library

Testing

Testing

Relevant source files

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

• pnpm-lock.yaml
• vitest.config.ts

The PrimeBrick SDK utilizes a testing strategy focused on reliability and isolation, ensuring that core modules function correctly without requiring live infrastructure. The strategy leverages the hexagonal architecture of the SDK by using in-memory mock adapters for ports and rigorous unit testing for business logic.

Test Strategy and Tooling

The SDK uses Vitest as its primary test runner. The configuration is optimized for a Node.js environment, targeting specific file patterns to separate implementation from verification.

Test Environment

The testing suite is configured in vitest.config.ts with the following parameters:

• Environment: node vitest.config.ts:5-5.
• Discovery: Files matching src/**/*.test.ts are automatically included vitest.config.ts:6-6.
• Globals: Disabled to encourage explicit imports of test utilities (vi, describe, it, expect) vitest.config.ts:7-7.

Mocking Patterns

The SDK relies heavily on Vitest's mocking capabilities to isolate modules:

• vi.mock: Used to intercept external dependencies like nats or Node.js built-ins.
• vi.fn / vi.spyOn: Used to verify interactions with port adapters and lifecycle signal handlers.
• Leak Detection: The suite is designed to be compatible with diagnostics like why-is-node-running to ensure async handles (like HTTP servers or NATS connections) are properly closed.

For details, see Test Infrastructure & Configuration.

---

Test Architecture

The following diagram illustrates how the test suite interacts with the SDK components, substituting real infrastructure with mock implementations.

Test Isolation Diagram

Code
graph TD
    subgraph "Test Space"
        TEST["Vitest Runner"]
        MOCK_ADAPTER["Mock Port Adapters"]
    end

    subgraph "Code Entity Space (SDK)"
        direction TB
        MODULE["Core Module (e.g., ConfigLoader)"]
        PORT["Port Interface (e.g., ConfigRepositoryPort)"]
    end

    TEST -->|"Executes"| MODULE
    MODULE -->|"Calls"| PORT
    PORT -.->|"Implemented by"| MOCK_ADAPTER
    MOCK_ADAPTER -->|"Returns Stubbed Data"| MODULE
    TEST -->|"Asserts State"| MOCK_ADAPTER

Sources: vitest.config.ts:1-9.

---

Module-Specific Patterns

Testing varies by module to address specific side effects and infrastructure requirements:

Module	Test Pattern	Key Entities
Config	In-memory repository mocks	makeRepo (Mock ConfigRepositoryPort)
Migrations	Temp directory fixtures	applyPatches, fs.mkdtemp
NATS	Singleton reset & vi.mock	NatsClient.close(), nats.connect
Lifecycle	Signal simulation & process mocking	GracefulShutdown, process.exit
HTTP	Ephemeral port binding	createHttpServer, HealthCheck

Infrastructure to Code Mapping

The following diagram bridges the natural language concepts of "Infrastructure" with the specific code entities used during testing.

Entity Mapping Diagram

Code
graph LR
    subgraph "Natural Language Space"
        DB["Database Port"]
        MSG["Messaging Client"]
        PROC["Process Lifecycle"]
        FS["File System"]
    end

    subgraph "Code Entity Space"
        DB_PORT["DatabasePort"]
        NATS_CLIENT["NatsClient"]
        SHUTDOWN["GracefulShutdown"]
        PATCH_REG["applyPatches"]
    end

    subgraph "Test Entity Space"
        MOCK_DB["makeDb (Mock)"]
        VI_NATS["vi.mock('nats')"]
        MOCK_EXIT["vi.spyOn(process, 'exit')"]
        TEMP_DIR["tmpdir() Fixture"]
    end

    DB --- DB_PORT --- MOCK_DB
    MSG --- NATS_CLIENT --- VI_NATS
    PROC --- SHUTDOWN --- MOCK_EXIT
    FS --- PATCH_REG --- TEMP_DIR

Sources: vitest.config.ts:4-8, pnpm-lock.yaml:14-16, pnpm-lock.yaml:20-22.

For details on specific module implementations, see Module Test Patterns.

---

Child Pages

• Test Infrastructure & Configuration: Detailed Vitest setup, file discovery, and diagnostic tooling for leaked handles.
• Module Test Patterns: Implementation details for mock adapters, singleton resets, and HTTP integration testing.

---