← Back to README · Русский · 简体中文
Run the Bash syntax checks and all validation scripts from a Bash-capable environment:
bash -n xrayebator
bash -n install.sh
bash -n update.sh
bash -n uninstall.sh
for test_file in validation/test-*.sh; do
bash "$test_file" || exit 1
doneA local ShellCheck pass is an additional developer check when shellcheck is installed:
shellcheck -S error xrayebator install.sh update.sh uninstall.shShellCheck is not a CI gate in the current workflows. The Linux CI gate is the four syntax checks plus the complete validation suite on Ubuntu; local ShellCheck results should not be described as a separate CI requirement.
The Bash tests use Linux-flavoured tools such as jq, uuidgen and rg. A bare Windows Git Bash
checkout may therefore be unable to run the complete suite; use the Ubuntu CI environment or a Linux
machine for authoritative results. Lifecycle checks should also verify Xray, DNS and the subscription
endpoint/service after an install or update; the runtime safe_restart_xray transaction is not a
promise that installer and updater paths behave identically.
validation/ contains exactly 49 scripts. Run every validation/test-*.sh; the current set is:
| Script | What it checks |
|---|---|
test-audit-functional.sh |
Functional P0/P1 regressions from the HowDeploy integration audit |
test-audit-privilege-regressions.sh |
Privilege boundaries, certificate ownership, rollback and HAPP setup regressions |
test-traffic-limit-cli.sh |
Per-profile traffic accounting: limit-unit normalization, delta accumulation and watermark reset, immediate ban/unban with the flow preserved, expire × traffic cross-guards, the Stats inbound migration with a port collision, the traffic fields of the profiles output, migration registration |
test-alerts-monitor.sh |
Monitoring Telegram alerts: alerts-setup/status/enable/disable/test, no config saved when the test is undelivered, the timer units and migration, service and backend detection (hysteria2, AWG), the subscription and its degradation to http_tls, the SNI probe (partial/full unreachability, recovery, interval, retry without a repeated probe), the reboot edge trigger |
test-subscription-formats.sh |
Subscription formats: normalization of vless:// (7 transports) and hysteria2://, IPv6/percent-decoding, Clash/mihomo YAML (reality-opts, flow, packet-encoding, grpc-opts, hysteria2, PyYAML validation when available), sing-box JSON through jq, PQ and xhttp skipping with a reason, edge cases (no live routes, PQ only), content negotiation in the handler heredoc, migration registration and the profiles CLI contract |
test-channel-test-cli.sh |
channel-test CLI: the link → client-config seam, free SOCKS port picking and the JSON contract (the network run itself is live-only) |
test-jq-keyword-compat.sh |
jq 1.6 compatibility: label: $label style object pairs are a syntax error on jq 1.6 (Ubuntu 22.04, Debian 12), so the route label travels as $lbl |
test-pq-routes.sh |
PQ route on any transport: a dedicated inbound with decryption, ML-KEM in the link, the ordinary route untouched, the single-route shape expanded before appending, the port union used by delete, duplicate refusal |
test-sni-reachability.sh |
Default SNI selection: an unreachable candidate is replaced by a reachable one, total unreachability keeps the previous default, one probe per SNI per run, the strict TLS 1.3 + HTTP criterion checked against real openssl output, candidate order (head of the list, then global fallbacks), and the required second attempt |
test-dns01-certbot.sh |
DNS-01 (Cloudflare/Route53): domain/provider validation (IP addresses and single-label local names rejected), certbot argument assembly per provider (plugin, credentials, propagation, deploy-hook, -m vs email-less registration), 0600 credentials content per provider, an nginx vhost without listen 80 and ACME location, CLI validation errors that write nothing to disk, and the static wiring (dispatcher, menu item, plugin packages, UFW port, domain_tls markers, the certbot manifest, uninstall cleanup) |
test-bbr-removal-migration.sh |
Safe removal of the retired BBR/TCP tuning |
test-certbot-snap-ip.sh |
Certbot for IP certificates: a single _ensure_certbot_ip_tls implementation (quickstart keeps no snap install of its own), waiting for snapd readiness (snap wait system seed.loaded), a retried install, the result verified by the binary's actual flags, snap output going to a log instead of stdout; functionally, _certbot_supports_ip_address tells certbot 5.4+ apart from the apt build and from a binary without --preferred-profile |
test-profile-revoke-expire-cli.sh |
Subscription revoke (token-only and uuid rotation, foreign clients on shared ports survive) and profile expiry (disable/enable, rebuild without a snapshot, idempotent expire-check) |
test-cascade-routing.sh |
Cascade routing configuration |
test-cascade-upstream-import.sh |
Cascade upstream import from a VLESS link |
test-dead-stealth-route-pruning.sh |
Pruning dead stealth routes |
test-fingerprint-subscription-sync.sh |
Fingerprint changes and subscription synchronisation |
test-happ-subscription-static.sh |
Static HAPP subscription handler behavior (routing placeholders, schema validation order) |
test-happ-client-routing.sh |
HAPP client split-profile: generator from bypass bundles (258 domains, placeholders, geoip:ru), nginx proxy buffers, menu wiring |
test-legacy-profile-port-sync.sh |
Legacy profiles without routes still receive SNI/port sync updates |
test-config-temp-json-suffix.sh |
Installer/update config validation: the temp config handed to xray run -test must end in .json (Xray ≥ 26.10 infers the format from the extension and ignores -format json), the failure path prints the kernel output, and mktemp --suffix=.json is verified functionally |
test-installer-network-fallbacks.sh |
Installer network and resolver fallbacks |
test-legacy-udp443-migration.sh |
One-time removal of the legacy UDP/443 block |
test-main-menu-numbering.sh |
Consecutive menu numbering and matching handlers (1..14 including the backend items and monitoring) |
test-backend-registry.sh |
Backend registry (multi-protocol stage): source-mode registry CRUD via safe_jq_write, installed/field reads, the lifecycle choke point as a safe no-op, backend-status JSON shape |
test-hysteria2-lifecycle.sh |
Hysteria 2 backend: server.yaml renderer (userpass map, placeholder fallback), systemd unit security model, arch mapping, TLS detection, grants/revocation/expire-restore events, deleted-regen with a pre-removed profile file, created-is-a-no-op (no auto-grant), pure hysteria2:// builder, CLI dispatch and subscription wiring |
test-ssh-protect.sh |
SSH brute-force protection: jail config (journald backend, 4 failures per 10 min, 30-minute ban, escalation), sshd drop-in (MaxAuthTries 3 / LoginGraceTime 30), the fact that password login stays enabled, the status-JSON shape the GUI renders, disable cleanup, wiring into menu/CLI/quickstart/install.sh and --unban validation. Also the 24-hour deploy-address exemption: ignoreip with an expiry stamp, the address parsed from SSH_CONNECTION/SSH_CLIENT, loopback skipped, pruning on expiry and the loopback baseline kept |
test-kernel-guard.sh |
Kernel hardening against CVE-2026-98432: the sysctl file that disables MPTCP, the nft rule that drops inbound IPv4 packets carrying IP options (hook input, priority -310, the exact Ubuntu rule), a boot unit that does not flush ruleset (that would wipe the UFW ruleset at boot), "a newer kernel is installed but not booted" detection without hard-coded version tables, Xray-core version comparison (leading zeros read as decimal), enable/disable against stub nft/sysctl binaries, the CLI JSON contract and the wiring into menu/dispatcher/migration/uninstall |
test-freedom-sockopt.sh |
freedom.domainStrategy → streamSettings.sockopt.domainStrategy (26.10.31 marks the old field deprecated and "will be removed"): the value moves, the legacy key is deleted, an explicit sockopt value wins, the second run is a no-op so Xray is not restarted for nothing, and the install.sh template writes only the new form |
test-awg-ppa-repo.sh |
amnezia/ppa is added only together with its signing key: the signed-by repo line, key-before-repo ordering, no repo without a key, repair of an already broken unsigned repo, idempotency by marker, and the repair wiring in main_menu/quickstart/happ-setup |
test-secret-argv.sh |
Secrets never reach a process command line (/proc/<pid>/cmdline is world-readable, /proc/<pid>/environ is not): a stub curl proves the bot token and sub_token arrive through the stdin config (-K -) and never in argv, the --secret-file/--secret-stdin payload parser (bare token, AWS pair, explicit flag wins, garbage), the 0600 refusal, the delete-after-read, the stderr warning --token now prints while stdout stays clean JSON, and jq reading $ENV.XRAYEBATOR_JQ_SECRET |
test-awg-lifecycle.sh |
AmneziaWG backend: the Amnezia-default junk dialect (Jc=5, Jmin=10, Jmax=50, H1–H4=1..4, S1–S4 unique), key generation, server conf renderer (PostUp MASQUERADE, no peers at install), peer address allocation, client .conf contents, revoke/expire/restore events, deleted-regen with a pre-removed profile file, created-is-a-no-op (no auto-grant), CLI dispatch |
test-main-readiness-regressions.sh |
Main-menu readiness and first-run regression checks |
test-multiroute-argument-preservation.sh |
Preservation of multiroute transport arguments |
test-port-change-cli.sh |
Port-change CLI scenarios, firewall moves and route selection |
test-bypass-cli.sh |
Bypass CLI JSON output and routing rule updates |
test-project-update-rollback.sh |
Rollback of a failed project update |
test-apt-lock-race.sh |
apt-lock race: DPkg::Lock::Timeout on installs, the unattended-upgrade worker check, and the 12-minute quickstart budget |
test-quickstart-email-and-inspect.sh |
Explicit quickstart email mode (--without-email without a fake address) and the read-only invariants of inspect --json |
test-quickstart-migration-parity.sh |
Parity between quickstart and main-menu migrations |
test-quickstart-subscription-port.sh |
Ensures quickstart uses the canonical subscription base helper and does not regress to an unrelated hardcoded URL |
test-quickstart-tls-fallback.sh |
The http_tls graceful-degradation branch: SUB_TLS_MODE switching, HTTP-only vhost (no ssl, no proxy), mode-aware markers, the ip_tls-only renew timer and degraded JSON metadata |
test-sni-change-cli.sh |
SNI-change JSON output, transport fields, profile sync and rollback |
test-subscription-server-name.sh |
HAPP subscription display name |
test-transaction-safety.sh |
Transactional safety of configuration operations |
test-update-branch-pinning.sh |
xrayebator update <branch> pins .current_branch so later GUI updates keep the branch |
test-update-xray-core-sync.sh |
Synchronisation between the core-update implementations |
test-vless-url-generation.sh |
VLESS link generation |
test-xhttp-route-path-repair.sh |
XHTTP route-path repair during migration |
Static tests do not replace a disposable VPS run: profile creation and deletion, config validation, service restarts, rollback, firewall behavior and a real client connection still need live-server verification.
The suite itself is not hermetic, so run it on a disposable host or in a container. Two examples found
by running it on a live server: test-ssh-protect.sh walks the real --disable path, which stops and
disables fail2ban (re-enable it afterwards), and test-hysteria2-lifecycle.sh expects a host without
a subscription Let's Encrypt certificate — with a real one present _hysteria2_tls_mode_detect
correctly answers le <domain> while the test expects selfsigned.
For a new deployment, exercise the broad quickstart --email <address> path and confirm that it
provisions the product IP-TLS endpoint on 8443, creates the profile and leaves healthy services. Its
non-interactive migration calls are best-effort, so also inspect migration markers and the resulting
profile/config. For an existing installation, exercise the reduced happ-setup path separately: remove
one or both subscription markers in a disposable environment and confirm that it refuses to fabricate
them unless the product IP-TLS endpoint/certificate on 8443 is verified. With both markers present,
confirm that setup reuses them rather than treating their presence as proof that the endpoint is still
healthy; operator verification or a rerun of the appropriate setup remains necessary.
Use Xray's run subcommand when validating the installed configuration:
sudo xrayebator probe-test # SNI reachability from the VPS
sudo /usr/local/bin/xray run -test -config /usr/local/etc/xray/config.json
sudo systemctl status xray --no-pager -l
sudo systemctl status xrayebator-sub --no-pager -l
curl -sS -i http://127.0.0.1:8080/sub/ # expected: 404
jq -r '.routes[] | [.label,.transport,.port,(.pq_enabled // false)] | @tsv' \
/usr/local/etc/xray/profiles/<profile>.json
sudo xrayebator channel-test --name <profile> # real traffic through every routechannel-test is the only check that proves a route actually carries traffic: it starts a local Xray
client from each subscription link and pushes an HTTP request through it, reporting ok, http and
latency per route, PQ routes included. Run it twice — the first run right after an Xray restart pays
connection warm-up (a live profile went from ~5.1 s to ~150 ms on the second run), so a single slow
measurement is not evidence of a broken channel.
The local subscription self-test must return 404 without a token and 200 with a valid token and
VLESS lines. Check that a newly provisioned standard HAPP profile has schema_version: 3 and seven
live routes, and that the HAPP body publishes all seven: the PQ route is no longer filtered out of it
(the base64 body for v2rayNG/v2rayN drops PQ routes instead, so it carries six). An existing profile reused by HAPP
setup may only satisfy the seven-live-route minimum, so inspect its actual labels and schema; a
migration does not retrofit missing routes. If UFW is already active, compare the numbered rules
before and after an operation: the installer adds the fixed project service TCP list and must not
change the default policy, while uninstall should remove only rules recorded as owned.
For the optional backends, a disposable VPS run should additionally cover: hysteria2-install --grant-all (service active, UDP listener present, grant in server.yaml), awg-install --grant-all (module in lsmod, awg show awg0 shows the peer), a profile-revoke cycle rotating
both grants, an expire/restore cycle, and both subscription bodies containing exactly one
hysteria2:// line per granted profile. CI covers the renderers, registry integration and dispatch
wiring with mocked binaries; the package installation itself (network, DKMS build, real systemctl)
and a real client connection are live-server checks by design.
A week of observation on a live server checks "has nothing degraded on its own" rather than "does it work now":
systemctl show <unit> -p NRestarts --value # 0 for every unit
journalctl -u xray --since "7 days ago" -p warning # empty
xrayebator inspect --json | jq '.profile_count, .route_count'
xrayebator channel-test --name <profile> # 8/8 routes, latencies of the same orderOn a live server such a week produced: no Xray warnings at all, no unit restarts caused by a failure, and
8/8 live routes with 150–250 ms latency. The only entries in the Hysteria 2 backend journal over that week
are timeout: no recent network activity when a client disconnects; there were no server-side errors.
The active Electron GUI has exactly twenty-five Vitest unit files:
| Test | What it checks |
|---|---|
tests/unit/awg-shared.test.ts |
AWG shared helpers: .conf parsing, comment stripping, vpn:// body/URL builder and the qCompress round-trip |
tests/unit/backend-manager.test.ts |
Backend status JSON and AWG conf parsing (hysteria2 + awg, 3.1 flags) |
tests/unit/calendar.test.ts |
Calendar grid helpers: local (non-UTC-shifted) ISO dates, month cells, navigation bounds |
tests/unit/countryFlag.test.ts |
Country-flag lookup used by server cards |
tests/unit/clipboard.test.ts |
Clipboard helper: a refused copy returns false instead of rejecting, so the UI never claims a silent success (all three failure modes) |
tests/unit/deployer.test.ts |
Quickstart argument building: provided/without email mode, no fake address, validation only in provided mode |
tests/unit/expire.test.ts |
Expiry badge states, server-local date rendering and the disabled-flag precedence |
tests/unit/traffic.test.ts |
Traffic limit helpers: input parsing and validation (500MB/1.5GB/2TB/none), usage and limit formatting, chip description (the 80% warn tone and the exhausted state), limit-to-input conversion |
tests/unit/extractJson.test.ts |
JSON extraction from noisy xrayebator command output |
tests/unit/probe-ports.test.ts |
Ports used by the Dashboard reachability probe |
tests/unit/server-inspector.test.ts |
Inspection normalization: public vs local-only/unreachable subscription, partial and refused-import states |
tests/unit/dns01.test.ts |
DNS-01 (Cloudflare/Route53) validation: domain rules, token and AWS key/secret shapes, cli argument assembly and readiness |
tests/unit/gui-cache-wiring.test.ts |
Wiring of the GUI caches: a server page is opened with the card re-read from the store, and the Keys page resolves expiry through the cache |
tests/unit/i18n-parity.test.ts |
Key parity of the three locales (ru/en/zh) |
tests/unit/server-keys-render.test.ts |
Server keys page SSR: the cached expiry date is present in the very first render, and a profile absent from both sources shows no line |
tests/unit/server-settings-render.test.ts |
Server settings SSR: connection gate markup, the settings section contract, and a smoke render of the separate Server profiles page |
tests/unit/server-manager.test.ts |
Safe update-branch validation |
tests/unit/server-store.test.ts |
Idempotent import upsert by host+port, credential-reference counting, the per-profile expiry cache (full-set writes, deleted profile disappears) |
tests/unit/shell-command.test.ts |
POSIX shell quoting and sudo command construction |
tests/unit/ssh-access.test.ts |
SSH credential validation, approved key access and the keychain resolution order |
tests/unit/ssh-client.test.ts |
Host-key trust, authentication and mismatch handling |
tests/unit/ssh-keychain.test.ts |
System-keychain save/load/remove of private keys with size/corruption guards (mock keytar) |
tests/unit/subscription.test.ts |
Subscription parsing, VLESS extraction and HTTP errors |
tests/unit/ui-contracts.test.ts |
Deploy readiness and payload construction for the email-mode choice |
tests/unit/vless.test.ts |
Port extraction from IPv4 and IPv6 VLESS URLs |
npm run typecheck compiles tsconfig.node.json, tsconfig.web.json and tsconfig.contracts.json —
the last project actually type-checks the strict onboarding contracts under
tests/type-contracts/ (required emailMode, keychain-reference key picker, exposed import API),
because Vitest transpilation alone would not catch a regressed type.
Run the Electron checks with:
npm run typecheck
npm test
npm run buildtests/unit/shell-command.test.ts invokes /bin/sh by design. On Windows this POSIX-specific test
can fail because /bin/sh is absent; Linux is the source of truth for it. The other unit files still
provide useful local coverage, while CI runs the Electron typecheck and unit suite on Ubuntu.
The workflows have separate responsibilities:
.github/workflows/ci-linux.ymlis the Bash core gate onubuntu-24.04: it installsjq,uuid-runtimeandripgrep, runs all four Bash syntax checks, then runs everyvalidation/test-*.shscript (49 at the time of writing)..github/workflows/release.ymlis the active Electron release path forv*tags or manual runs. Apreflightjob first checks that the release notes filedocs/releases/<tag>.en.mdexists and that theAP3X0repository secret (if set) can actually create releases — it probes with a draft release that is deleted in the same step, so surprises surface in seconds instead of after three platform builds. Both checks are warnings only: the release always gets published. Then it runsnpm run typecheckandnpm teston Ubuntu and builds/packages Windows, macOS and Linux artifacts. Thereleasejob publishes as the owner of theAP3X0token whenpreflightproved that token works, otherwise asgithub-actions[bot]via the built-inGITHUB_TOKEN: a GitHub release author is fixed at creation time and cannot be reassigned later..github/workflows/gui-release.ymlis the legacy PySide6 workflow. It runs Pythonruffandpytest gui-legacy/tests, builds legacy native bundles, and runs only a small Bash smoke subset; it is not the Electron unit-test workflow.
The Windows packaging matrix does not change the Linux source of truth for the POSIX shell test. A
Windows package can be built by the release workflow even though a local Windows run cannot execute
that /bin/sh test.