# Testing

# Testing

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



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](#3.1).

---

## Test Architecture

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

### Test Isolation Diagram
```mermaid
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
```mermaid
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](#3.2).

---

## Child Pages

*   **[Test Infrastructure & Configuration](#3.1)**: Detailed Vitest setup, file discovery, and diagnostic tooling for leaked handles.
*   **[Module Test Patterns](#3.2)**: Implementation details for mock adapters, singleton resets, and HTTP integration testing.

---