Protocol Compliance Testing
Relevant source files
The following files were used as context for generating this wiki page:
Protocol Compliance Testing validates that the OneBots gateway adheres to the communication specifications defined by OneBot, Satori, and Milky protocols. The test suite ensures that authentication, heartbeat mechanisms, and API signatures match official documentation requirements across multiple communication methods.
This module provides a rigorous framework for regression testing when modifying protocol implementations. It covers HTTP, forward and reverse WebSocket, and Webhook (HTTP Reverse) interactions.
Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:1-7, tests/README.md:1-8
Testing Architecture and Structure
The testing framework uses Vitest to execute integration and end-to-end tests. The repository organizes tests by protocol name and version, maintaining separate utilities for HTTP and WebSocket clients.
Testing Directory Layout
The diagram above illustrates the hierarchical organization of test files by protocol and transport layer.
Sources: tests/README.md:21-65, AGENTS.md:104-106
Core Testing Components
| Component | Description |
|---|---|
| MockBot | A simulated adapter used for unit tests to trigger events without a real IM platform. |
| Test Server | A local server used to validate WebHook (HTTP Reverse) and Reverse WebSocket connections. |
| HTTP/WS Clients | Specialized utilities for sending signed requests and monitoring event streams. |
Sources: tests/README.md:23-26, AGENTS.md:113-115
Authentication Compliance Standards
The system enforces specific authentication logic for each protocol. Authentication must occur before protocol upgrades (for WebSocket) or as part of the request header/query for HTTP.
Protocol Authentication Requirements
| Protocol | Authentication Method | Required Headers / Params |
|---|---|---|
| OneBot 11 | Bearer Token or Query | Authorization: Bearer <token> or ?access_token=<token> |
| OneBot 12 | Header (Priority) or Query | Authorization (checked first), then access_token query |
| Milky V1 | Bearer Token or Query | Authorization: Bearer <token>; defaults to 401 on failure |
| Satori V1 | Bearer Token | Authorization: Bearer <token> |
Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:19-23, tests/PROTOCOL_AUTH_HEARTBEAT.md:46-50, tests/CHECKLIST_AUTH_HEARTBEAT.md:38-40
OneBot 12 Webhook Headers
OneBot 12 requires mandatory headers for Webhook compliance. The test suite validates these strictly:
Content-Type: Must beapplication/json.X-OneBot-Version: Must be12.X-Impl: Identifies the implementation (e.g.,onebots).User-Agent: Suggested formatOneBot/12 (<impl>) <software>.
Sources: tests/onebot/v12/webhook/headers.spec.js:10-15, tests/onebot/v12/webhook/headers.spec.js:203-207
Heartbeat and Meta-Event Validation
Heartbeat events ensure connection stability. Compliance testing verifies the specific structure and field types of these events.
Heartbeat Event Structures
OneBot 11 requires a status object, whereas OneBot 12 only requires the interval field.
Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:31-35, tests/PROTOCOL_AUTH_HEARTBEAT.md:65-68, tests/CHECKLIST_AUTH_HEARTBEAT.md:27-28
Connection Flow Testing
Connection testing validates the lifecycle of both forward and reverse connections. Forward testing connects to the OneBots gateway, while reverse testing requires a mock server to receive connections from the gateway.
WebSocket Connection Sequence
Reverse Connection Port Defaults
Compliance testing uses standard ports for local verification:
- WebHook (V11):
18080 - WS-Reverse (V11):
18081 - WS-Reverse (V12):
18082
Sources: tests/README.md:144-148
Testing Procedures
You must follow these steps to execute compliance verification:
- Environment Setup: Ensure Node.js >= 24 and pnpm >= 10.34.5 are installed.
- Gateway Activation: Start the gateway service using
pnpm dev. - Configuration: Define the
PLATFORMandACCOUNT_IDenvironment variables. - Execution: Run specific protocol tests using
pnpm test -- --run <protocol_path>. - Validation: Check the "Unsupported API Summary" collected at the end of the test run to identify implementation gaps.
Sources: CONTRIBUTING.md:43-48, tests/README.md:92-97, tests/README.md:180-185
Summary
Protocol Compliance Testing provides the final verification layer for the OneBots project. It ensures that the normalized CommonEvent format is correctly translated into protocol-specific报文 (messages) and that security measures like access_token validation are strictly implemented according to the OneBot 11/12, Satori, and Milky standards. Compliance is maintained through a combination of automated Vitest suites and manual checklists.
Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:78-85, AGENTS.md:15-20