Testing Strategies & CI Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Testing strategies in HX-ProxyGroup focus on maintaining a strict boundary between the control plane and the data plane while ensuring contract consistency across different integration points. The project utilizes a "Testing Pyramid" approach, combining unit tests for domain logic, integration tests for boundaries like SQLite and Mihomo, and end-to-end (E2E) tests for core user journeys.
Contract verification scripts act as enforcement gates for the public and administrative APIs, preventing documentation drift and ensuring that external agents and internal renders remain synchronized.
The Testing Pyramid
The project structures its quality assurance into three distinct layers to ensure reliability without sacrificing development speed.
1. Unit Testing
Unit tests target pure domain logic within the control plane. Key focus areas include node fingerprinting, rule pipelines, metrics aggregation, and configuration compilation stability.
Sources: AGENTS.md:121-125
2. Integration Testing
Integration tests verify interactions with external boundaries. This includes SQLite migrations, Mihomo configuration application/rollback, and HTTP/SSE API behaviors.
Sources: AGENTS.md:127-130
3. End-to-End (E2E) Testing
E2E tests validate the complete user lifecycle, from adding a subscription to viewing traffic statistics.
Sources: AGENTS.md:132-137
The diagram shows the hierarchical relationship and scope of the different testing layers.
Sources: AGENTS.md:121-137
Contract Verification Gates
HX-ProxyGroup uses specialized TypeScript scripts to ensure that API definitions, documentation, and external AI skills stay in sync.
Consumer Contract Verification
The verify-consumer-contract.ts script ensures that the frozen vocabulary for public consumer integrations is consistent across three locations:
- The human-readable documentation (
docs/CONSUMER_INTEGRATION_CONTRACT.md). - The server-side Go implementation (
internal/listener/consumer.go). - The AI agent skills (
.agents/skills/hx-consumer-api/SKILL.md).
It checks the endpoint constants, field vocabularies (protocols, transports, formats), and HTTP status codes.
Sources: scripts/verify-consumer-contract.ts:3-17
Admin Catalog Verification
The verify-admin-catalog.ts script gates the management API's capability catalog. It prevents drift between the published Go constants, the admin agent skills, and the scripts used by agents. It specifically checks that:
- The skill does not name endpoints the catalog does not publish.
- The agent script does not hard-code paths (it must read them from the catalog).
- Product boundaries (e.g., residential-only chaining) are clearly stated.
Sources: scripts/verify-admin-catalog.ts:3-19
This diagram illustrates the verification flow for the administrative API catalog.
Sources: scripts/verify-admin-catalog.ts:46-135
Automated System and API Tests
The project includes extensive Go tests to verify system configuration, security, and API behavior.
Configuration and Security Validation
Tests in internal/config/config_test.go and install_test.go ensure that the system remains secure by default:
- Listen Address Gating: Rejects public or ambiguous addresses (e.g.,
0.0.0.0) to keep the management API private. - Systemd Sandboxing: Verifies that systemd units use
NoNewPrivileges,ProtectSystem=strict, andProtectHome=true. - Terminal Isolation: Ensures the privileged terminal helper uses a Unix socket and is root-only.
Sources: internal/config/config_test.go:12-45, install_test.go:21-65
API and Lifecycle Testing
Tests in internal/api/ and internal/subscription/ verify runtime behaviors:
- Two-Factor Authentication (2FA): Verification that system updates and terminal access require 2FA-verified sessions.
- Subscription Rollbacks: Ensuring that if a new subscription refresh fails, the previous valid node snapshot is preserved.
- Deduplication: Verifying that nodes are deduplicated and orphaned nodes are correctly retired.
Sources: internal/api/system_static_test.go:103-125, internal/subscription/parsed_refresh_test.go:42-95, internal/subscription/parsed_refresh_test.go:167-200
Release Package Verification
The scripts/package-release.sh and install_test.go handle the creation and verification of release bundles.
| Verification Step | Description | Source File |
|---|---|---|
| Syntax Check | Validates the bash syntax of install.sh. | install_test.go:16-21 |
| Path Safety | Ensures release bundles do not contain unsafe paths (e.g., ..). | install.sh:137-142 |
| Checksum Integrity | Matches bundle SHA256 against SHA256SUMS. | install.sh:144-152 |
| Reproducibility | Verifies that two identical package runs produce identical binaries. | install_test.go:117-150 |
Critical CI Enforcement Commands
| Command | Purpose |
|---|---|
go test ./... | Runs all unit and integration tests. |
node scripts/verify-consumer-contract.ts | Enforces consistency for public consumer APIs. |
node scripts/verify-admin-catalog.ts | Enforces consistency for the admin management catalog. |
bash install.sh install --offline-dir <dir> | Tests the installation and upgrade paths. |
Conclusion
The testing strategy of HX-ProxyGroup is designed to prevent architectural erosion and contract drift. By combining traditional Go testing for internal logic with TypeScript-based contract gates, the project ensures that its control plane remains stable and secure, while its public interfaces remain consistent for both human developers and AI agents.