Automated Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr implements a multi-layered automated testing strategy to ensure the security, correctness, and performance of its Mihomo GUI client. The strategy spans the Rust backend (core logic and Tauri integration) and the JavaScript frontend (UI components and IPC contracts). All major new functionality must include automated tests to verify behavior and prevent regressions.
The testing suite comprises unit tests, integration tests, Golden snapshot tests, and continuous verification through a CI/CD pipeline. These layers address different risks, from low-level data sanitization to high-level cross-module IPC contracts.
Sources: CONTRIBUTING.md:73-75, SECURITY.md:167-172
Testing Architecture
The project divides testing responsibilities between the Rust backend and the JavaScript frontend. Rust tests focus on business logic and security-critical functions, while JavaScript tests verify UI state and the communication bridge between the two environments.
The diagram shows the parallel testing tracks for backend and frontend that converge in the CI pipeline for final verification.
Sources: CONTRIBUTING.md:81-99, apps/desktop/src/integration.test.js:10-15
Backend Testing (Rust)
Backend testing focuses on the zephyr-core logic and the Tauri IPC layer. It utilizes standard Rust testing attributes and the insta crate for snapshot verification.
Unit and Logic Testing
Unit tests are typically located inline within source files using #[cfg(test)] mod tests. These tests verify pure utility functions, such as filename sanitization, extension normalization, and rule format detection.
Key functions tested include:
sanitize_filename: Ensures filenames are safe for the filesystem and lack path traversal sequences.detect_source: Identifies if a rule file follows Clash, Surge, or unknown formats.normalize_to_prism_yaml: Converts various rule formats into the project's native Prism DSL.
Sources: apps/desktop/src-tauri/src/prism_tests.rs:1-20, crates/core/src/config/prism_types.rs:205-255
Golden Snapshot Tests
Zephyr uses "Golden" snapshot tests via the insta crate. These tests capture the output of complex operations (like input/output contracts for mask_url or parse_version) and compare them against stored .snap files. This ensures that changes to logic do not silently alter expected data structures.
Sources: CONTRIBUTING.md:86-88, crates/core/src/config/prism_types.rs:258-270
Integration and Security Testing
Integration tests in prism_tests.rs simulate file CRUD operations using temporary directories. These tests verify that the system correctly handles groups.json management and rule file extraction while maintaining security boundaries.
Sources: apps/desktop/src-tauri/src/prism_tests.rs:400-450, SECURITY.md:167-172
Frontend Testing (JavaScript)
The frontend uses Vitest with the happy-dom environment to execute unit and contract tests.
IPC Contract Verification
A critical part of the strategy is the "Contract Integration" test suite. These tests ensure that the frontend and backend remain synchronized without manual checking.
| Contract Type | Verification Logic |
|---|---|
| Backend -> Frontend | Every #[tauri::command] in Rust must have a matching entry in shared/index.js COMMANDS. |
| UI -> COMMANDS | Every COMMANDS.XXX reference in UI code must resolve to a defined string value. |
| I18n Translation | Every translation key used via t('key') must exist in all supported language dictionaries. |
| Event Bridge | Every event name emitted by Rust (e.g., deep-link, prism-event) must have a frontend listener. |
Sources: apps/desktop/src/integration.test.js:10-40, apps/desktop/src/integration.test.js:335-375
The sequence diagram illustrates how the integration.test.js suite prevents runtime failures by verifying the string mapping between layers.
Sources: apps/desktop/src/integration.test.js:35-50
UI Component and Polish Testing
Frontend tests also cover UI-specific logic, such as:
- TUN Status Labels: Verifying that localized labels are correctly applied based on the active state.
- Speed Units: Ensuring that KB/s or MB/s units are not incorrectly transformed (e.g., uppercased) by CSS.
- Sidebar Tooltips: Testing the hover intent delay, visibility logic, and RTL layout support for tooltips.
Sources: apps/desktop/src/ui/ui-polish.test.js:30-60, apps/desktop/src/ui/ui-polish.test.js:125-150
Continuous Integration (CI)
The CI pipeline provides automated verification for every Pull Request and push to the main branch. It enforces code quality and security standards through the following checks:
- Rust Lints: Runs
cargo clippywith 170 deny rules, covering correctness, security, concurrency, and performance. - Rust Tests: Executes all unit, integration, and Golden snapshot tests across the workspace.
- Frontend Lints: Runs ESLint with custom security rules (e.g.,
no-unsanitizedfor innerHTML). - Frontend Tests: Executes Vitest suites.
- Security Audits: Includes dependency audits via
cargo-denyand SAST scans.
Sources: CONTRIBUTING.md:40-65, CONTRIBUTING.md:100-110, SECURITY.md:167-172
Summary
The Automated Testing Strategy in Zephyr ensures that security boundaries are maintained and that the complex communication between the Rust backend and JavaScript frontend is resilient. By combining low-level unit tests with high-level IPC contract verification and automated CI enforcement, the project maintains high technical standards for a proxy client environment.