Google GitGoogle Git
Sign in
fuchsia/fuchsia/HEAD/./src/developer/debug/e2e_tests
tree: ec05ba24b4bf64a729226da50ace7831c0122b52 [search]
  1. dap_integration_tests/
  2. inferiors/
  3. scripts/
  4. BUILD.gn
  5. e2e_test.cc
  6. e2e_test.h
  7. ffx_debug_agent_bridge.cc
  8. ffx_debug_agent_bridge.h
  9. main.cc
  10. README.md
  11. script_test.cc
  12. script_test.h
src/developer/debug/e2e_tests/README.md

ZXDB E2E Tests (e2e_tests)

This directory contains the test cases and supporting infrastructure for zxdb end-to-end (E2E) tests.

ScriptTest registers test cases dynamically from .script files in the scripts/ directory and runs them via script_test.cc. The script runner feeds commands from each .script file to the zxdb console and matches the console output against expected patterns.

Prerequisites

The test harness reads build-time configuration from environment variables that BUILD.gn exposes as C preprocessor macros:

  • ZXDB_E2E_TESTS_BUILD_TYPE: Identifies the active build configuration at runtime so scripts can skip unsupported build types.
  • ZXDB_E2E_TESTS_SYMBOL_DIR: Required directory containing hard-linked DWARF symbols (symbols_dir_test_data) for target inferior programs.
  • ZXDB_E2E_TESTS_SCRIPTS_DIR: Required path to the .script files under root_out_dir.
  • ZXDB_E2E_TESTS_FFX_TEST_DATA: Required when ffx debug builds as a separate subtool. Unused when ffx debug compiles directly into ffx.

FFX Isolate

Before registering GoogleTest cases, FfxDebugAgentBridge (ffx_debug_agent_bridge.cc) creates an FFX Isolate. The isolate connects to the target and exposes a local Unix socket that zxdb uses to connect to debug_agent (bridging FIDL and Unix sockets). In normal user sessions, ffx debug creates the target pipe and spawns zxdb as a child process instead.

The FFX Isolate reads these environment variables to connect to the target:

  • FUCHSIA_DEVICE_ADDR: The IPv4 or IPv6 address of the target. fx test and CI set this variable automatically. When running the test binary directly, read this address from ffx target list.
  • FUCHSIA_SSH_PORT: The target SSH port. fx test and CI set this variable automatically, or you must provide it when running the binary directly.
  • FUCHSIA_SSH_KEY: Path to the authorized target SSH private key. Optional for local runs when $HOME/.ssh/fuchsia_ed25519 exists.
  • FUCHSIA_TEST_OUTDIR: Output directory for ffx logs in CI environments. Optional for local runs.

FfxDebugAgentBridge reads these variables, initializes the FFX isolate in a temporary directory, and adds the target device. Next, it spawns ffx debug connect --agent-only as a child process while all test cases run. After the test suite finishes, FfxDebugAgentBridge deletes the isolate directory and stops the isolate daemon.

Subdirectories

This directory contains these subdirectories:

  • inferiors/: Target test programs compiled into the zxdb_e2e_inferiors Fuchsia package.
  • scripts/: .script files replayed by ScriptTest (script_test.cc) to test zxdb console workflows.
  • dap_integration_tests/: Python end-to-end and framework test suites for the zxdb Debug Adapter Protocol (DAP) server.

Authoring Rules & Pitfalls

Follow scripting.md and the rules below when writing or triaging .script tests.

Disabling a Single .script Test

Prepend DISABLED_ to a .script filename (for example, DISABLED_inline_frames.script) and link a https://fxbug.dev/<id> issue. Disabling one script preserves test coverage across the rest of the suite while you fix the failure.

Disabling a Single python DAP Test

Add the decorator @unittest.skip("...") with a reason string pointing to a bug link https://fxbug.dev/<id> above a test case.

Breaking on Functions Instead of Line Numbers

Always set breakpoints on function names rather than source line numbers in scripts/*.script unless the test specifically checks source-map settings. A line-number command such as until 9 passes locally but fails on CQ builders when source files are absent:

[zxdb] until 9
> 9
Source file .../e2e_tests/inferiors/async_rust_multithreaded.rs not found.
You might want to adjust the source file remap setting. See "get source-map".

The source file provider requires local source files to resolve line-number display information.

Interface

Public headers and test directories expose these harnesses:

  • zxdb::ScriptTest: End-to-end test harness (script_test.h, script_test.cc) that replays .script files against a live zxdb Console and Session.
  • zxdb::FfxDebugAgentBridge: Manages an isolated ffx environment (FFXIsolate) and bridges the debug_agent Unix socket for E2E tests (ffx_debug_agent_bridge.h).
  • dap_integration_tests/: Python test suites (dap_e2e_tests, dap_framework_test) that test the zxdb DAP server over an isolated ffx environment.

Invariants

Test authors and BUILD.gn definitions must preserve these invariants:

  • In scripts/*.script, break on function names instead of line numbers unless testing source-map, and wildcard volatile addresses, registers, and KOIDs with ??.
  • To disable a failing .script test without disabling the suite, rename the file with a DISABLED_ prefix and cite a https://fxbug.dev/<id> bug.
  • In BUILD.gn, place pure host tests (such as dap_framework_test) in tests gated only on is_host ($host_toolchain) so they run without a board. Gate tests on has_board only when they require target inferiors or target symbol generation (ZXDB_E2E_TESTS_SYMBOL_DIR or DAP_E2E_TESTS_SYMBOL_DIR).
  • When declaring host_test_data targets in BUILD.gn, list sources explicitly so CQ sandboxes receive required host binaries such as zxdb.
  • Keep E2E and integration tests enabled on both arm64 and x64. If a platform bug requires an exclusion, document it in BUILD.gn with a https://fxbug.dev/<id> link.
  • When testing crash or trap generation (__builtin_trap()), do not require ZX_EXCP_SW_BREAKPOINT (ud2 on x86_64 raises ZX_EXCP_UNDEFINED_INSTRUCTION). Assert that an exception occurred without over-constraining the architectural exception code unless testing a specific instruction.
  • In dap_integration_tests/, target Python 3.11+ and never land commented-out assertions. Use await asyncio.wait([prev_task]) to await FIFO predecessor tasks without propagating asyncio.CancelledError.

Side Effects

Running the E2E suite produces these host and target side effects:

  • Creates and deletes a temporary ffx isolate directory, and spawns ffx debug connect --agent-only as a child process.
  • Starts target inferior components from zxdb_e2e_inferiors and talks to a live Fuchsia device or emulator over SSH.

Verification

Run these commands to build and run the E2E test suites:

  • Build: fx build //src/developer/debug/e2e_tests:tests
  • Test (all .script E2E tests): fx test --e2e zxdb_e2e_tests
  • Test (single .script test): fx test --e2e zxdb_e2e_tests -- --gtest_filter="ScriptTest.<script_stem>"
  • Test (DAP suites): fx test dap_framework_test and fx test --e2e dap_e2e_tests