Testing Strategy & CI/CD

Relevant source files

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

• CONTRIBUTING.md
• AGENTS.md
• tests/README.md
• tests/PROTOCOL_AUTH_HEARTBEAT.md
• tests/CHECKLIST_AUTH_HEARTBEAT.md
• packages/core/src/tests/integration.test.ts
• packages/core/src/app-observability.ts
• packages/onebots/src/installation/generation-verify.spec.ts

The OneBots testing strategy ensures stability across multiple IM platforms and communication protocols. It uses a tiered approach ranging from unit tests to full protocol integration tests, integrated into a GitHub Actions CI/CD pipeline. The system validates core logic, platform adapters, and external protocol compliance (OneBot, Satori, Milky).

Sources: AGENTS.md:129-130, CONTRIBUTING.md:280-282

Testing Architecture & Environment

OneBots utilizes Vitest (v1.6.x) as its primary testing framework. The environment requires Node.js >= 24 and pnpm >= 10.34.5. Tests run in a Node environment with a 30s timeout and global APIs enabled.

Sources: AGENTS.md:130-132, CONTRIBUTING.md:280-285

Test Types

The project categorizes tests into four levels to maintain modularity and reliability:

1. Unit Tests: Validate individual functions and classes within packages/*/src/ and adapters/*/src/. These tests use @onebots/adapter-mock to simulate bot behavior without connecting to real services.
2. Integration Tests: Located in packages/core/src/__tests__/, these verify interactions between core modules like the Lifecycle Manager, Config Validator, and DI Container.
3. Protocol Tests: Located in __tests__/, these ensure compliance with OneBot v11/v12, Milky, and Satori standards using actual network communication.
4. Verification Tests: Specialized tests in packages/onebots/src/installation/ that validate immutable runtime generations and plugin isolation.

Sources: AGENTS.md:133-145, packages/core/src/tests/integration.test.ts:1-5, packages/onebots/src/installation/generation-verify.spec.ts:104-106

Testing Flow Diagram

This diagram illustrates the progression from isolated unit tests using mocks to complex protocol-level testing.

Sources: CONTRIBUTING.md:285-300, AGENTS.md:144-146

Protocol & Integration Testing

Protocol tests verify that the gateway correctly implements communication standards. These tests cover HTTP APIs, Forward/Reverse WebSockets, Server-Sent Events (SSE), and Webhooks.

Supported Protocols Coverage

Protocol	API Count	Coverage	Key Test Areas
OneBot V11	36	100%	HTTP, WS, Webhook, WS-Reverse
OneBot V12	23	100%	HTTP, WS, WS-Reverse, Headers
Milky V1	59	100%	HTTP, WS, SSE, Webhook
Satori V1	21	100%	HTTP, WS

Sources: tests/README.md:145-165

Authentication & Heartbeat Validation

Tests for authentication and heartbeats strictly follow official protocol specifications. Heartbeat tests verify the interval (typically in milliseconds) and status fields in meta-events.

• OneBot 11: Validates access_token in Headers or Query, and checks X-Signature for Webhooks.
• OneBot 12: Requires checking Authorization header before URL Query.
• Milky: Validates 401 Unauthorized, 415 Unsupported Media Type, and 404 Not Found responses.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:15-60, tests/CHECKLIST_AUTH_HEARTBEAT.md:15-45

Reverse WebSocket Sequence

The reverse WebSocket test verifies the gateway's ability to initiate connections and handle inbound API calls from a remote server.

Sources: tests/README.md:92-115

Observability & CI Health Probes

The system provides observability endpoints used by CI and deployment probes to verify application readiness.

Endpoint	Purpose	Metrics/Data Provided
/health	Liveness check	Uptime, instance ID, version info
/ready	Readiness check	Adapter status, account status, config sync status
/metrics	Prometheus metrics	Memory, connection counts, protocol readiness

Sources: packages/core/src/app-observability.ts:175-230

Readiness Logic

A gateway is considered ready only if:

• isStarted is true.
• isReloading is false.
• config.in_sync is true.
• All configured accounts are online and their protocols are ready.

Sources: packages/core/src/app-observability.ts:100-145

CI/CD Pipeline

The project uses GitHub Actions for automated verification and delivery.

CI Gating Requirements

Every PR must pass the following gates:

• Build: pnpm build must succeed across the monorepo.
• Linting: No ESLint or Prettier violations.
• Testing: All Vitest suites must pass (pnpm test).
• Packaging Check: pnpm packages:pack:check validates npm tarball boundaries.
• Coverage: Must meet specific thresholds.

Sources: CONTRIBUTING.md:345-360, AGENTS.md:85-95

Coverage Thresholds

Metric	Minimum Threshold
Lines	50%
Functions	50%
Statements	50%
Branches	40%

Sources: CONTRIBUTING.md:287-289, AGENTS.md:148-150

Release Workflow

The release process follows a specific sequence triggered by pushes to the master branch:

1. Installation: pnpm install --frozen-lockfile.
2. Testing: Full execution of all test suites.
3. Version PR: If changesets are present, a Version PR is created.
4. Publishing: Upon merging, packages are published to NPM via OIDC (trusted publishing) and Docker images are pushed to ghcr.io/lc-cn/onebots.

Sources: CONTRIBUTING.md:365-375, AGENTS.md:195-205

Execution Commands

Target	Command
Run all tests	pnpm test
Watch mode	pnpm test:watch
Coverage report	pnpm test:coverage
UI Dashboard	pnpm test:ui
Run specific protocol	pnpm test -- --run onebot/v11

Sources: CONTRIBUTING.md:380-400, AGENTS.md:100-105

OneBots employs a strict testing strategy grounded in protocol compliance and process isolation. By combining unit-level mocking with comprehensive protocol integration tests and observability probes, the CI/CD pipeline ensures that changes across the 20+ adapters and multiple protocols do not introduce regressions.