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.

Build it first — it is not part of the default ALL target (<build-dir> is the CMake binary directory):

cmake --build <build-dir> --target test-libmongoc

The examples below use a single-config generator. With a multi-config generator, select a configuration when building and running CTest (for example, with --config and -C); the executable may be in a configuration-specific directory.

There are two ways to run the resulting tests, and they suit different jobs:

Running via CTest

Every test case is registered as an individual CTest test named mongoc/<case-name>:

# List tests:
ctest --test-dir <build-dir> -N

# Run tests:
ctest --test-dir <build-dir> --output-on-failure -R "/server_selection/"

Use ctest --help to discover filtering and other CTest options. The MONGOC_TEST_* environment variables documented in CONTRIBUTING.md apply to CTest runs as well.

Each case's [...] tags (see Finding a test's name) are translated into CTest properties by build/cmake/LoadTests.cmake:

Cases run with the working directory set to the source root, and a case that reports itself skipped is recorded as skipped rather than passed.

Running the executable directly

Typical invocation:

<build-dir>/src/libmongoc/test-libmongoc -d -f -l "<test-name-or-pattern>"

For multi-config generators, the executable may be under a configuration-specific subdirectory; use the path produced by the build.

Run <build-dir>/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:

1. 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".
2. 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:

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.
• Reading a CTest timeout as a test failure — an untagged case is killed at 10 seconds, so a slow-but-correct test looks like a failure until it declares a timeout: tag. Confirm by running that one case directly.
• Passing an -l pattern to ctest -R, or vice versa — -l is an exact/prefix match on the bare test name, while -R is a regex over the CTest name (which carries the mongoc prefix).