Skip to content

Local Test Server

For an isolated native backup/restore rehearsal using separate disposable clusters, see the recovery drill. It runs independently of the managed test-server lifecycle described below.

This module can automatically install and run a local FoundationDB server for JVM and desktop native tests.

  • Automatic test lifecycle: macOS/Linux only. scripts/run-fdb-for-tests.sh starts fdbserver on 127.0.0.1:4500, writes logs to build/testdatastore/logs, and PID to build/testdatastore/fdbserver.pid; scripts/stop-fdb-for-tests.sh stops that managed server and removes the test database directory.
  • Windows: unsupported for Maryk FoundationDB JVM tests. scripts/install-foundationdb.ps1 exits intentionally because the required release artifacts and checksums are not pinned. Do not use it as an installer; use macOS/Linux for the managed local test lifecycle.
  • Install location: Binaries are placed under store/foundationdb/bin and native libs under store/foundationdb/bin/lib. The Gradle JVM test task sets java.library.path and DYLD_LIBRARY_PATH/LD_LIBRARY_PATH to this location.
  • Auto start/stop: JVM and supported native test tasks acquire the shared test-server lease, reset test data, start FDB, and finalize by stopping it. The lease prevents another Gradle invocation in the same checkout from resetting the server during a test run.
  • Native client shutdown: The Native test launcher calls FDB.instance().shutdown() after all selected tests finish, before process teardown. Test filters and failure exit codes are preserved. See process lifecycle for the host application contract.
  • Native target selection: allTests includes only the exact host native architecture (for example, macosArm64Test on Apple Silicon), alongside JVM tests. The installed C client matches that host. Explicit target checks such as compileTestKotlinLinuxX64 and linkDebugTestLinuxX64 remain available; linking requires a C client for that target. CI continues to run each supported native test task on its matching runner/client architecture.
  • Tasks:
    • installFoundationDB: installs or links FDB locally.
    • startFoundationDBForTests: starts the local server.
    • stopFoundationDBForTests: stops the server and cleans data.
  • FDB_VERSION: Optional FoundationDB release selector. Pinned releases are 7.3.81 (default) and 7.3.79; other versions fail before local/system installation, download, or extraction. If unset, scripts use the project default matching the client dependency.
  • FDB_CLEAN_MODE: Post‑test cleanup (default data). Options:
    • data: delete build/testdatastore/data (database wiped).
    • all: delete build/testdatastore/data and build/testdatastore/logs.
    • none: keep both.
  • Cluster file: Tests use store/foundationdb/fdb.cluster (exported as FDB_CLUSTER_FILE for JVM tests). The run script will create it if missing.
  • Ports/paths: Default listen/public address 127.0.0.1:4500, data build/testdatastore/data, logs build/testdatastore/logs.
  • Install (macOS/Linux): bash scripts/install-foundationdb.sh.
  • Install (Windows): not supported by Maryk. The PowerShell script exits intentionally; it does not install or configure a test runtime.
  • Start/stop (macOS/Linux only): bash scripts/run-fdb-for-tests.sh and bash scripts/stop-fdb-for-tests.sh (respects FDB_CLEAN_MODE).

Notes:

  • On macOS, the installer downloads and extracts the FoundationDB .pkg from GitHub releases if fdbserver is not on the PATH, and copies libfdb_c.* into bin/lib.
  • On Linux, if no package manager is detected, the installer downloads and extracts .deb artifacts locally.
  • Windows FoundationDB testing is not supported by this module’s local tooling until release artifacts and checksums are pinned.

Binding development and performance probes

Section titled “Binding development and performance probes”

The store targets FoundationDB client 7.3.81, API version 730, and Kotlin multiplatform binding 7.3.81.1. Run the JVM suite from the repository root:

Terminal window
./gradlew :store:foundationdb:jvmTest

To test a sibling binding checkout before publishing its release, pass an explicit source path. The development adapter compiles those sources with Maryk’s verified toolchain; normal builds keep using the pinned Maven dependency.

Terminal window
./gradlew -PfoundationDbBindingsPath=../foundationdb-multiplatform :store:foundationdb:jvmTest

For native development, first run downloadFoundationDbHeaders in the binding checkout. :store:foundationdb:runFoundationDBPerformanceProbe runs opt-in local comparisons for streaming modes, unique-owner lookup, bulk import and rebuilding. It validates results and reports timings without flaky timing assertions.