# Test Infrastructure & Configuration

# Test Infrastructure & Configuration

<details>
<summary>Relevant source files</summary>

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

- [pnpm-lock.yaml](pnpm-lock.yaml)
- [vitest.config.ts](vitest.config.ts)

</details>



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**

```mermaid
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**

```mermaid
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]()

---