tests — server

Module: tests-server Cohesion: 0.80 Members: 0

tests — server

This document provides an overview of the tests/server module, which contains comprehensive tests for the server-side components of the application. These tests ensure the robustness, correctness, and expected behavior of the API server, its middleware, authentication mechanisms, protocol implementations, and various feature-specific routes.

The tests are written using vitest and jest and employ mocking extensively to isolate units of functionality, verify contracts between layers, and simulate various scenarios without requiring a full server stack for every test.

Module Purpose

The tests/server module serves several critical purposes:

  1. Validation of API Contracts: Ensures that API endpoints respond with the expected status codes, data formats, and error messages.
  2. Middleware Correctness: Verifies that core middleware (authentication, rate limiting, logging, error handling) functions as designed.
  3. Protocol Compliance: Confirms that internal and external communication protocols (like A2A and WebSocket) adhere to their specifications.
  4. Concurrency Management: Tests the serialization and parallelization logic for handling concurrent requests.
  5. Feature Integration: Validates the integration of various server-side features with their underlying managers and engines.

Core Server Infrastructure Tests

This section covers tests related to the fundamental building blocks of the API server.

API Server Configuration and Route Registration (api-server.test.ts)

The api-server.test.ts file focuses on verifying the foundational setup of the Express API server. It uses mocks for express and cors to inspect how the application configures itself and registers its routes, rather than making live HTTP requests.

Key Aspects Tested:

Middleware Functionality (middleware.test.ts)

The middleware.test.ts file contains tests for the various Express middleware components that process incoming requests and outgoing responses. These tests simulate the behavior of middleware in isolation.

Key Middleware Tested:

Authentication Mechanisms (auth.test.ts)

The auth.test.ts file provides detailed tests for the API key and JWT (JSON Web Token) authentication systems, leveraging Node.js's crypto module for cryptographic operations.

Key Areas Tested:

Concurrency and Request Serialization (lane-queue-server.test.ts)

The lane-queue-server.test.ts file focuses on the server-side integration of the LaneQueue concurrency mechanism. It ensures that requests are properly serialized within a "lane" (e.g., for a specific session or connection) while allowing parallel processing across different lanes.

Key Functions and Concepts Tested:

The following Mermaid diagram illustrates the core concept of the LaneQueue: 

graph TD
    A[Incoming Request] --> B{Determine Session Key};
    B -- "api:chat:sessionId" --> C1[LaneQueue: HTTP Chat];
    B -- "ws:connectionId" --> C2[LaneQueue: WebSocket];
    B -- "webhook:source:chatId" --> C3[LaneQueue: Webhook];
    C1 -- "Enqueue Task" --> D1[Task 1 (Session A)];
    C1 -- "Enqueue Task" --> D2[Task 2 (Session A)];
    C2 -- "Enqueue Task" --> E1[Task 1 (Connection X)];
    C2 -- "Enqueue Task" --> E2[Task 2 (Connection X)];
    D1 --> F{Execute Task};
    D2 -- "Waits for D1" --> F;
    E1 --> G{Execute Task};
    E2 -- "Waits for E1" --> G;
    C1 -- "Different Session" --> H[LaneQueue: HTTP Chat (Session B)];
    H -- "Enqueue Task" --> I[Task 1 (Session B)];
    I --> J{Execute Task};
    F & J --> K[Parallel Execution];

This diagram shows how requests are categorized by a Session Key and routed to dedicated LaneQueue instances. Tasks within the same lane are executed sequentially, ensuring order, while tasks in different lanes can proceed in parallel, maximizing throughput.

Protocol & Feature-Specific Tests

This section details tests for specific communication protocols and advanced server features.

Agent-to-Agent (A2A) Protocol (a2a-protocol.test.ts)

The a2a-protocol.test.ts file tests the core logic of the Agent-to-Agent (A2A) communication protocol, which enables agents to discover and interact with each other. These are unit tests for the protocol implementation itself, not directly for Express routes.

Key Components Tested:

Key Scenarios Tested:

Advanced Chat Protocol (ACP) Sessions (acp-routes.test.ts)

The acp-routes.test.ts file tests advanced session management features, likely intended for use within chat-related API routes. It mocks the a2a module to focus on the session logic itself.

Key Concepts Tested:

Native Engine API Routes (Native Engine-routes.test.ts)

The Native Engine-routes.test.ts file is a critical integration test suite for various "Native Engine" API routes. It replicates the exact handler logic from src/server/index.ts but injects mock manager objects (e.g., mockHeartbeatEngine, mockSkillsHub) to verify the contract between the HTTP layer and the underlying business logic modules without a full server startup.

Key Route Groups and Managers Tested:

WebSocket Handler (websocket.test.ts)

The websocket.test.ts file tests the functionality of the WebSocket server, covering connection lifecycle, message parsing, authentication, and various message types for real-time interaction.

Key Areas Tested:

Workflow Builder & API (workflow-builder.test.ts)

The workflow-builder.test.ts file tests the server-side components related to the workflow builder, including its API routes and underlying data stores. It spins up a minimal Express server to make actual HTTP requests, providing a more integrated test environment for these routes.

Key Components and APIs Tested:

Key Scenarios Tested:

This comprehensive test suite ensures that the server-side components are well-tested, maintainable, and behave as expected across various functionalities and integration points.