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.shstartsfdbserveron127.0.0.1:4500, writes logs tobuild/testdatastore/logs, and PID tobuild/testdatastore/fdbserver.pid;scripts/stop-fdb-for-tests.shstops that managed server and removes the test database directory. - Windows: unsupported for Maryk FoundationDB JVM tests.
scripts/install-foundationdb.ps1exits 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/binand native libs understore/foundationdb/bin/lib. The Gradle JVM test task setsjava.library.pathandDYLD_LIBRARY_PATH/LD_LIBRARY_PATHto this location.
Gradle Integration
Section titled “Gradle Integration”- 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:
allTestsincludes only the exact host native architecture (for example,macosArm64Teston Apple Silicon), alongside JVM tests. The installed C client matches that host. Explicit target checks such ascompileTestKotlinLinuxX64andlinkDebugTestLinuxX64remain 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.
Configuration
Section titled “Configuration”FDB_VERSION: Optional FoundationDB release selector. Pinned releases are7.3.81(default) and7.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 (defaultdata). Options:data: deletebuild/testdatastore/data(database wiped).all: deletebuild/testdatastore/dataandbuild/testdatastore/logs.none: keep both.
- Cluster file: Tests use
store/foundationdb/fdb.cluster(exported asFDB_CLUSTER_FILEfor JVM tests). The run script will create it if missing. - Ports/paths: Default listen/public address
127.0.0.1:4500, databuild/testdatastore/data, logsbuild/testdatastore/logs.
Manual Usage
Section titled “Manual Usage”- 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.shandbash scripts/stop-fdb-for-tests.sh(respectsFDB_CLEAN_MODE).
Notes:
- On macOS, the installer downloads and extracts the FoundationDB
.pkgfrom GitHub releases iffdbserveris not on thePATH, and copieslibfdb_c.*intobin/lib. - On Linux, if no package manager is detected, the installer downloads and extracts
.debartifacts 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:
./gradlew :store:foundationdb:jvmTestTo 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.
./gradlew -PfoundationDbBindingsPath=../foundationdb-multiplatform :store:foundationdb:jvmTestFor 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.
