Testing Guide
This document explains how tests are organized in the current repository and which interfaces new tests should target.
Test directories
packages/libfalcon-core/tests/
packages/libfalcon-protocols/tests/
packages/libfalcon-storage/tests/
packages/libfalcon-drives/tests/
packages/falcon-daemon/tests/These libraries currently contain:
unit/integration/performance/
Building tests
The recommended path is the vcpkg manifest build. The repository-root vcpkg.json declares gtest, so configuring with the vcpkg toolchain installs the test dependency automatically.
export VCPKG_ROOT=/path/to/vcpkg
cmake -B build-vcpkg-core -S . \
-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
-DVCPKG_TARGET_TRIPLET=x64-linux \
-DFALCON_BUILD_TESTS=ON \
-DFALCON_BUILD_DESKTOP=OFF \
-DFALCON_BUILD_DAEMON=OFF \
-DFALCON_BUILD_CLI=OFF \
-DFALCON_BUILD_EXAMPLES=OFF \
-DFALCON_ENABLE_RESOURCE_BROWSER=OFF \
-DFALCON_ENABLE_CLOUD_STORAGE=OFF \
-DFALCON_ENABLE_RESOURCE_SEARCH=OFF \
-DFALCON_ENABLE_CONFIG_MANAGER=OFF
cmake --build build-vcpkg-core --target falcon_core_tests falcon_split_tests -j4Verify the minimal stable surface of the core library:
./build-vcpkg-core/bin/falcon_core_tests --gtest_brief=1
./build-vcpkg-core/bin/falcon_split_tests --gtest_brief=1Current verified results:
falcon_core_tests: 384 tests passedfalcon_split_tests: 10 tests passed
To use system dependencies instead of vcpkg:
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFALCON_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failureA bare CMake configuration does not install dependencies from the vcpkg manifest. If GTest is not preinstalled, the repository skips the test directories rather than fetching dependencies over the network with FetchContent.
Common installation commands:
# macOS (Homebrew)
brew install googletest
# Ubuntu / Debian
sudo apt-get install libgtest-devAfter installation, rerun the CMake configuration and build commands above.
Interface baseline for tests
New tests should target these public symbols:
DownloadEngine::add_task()DownloadEngine::start_task()DownloadEngine::pause_task()DownloadEngine::resume_task()DownloadEngine::cancel_task()DownloadTask::status()DownloadTask::id()
Do not use startDownload(), loadPlugin(), or getStatus() as defaults in new test examples.
Basic examples
#include <gtest/gtest.h>
#include <falcon/download_engine.hpp>
TEST(DownloadEngineTest, CreateInstance) {
falcon::DownloadEngine engine;
EXPECT_GE(engine.get_total_task_count(), 0u);
}
TEST(DownloadEngineTest, AddTaskWithSupportedUrl) {
falcon::DownloadEngine engine;
auto task = engine.add_task("https://example.com/file.zip");
EXPECT_NE(task, nullptr);
}Test fixture
class DownloadEngineTest : public ::testing::Test {
protected:
void SetUp() override {
engine_ = std::make_unique<falcon::DownloadEngine>();
}
std::unique_ptr<falcon::DownloadEngine> engine_;
};
TEST_F(DownloadEngineTest, AddedTaskStartsAsPending) {
auto task = engine_->add_task("https://example.com/file.zip");
ASSERT_NE(task, nullptr);
EXPECT_EQ(task->status(), falcon::TaskStatus::Pending);
}Parameterized tests
class ProtocolSupportTest : public ::testing::TestWithParam<std::string> {
protected:
falcon::DownloadEngine engine_;
};
TEST_P(ProtocolSupportTest, UrlSupportCheck) {
EXPECT_TRUE(engine_.is_url_supported(GetParam()));
}
INSTANTIATE_TEST_SUITE_P(
CommonProtocols,
ProtocolSupportTest,
::testing::Values(
"https://example.com/file.zip",
"http://example.com/file.zip",
"ftp://ftp.example.com/file.zip"
)
);Integration-test guidance
Integration tests are a better fit for verifying:
- Whether a real URL routes to the correct handler.
- The transition of a download task from
PendingtoCompleted. - Resume and output-path behavior.
- Active-task counts and global concurrency limits.
Example:
TEST(DownloadEngineIntegration, AddThenStartTask) {
falcon::DownloadEngine engine;
falcon::DownloadOptions options;
options.output_directory = "/tmp/falcon-test";
auto task = engine.add_task("http://localhost:8080/test.zip", options);
ASSERT_NE(task, nullptr);
EXPECT_TRUE(engine.start_task(task->id()));
task->wait();
EXPECT_TRUE(
task->status() == falcon::TaskStatus::Completed ||
task->status() == falcon::TaskStatus::Failed);
}Coverage
cmake -B build -S . \
-DCMAKE_BUILD_TYPE=Debug \
-DFALCON_BUILD_TESTS=ON \
-DFALCON_ENABLE_COVERAGE=ON
cmake --build build
ctest --test-dir buildBest practices
- Test real interfaces from the public headers; do not extend new examples around historical design drafts.
- Prefer stable behavior: state transitions, URL support checks, output paths, and concurrency limits.
- Use local test servers or fixtures for network-dependent tests to avoid external-network flakiness.
- When a plugin is disabled by default, state the required build-option precondition in the test.