Skip to content

Commit 9151b32

Browse files
owend74owend74
committed
MB-70383: Add README for building and running kv_engine tests
Add documentation covering how to build and run kv_engine unit tests using CTest. The README provides: Build Instructions: - Link to tlm README for general build setup - repo sync and Build.sh usage with sanitizer options (-T/-A/-U/-R) - ninja kv_engine_everything to build all test executables Configuration: - Debug/DebugOptimized/Release/RelWithDebInfo build types - macOS ARM64 deployment target fix for to_chars availability Test Execution: - ctest commands (parallel, filtering, --stop-on-failure) - ninja kv_engine/test alternative for build-and-run - GoogleTest options for individual test binary control Troubleshooting: - Common issues and fixes (Not Run status, PCH errors) Change-Id: I5dcfb8840c8ee60ce4e951ca43b710efe7a8f375 Reviewed-on: https://review.couchbase.org/c/kv_engine/+/239372 Tested-by: Build Bot <build@couchbase.com> Reviewed-by: Trond Norbye <trond.norbye@couchbase.com>
1 parent e387be9 commit 9151b32

File tree

1 file changed

+172
-0
lines changed

1 file changed

+172
-0
lines changed

‎tests/README.txt‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
Running Unit Tests for kv_engine
2+
=================================
3+
4+
The kv_engine tests reside in kv_engine/tests and use CMake/CTest for test
5+
execution.
6+
7+
For general build instructions, see:
8+
https://github.com/couchbase/tlm?tab=readme-ov-file#how-to-build
9+
10+
Prerequisites
11+
-------------
12+
1. Ensure the source tree is synced using repo:
13+
repo sync
14+
15+
2. The build directory should be at the same level as the source (e.g., ../build)
16+
17+
3. ninja build system installed (used by default)
18+
19+
=============================================================================
20+
COMPLETE STEPS TO BUILD AND RUN ALL TESTS
21+
=============================================================================
22+
23+
Step 1: Sync and Build the Project
24+
----------------------------------
25+
From the top-level source directory:
26+
27+
repo sync
28+
./Build.sh
29+
30+
This will configure, build, and install the project to the 'install' directory.
31+
32+
Build.sh Options:
33+
-s source_root Source directory (default: current working directory)
34+
-b build_root Build directory (default: <cwd>/build)
35+
-i install_root Install directory (default: <cwd>/install)
36+
-X Set Mac platform to x86_64 (for arm64 Macs cross-compiling)
37+
-T Enable thread sanitizer
38+
-A Enable address sanitizer
39+
-U Enable undefined behavior sanitizer
40+
-R Set build type to RelWithDebInfo
41+
42+
Step 2: Build Test Executables
43+
------------------------------
44+
Test executables are NOT built by default. The simplest way to build
45+
everything for kv_engine (including all test programs) is:
46+
47+
cd <build_directory>
48+
ninja kv_engine_everything
49+
50+
Step 3: Run All Tests
51+
---------------------
52+
cd <build_directory>/kv_engine
53+
ctest --output-on-failure
54+
55+
Alternatively, you can build and run all tests in one step from the build
56+
directory (output goes to a file rather than console):
57+
58+
ninja kv_engine/test
59+
60+
=============================================================================
61+
DEBUG MODE
62+
=============================================================================
63+
64+
To build in Debug mode (full debug symbols, no optimization):
65+
66+
Option 1: Using Build.sh environment variable
67+
---------------------------------------------
68+
CMAKE_BUILD_TYPE=Debug ./Build.sh
69+
70+
Option 2: Manual CMake configuration
71+
------------------------------------
72+
cd <build_directory>
73+
cmake -DCMAKE_BUILD_TYPE=Debug ..
74+
ninja
75+
76+
Available build types:
77+
- Debug: Full debug symbols, no optimization (-O0 -g)
78+
- DebugOptimized: Debug symbols with optimization (-Og -g) [default]
79+
- Release: Full optimization, no debug symbols
80+
- RelWithDebInfo: Release with debug info
81+
82+
=============================================================================
83+
macOS ARM64 (Apple Silicon) Notes
84+
=============================================================================
85+
86+
For arm64 Macs, if you encounter "'to_chars' is unavailable" errors, ensure
87+
the deployment target is set correctly:
88+
89+
cd <build_directory>
90+
cmake -DCMAKE_BUILD_TYPE=Debug -DCB_OVERRIDE_OSX_DEPLOYMENT_TARGET=13.3 ..
91+
92+
After changing the deployment target, clean precompiled headers:
93+
94+
find . -name "*.pch" -delete
95+
96+
Then rebuild:
97+
98+
ninja
99+
100+
=============================================================================
101+
CTEST COMMANDS
102+
=============================================================================
103+
104+
Run all tests with output on failure:
105+
ctest --output-on-failure
106+
107+
Run tests with verbose output:
108+
ctest -V
109+
110+
Run a specific test by name (using regex):
111+
ctest -R <test-name-pattern>
112+
113+
List all available tests without running them:
114+
ctest -N
115+
116+
Re-run only failed tests:
117+
ctest --rerun-failed --output-on-failure
118+
119+
Run tests in parallel (e.g., 4 jobs):
120+
ctest -j4 --output-on-failure
121+
122+
Stop on first failure:
123+
ctest --stop-on-failure --output-on-failure
124+
125+
Run tests from top-level build directory:
126+
ctest --test-dir kv_engine --output-on-failure
127+
128+
=============================================================================
129+
TROUBLESHOOTING
130+
=============================================================================
131+
132+
1. Tests show "Not Run" status
133+
CAUSE: Test executables were not built
134+
FIX: Run "ninja kv_engine_everything" to build all test executables
135+
136+
2. Precompiled header errors after changing build settings
137+
CAUSE: Old .pch files compiled with different settings
138+
FIX: Run "find . -name '*.pch' -delete" and rebuild
139+
140+
3. To list all available test targets:
141+
cd <build_directory> && ninja -t targets | grep -E "_test|testsuite"
142+
143+
4. Build failures due to missing headers after repo sync
144+
FIX: Ensure all repos are properly synced:
145+
repo sync
146+
If conflicts exist, check with:
147+
repo status
148+
149+
=============================================================================
150+
RUNNING INDIVIDUAL TEST BINARIES DIRECTLY
151+
=============================================================================
152+
153+
For more control or debugging, you can run test binaries directly.
154+
Running a test binary without arguments runs all tests in that binary.
155+
156+
cd <build_directory>/kv_engine
157+
158+
# Run all tests in memcached_unit_tests
159+
./memcached_unit_tests
160+
161+
# Run EP-engine unit tests with a filter
162+
./ep-engine_ep_unit_tests --gtest_filter="*CheckpointTest*"
163+
164+
# List all available tests
165+
./memcached_unit_tests --gtest_list_tests
166+
167+
GoogleTest options (for *_test binaries):
168+
--gtest_filter=PATTERN Run only tests matching the pattern (omit to run all)
169+
--gtest_list_tests List all test names
170+
--gtest_repeat=N Run tests N times
171+
--gtest_shuffle Randomize test order
172+
--gtest_output=xml:FILE Output results to XML file

0 commit comments

Comments
 (0)