testing

name	testing
description	Use when: running or writing libatbus unit tests, filtering private test cases, testing topology/shared-memory behavior, or fixing Windows DLL/PATH startup issues.

Unit testing (libatbus)

This repo uses a private unit testing framework (not GoogleTest).

Run tests

The test executable is atbus_unit_test.

Common commands:

• Run all tests: ./atbus_unit_test
• List tests: ./atbus_unit_test -l / ./atbus_unit_test --list-tests
• Run a group/case: ./atbus_unit_test -r <group> or ./atbus_unit_test -r <group>.<case>
• Filter: ./atbus_unit_test -f "pattern*" / ./atbus_unit_test --filter "pattern*"
• Help/version: ./atbus_unit_test -h, ./atbus_unit_test -v

Windows: DLL lookup via PATH

On Windows, atbus_unit_test.exe (and samples) may fail to start if dependent DLLs cannot be found.

Preferred approach: prepend DLL directories to PATH for the current run/debug session.

Typical DLL directories in the monorepo/toolset layout:

• <BUILD_DIR>\\publish\\bin\\<Config>
• <REPO_ROOT>\\third_party\\install\\windows-amd64-msvc-19\\bin

Example (PowerShell):

• $buildDir = "<BUILD_DIR>"
• $cfg = "Debug"
• $env:PATH = "$buildDir\\publish\\bin\\$cfg;$buildDir\\publish\\bin;${PWD}\\third_party\\install\\windows-amd64-msvc-19\\bin;" + $env:PATH
• Set-Location "$buildDir\\_deps\\atbus\\test\\$cfg"
• ./atbus_unit_test.exe -l

Test groups and cases

Node messaging (atbus_node_msg) — 24 tests

Core message delivery, crypto configuration, and multi-hop routing:

• ping_pong — Heartbeat exchange with timing validation
• custom_cmd / custom_cmd_by_temp_node / send_cmd_to_self — Custom command round-trip
• reset_and_send — Direct self-send via callback
• upstream_and_downstream — Tree topology message delivery
• transfer_and_connect / transfer_only — Proxy forwarding
• send_failed / transfer_failed / transfer_failed_cross_upstreams — Error handling
• send_msg_to_self_and_need_rsp — Response flag (REQUIRE_RSP) and response callback
• topology_registry_multi_level_route / ..._reverse — Multi-hop routing through 3-level hierarchy
• msg_handler_get_body_name — Body type name resolution
• crypto_config_key_exchange_algorithms — Tests X25519, SECP256R1, SECP384R1
• crypto_config_cipher_algorithms — Tests AES-128/192/256 CBC/GCM, XXTEA, ChaCha20
• crypto_config_comprehensive_matrix — All crypto combination matrix
• crypto_config_multiple_algorithms — Multiple algorithms at once
• crypto_config_upstream_downstream — Crypto across topology
• crypto_config_disabled — Plaintext operation
• crypto_list_available_algorithms — Algorithm enumeration

Node registration (atbus_node_reg) — 22 tests

Registration flow, timeout, access tokens, channel types:

• reset_and_send_tcp — Basic TCP registration handshake
• timeout — Registration timeout and recovery
• message_size_limit — Large message handling
• reg_pc_success / reg_pc_success_cross_subnet / reg_pc_failed_with_subnet_mismatch — Point-to-point registration
• reg_bro_success — Broadcast discovery
• reg_failed_with_mismatch_access_token / reg_failed_with_missing_access_token — Token validation
• conflict / destruct / reconnect_upstream_failed — Lifecycle edge cases
• on_close_connection_normal / on_close_connection_by_peer — Connection close callbacks
• mem_and_send / shm_and_send — Memory/shared memory channel tests
• on_topology_upstream_set / on_topology_upstream_clear / on_topology_upstream_change_id — Topology events
• set_hostname — Hostname configuration

Connection context (atbus_connection_context) — 37 tests

Encryption/compression handshake, pack/unpack, all algorithm combinations:

• padding_* (9 tests) — Buffer allocation alignment and overhead validation
• create_* (4 tests) — Context creation with various key exchange types
• get_* / is_* (3 tests) — Property getters and algorithm support checks
• update_compression_algorithm_* (2 tests) — Compression config updates
• handshake_* (7 tests) — Key generation, public key exchange, complete flow
• pack_unpack_* (5 tests) — Message round-trip with/without encryption/compression
• all_*_algorithms_* / comprehensive_crypto_matrix — Full algorithm combination coverage
• aead_ciphers_verification / non_aead_ciphers_verification — AEAD vs non-AEAD validation
• key_renegotiation_flow — Key refresh scenarios
• bidirectional_encrypted_communication — Full duplex encrypted channel

Message handler (atbus_message_handler) — 16 tests

Access data plaintext format, HMAC-SHA256 signatures:

• make_access_data_plaintext_crypto_* — Plaintext format: timestamp:nonce1-nonce2:bus_id[:type:hash]
• make_access_data_plaintext_custom_command_* — Command hash inclusion
• calculate_access_data_signature_* — HMAC-SHA256 computation with various inputs
• generate_access_data_* — Full access_data generation with tokens
• integration_* — Plaintext-signature consistency and determinism

Topology (atbus_topology) — 9 tests

• topology_peer_basic / topology_peer_downstream_iteration — Peer creation and iteration
• topology_registry_relations — Self/upstream/downstream relation types
• topology_registry_update_and_remove — Peer lifecycle
• topology_registry_*_auto_removed_* — Proactive vs passive peer removal
• topology_registry_foreach_and_policy — Iteration and policies
• topology_registry_update_peer_cycle_detection — Loop prevention

Channel tests — 24 tests

TCP (channel_io_stream_tcp) — 8 tests

• io_stream_tcp_basic / io_stream_tcp_reset_by_client / io_stream_tcp_reset_by_server
• io_stream_tcp_size_extended (>64KB) / io_stream_tcp_connect_failed

Unix socket (channel_io_stream_unix) — 5 tests (non-Windows)

• io_stream_unix_basic / io_stream_unix_reset_* / io_stream_unix_size_extended

Memory (channel_mem) — 5 tests

• mem_attach_with_invalid_* — Magic/version/alignment validation
• mem_siso / mem_miso — Single/multi-input-single-output ring buffer

Shared memory (channel_shm) — 6 tests

• shm_attach_with_invalid_* — Validation checks
• shm_siso — SHM ring buffer round-trip

Other test groups

• buffer (11 tests) — Varint encoding, static/dynamic buffer manager modes
• atbus_endpoint (5 tests) — Connection retrieval, address type parsing
• atbus_node_relationship (3 tests) — FlatBuffers message, conf copy, endpoint ops
• atbus_node_setup (3 tests) — Listen override, algorithm enumeration
• libatbus_error (6 tests) — Error code to string mapping
• atbus_connection_context_crosslang (10 tests) — Binary enc/dec test vector generation
• atbus_access_data_crosslang (9 tests) — Auth signature test vector generation

Writing tests

Test files are under test/case/.

Minimal example

#include <frame/test_macros.h>
#include "atbus_node.h"

CASE_TEST(my_group, my_test) {
    CASE_EXPECT_EQ(1, 1);
}

Multi-node test pattern

CASE_TEST(atbus_node_msg, my_multi_node_test) {
    // 1. Setup libuv event loop
    uv_loop_t ev_loop;
    uv_loop_init(&ev_loop);

    // 2. Configure nodes
    atbus::node::conf_t conf;
    atbus::node::default_conf(&conf);
    conf.ev_loop = &ev_loop;
    conf.receive_buffer_size = 64 * 1024;
    conf.ping_interval = std::chrono::seconds{8};

    // 3. Create and initialize nodes
    auto node1 = atbus::node::create();
    auto node2 = atbus::node::create();
    node1->init(0x12345678, &conf);
    node2->init(0x12356789, &conf);

    // 4. Listen on addresses
    node1->listen("ipv4://127.0.0.1:16387");
    node2->listen("ipv4://127.0.0.1:16388");

    // 5. Start nodes
    atbus::node::start_conf_t start_conf;
    start_conf.timer_timepoint = unit_test_make_timepoint(0, 0);
    node1->start(start_conf);
    node2->start(start_conf);

    // 6. Connect and wait
    node2->connect("ipv4://127.0.0.1:16387");

    time_t proc_usec = 0;
    UNITTEST_WAIT_UNTIL(ev_loop,
        node1->is_endpoint_available(0x12356789), 8000, 8) {
        ++proc_usec;
        node1->proc(unit_test_make_timepoint(0, proc_usec));
        node2->proc(unit_test_make_timepoint(0, proc_usec));
    }
    CASE_EXPECT_TRUE(node1->is_endpoint_available(0x12356789));

    // 7. Send and verify
    // ... setup callbacks, send data, verify receipt ...

    // 8. Cleanup
    unit_test_setup_exit(&ev_loop);
}

Encryption test pattern

CASE_TEST(atbus_connection_context, my_crypto_test) {
    // 1. Init crypto globally
    atfw::util::crypto::cipher::init_global_algorithm();

    // 2. Create DH shared context
    auto dh_ctx = atfw::util::crypto::dh::shared_context::create("x25519");

    // 3. Create client/server connection contexts
    auto client_ctx = atbus::connection_context::create(
        protocol::ATBUS_CRYPTO_KEY_EXCHANGE_X25519, dh_ctx);
    auto server_ctx = atbus::connection_context::create(
        protocol::ATBUS_CRYPTO_KEY_EXCHANGE_X25519, dh_ctx);

    // 4. Perform handshake (see libatbus-protocol-crypto skill for full flow)
    // ...

    // 5. Pack encrypted message
    atbus::random_engine_t rng;
    auto packed = client_ctx->pack_message(msg, 3, rng, 65536);
    CASE_EXPECT_TRUE(packed.is_success());

    // 6. Unpack and verify
    atbus::message recv_msg;
    CASE_EXPECT_EQ(EN_ATBUS_ERR_SUCCESS,
        server_ctx->unpack_message(recv_msg, packed.get_success().as_span(), 65536));

    // 7. Cleanup
    atfw::util::crypto::cipher::cleanup_global_algorithm();
}

Wait macros reference

// Wait until condition is true (or timeout in ms)
UNITTEST_WAIT_UNTIL(uv_loop, condition, timeout_ms, tick_ms) {
    // Body executed each tick
    node->proc(timepoint);
}

// Wait while condition is true
UNITTEST_WAIT_IF(uv_loop, condition, timeout_ms, tick_ms) { ... }

// Wait fixed duration
UNITTEST_WAIT_MS(uv_loop, timeout_ms, tick_ms) { ... }

// Time point helper
auto tp = unit_test_make_timepoint(seconds, microseconds);

Address schemes for tests

• TCP: ipv4://127.0.0.1:PORT or ipv6://[::1]:PORT
• Unix (non-Windows): unix:///tmp/path.sock (3 slashes)
• Memory: mem://0xADDRESS (single process, pointer-based)
• Shared Memory: shm://NAME (cross-process)
• Pipe (Windows): pipe:///path

Windows notes (shared memory)

• Private shared memory does not allow cross-process sharing on Windows
• Public shared memory may require administrator privileges