| name | running-test-libmongoc |
| description | Use when running, filtering, or debugging tests in the test-libmongoc executable of the MongoDB C Driver — the custom TestSuite framework in src/libmongoc/tests/TestSuite.h with its own flags (-l, -d, -f), test-naming rules, and JSON spec tests. |
Running test-libmongoc
Overview
test-libmongoc is the executable holding most libmongoc and libbson tests. It uses a custom test framework (src/libmongoc/tests/TestSuite.h), not a mainstream one, so its invocation, filtering, and test-naming rules are unique. This skill explains how to run and select tests with it.
The executable is excluded from the CMake ALL target. Build it first with the --target flag:
cmake --build cmake-build --target test-libmongoc
Running tests
Typical invocation:
./cmake-build/src/libmongoc/test-libmongoc -d -f -l "<test-name-or-pattern>"
| Flag | Meaning |
|---|
-l | Run tests matching a name or pattern. Repeatable — pass -l multiple times to select several tests in one run. |
-d | Print debug output. Useful when a test hangs. |
-f | Do not fork a process per test; abort on the first error. |
Run ./cmake-build/src/libmongoc/test-libmongoc --help for the full flag list.
-l matching rules
Matching against a test's name (TestSuite_TestMatchesName in TestSuite.c) is exact string, with one exception: a trailing * makes it a prefix match. There is no other wildcard support.
-l "*aggregate" does not work — a * is only special as the last character.- A trailing
* is a prefix match and over-matches siblings: -l "/crud/unified/aggregate*" also matches /crud/unified/aggregate-let, /crud/unified/aggregate-merge, etc. To run exactly one test, pass its full name without a * (e.g. -l "/crud/unified/aggregate").
Finding a test's name
A test's registration string may bundle a name and one or more space-separated [...] tags. At registration (_V_TestSuite_AddFull) the string is split on the first space: everything before it is the test's name, and the bracketed tags are stored separately as metadata. -l matches the name only — never include a tag in the pattern. Names come from one of two places:
- The second argument to a
TestSuite_Add* call. In /loadbalanced/connect/single [lock:live-server],
the name is /loadbalanced/connect/single and [lock:live-server] is a tag indicating the
test needs a live MongoDB server. Match it with -l "/loadbalanced/connect/single".
- A JSON spec test. Its name is the path starting at (and including) the
/ after
src/libmongoc/tests/json, with .json removed. Spec tests installed via
install_json_test_suite also get a [lock:live-server] tag appended and a
TestSuite_CheckLive check, so they require a live server. Example:
src/libmongoc/tests/json/crud/unified/aggregate.json has the name
/crud/unified/aggregate (leading /, no tag) — match it with -l "/crud/unified/aggregate".
Tip: test-libmongoc --list-tests prints every registered test name (all tests, unfiltered; tags are not shown). Pipe it through grep to find the exact name to pass to -l.
Registration functions (server requirements)
Tests register with the suite through these functions; which one is used tells you whether a live server is required:
| Function | Requires live server? | Notes |
|---|
TestSuite_Add | No | Basic test. |
TestSuite_AddLive | Yes | Needs a live MongoDB server. |
TestSuite_AddFull | Depends | May use a context object or skip conditions. |
Common mistakes
- Including a
[...] tag in the -l pattern — tags are metadata, not part of the name; -l matches the name only. Use -l "/crud/unified/aggregate", not -l "/crud/unified/aggregate [lock:live-server]".
- Dropping the leading
/ from a spec-test name — the name is /crud/unified/aggregate, not crud/unified/aggregate. The leading slash is part of the name.
- Assuming a trailing
* matches exactly one test — it is a prefix match and catches siblings. See the matching rules above.
- Using a leading or interior wildcard —
-l "*aggregate" will not work; only a trailing * is supported.
- Forgetting to build the target first —
test-libmongoc is not built by the default ALL target.
- Expecting a fork-per-test by default when debugging — add
-f so the run aborts on the first failure instead of continuing, and -d to see where a hang occurs.
