Copy page

SDK Library

Test Infrastructure & Configuration

Test Infrastructure & Configuration

Relevant source files

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

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

This page outlines the testing infrastructure for the @primebrick/sdk, focusing on the Vitest configuration, execution environment, and the patterns used to ensure code quality across the SDK's modules.

Vitest Configuration

The SDK utilizes Vitest as its primary testing framework, configured to provide a fast, TypeScript-native testing experience. The configuration is centralized in vitest.config.ts.

Test Environment and Discovery

The SDK is designed for backend microservices, and thus the test environment is explicitly set to node vitest.config.ts:5-5. Test discovery follows a strict pattern to separate implementation from verification: Vitest is configured to include only files matching src/**/*.test.ts vitest.config.ts:6-6.

Global Variables

Unlike some testing setups that inject describe, it, and expect into the global namespace, this SDK sets globals: false vitest.config.ts:7-7. This requires all Vitest utilities to be explicitly imported in each test file, ensuring better IDE support and preventing namespace pollution.

Configuration Implementation

The configuration is defined using the defineConfig helper from vitest/config vitest.config.ts:1-1.

Property	Value	Description
environment	"node"	Simulates the Node.js runtime environment.
include	["src/**/*.test.ts"]	Pattern for identifying test files within the source directory.
globals	false	Disables global injection of Vitest functions.

Sources:

• vitest.config.ts:1-9

---

Mocking Patterns

Testing the SDK requires isolating core logic from external dependencies such as NATS servers, databases, or the operating system's process lifecycle. The SDK relies on Vitest's mocking utilities to achieve this.

vi.mock

Used to replace entire modules. This is frequently used to mock the nats peer dependency or internal modules when testing high-level orchestrators.

vi.fn

Used to create "spy" functions that can be passed as arguments or used to satisfy interface requirements (e.g., providing a mock implementation for a Port adapter).

vi.spyOn

Used to track calls to existing object methods or to mock specific functions within a module while keeping the rest of the module's implementation intact. This is particularly useful for mocking process.exit or console methods without breaking the test runner.

Code Entity to Test Pattern Mapping

Code
graph TD
    subgraph "Natural Language Space"
        A["External Dependencies"]
        B["Port Interfaces"]
        C["Process Signals"]
    end

    subgraph "Code Entity Space"
        D["nats module"]
        E["DatabasePort"]
        F["process.exit"]
        G["vi.mock('nats')"]
        H["vi.fn()"]
        I["vi.spyOn(process, 'exit')"]
    end

    A --> D
    D -.-> G
    B --> E
    E -.-> H
    C --> F
    F -.-> I

Sources:

• vitest.config.ts:1-9
• pnpm-lock.yaml:20-22

---

Dependency Management

The testing infrastructure relies on specific development dependencies defined in the project's lockfile.

Core Test Stack

The SDK uses vitest version ^2.1.0 pnpm-lock.yaml:20-22. It also includes @types/node pnpm-lock.yaml:11-13 to provide type definitions for Node.js globals and built-in modules used during testing, such as process or fs.

Peer Dependencies in Tests

Because nats is a peer dependency pnpm-lock.yaml:14-16, the test environment includes it as a devDependency to allow for integration testing and mocking of NATS-related features within the SDK.

Sources:

• pnpm-lock.yaml:11-23

---

Diagnostic Tools & Leaked Handles

A common issue in Node.js testing is "leaked handles"—asynchronous operations (like open network connections or active timers) that prevent the test process from exiting cleanly.

why-is-node-running

While not explicitly configured in the vitest.config.ts file, the SDK's use of the node environment vitest.config.ts:5-5 and its focus on lifecycle management (e.g., NATS connections and HTTP servers) necessitates diagnostic patterns.

When tests fail to exit, developers are encouraged to use diagnostic tools to identify leaked async handles. This is critical for modules like nats and http where sockets must be explicitly closed.

Async Lifecycle Flow

Code
sequenceDiagram
    participant T as Vitest Runner
    participant S as SDK Module
    participant H as Node.js Handles

    T->>S: Execute Test
    S->>H: Open Connection/Server
    Note over S,H: Async Task Running
    T->>S: Teardown (afterEach)
    S->>H: Close/Cleanup
    alt Cleanup Successful
        H-->>T: Process Exits Cleanly
    else Leaked Handle
        Note right of H: Handle remains open
        T-->>T: Process hangs (requires SIGKILL)
    end

Sources:

• vitest.config.ts:4-8
• pnpm-lock.yaml:20-22

---