Coverage instrumentation

Coverage instrumentation tells Antithesis which lines of code are reached over the course of testing. Having coverage callbacks at every basic block in the program’s control flow enables the Antithesis platform to test your program more effectively.

For some languages, instrumentation is required to define test properties, consult the language-specific documentation for more details.

When you instrument your code, you may need to install additional runtime dependencies into your containers, but the benefits are well worth it.

Benefits of instrumentation

When run in Antithesis, instrumentation provides the following benefits,

• Instrumentation sends continuous feedback to Antithesis, which enables it to find bugs faster and more reliably.
• Instrumentation enables a powerful fault-injection technique called thread pausing which is useful for finding subtle race conditions and other concurrency bugs.
• Instrumentation provides much richer data to the bug report, allowing us to automatically discover which lines of code were most and least associated with the bug.

Supported languages

The following is a list of languages that are supported for instrumentation.

• Go instrumentation
• C/C++ instrumentation
• Java instrumentation
• JavaScript instrumentation
• Rust instrumentation
• .NET instrumentation
• Other LLVM instrumentation

If your language is not on this list, it may still be possible to enable instrumentation. For more details, contact us at support@antithesis.com or ask on our Discord.

Symbolization

Symbolization is the process of translating between locations in your compiled code and locations in your source files. For some languages, Antithesis handles all of this automatically. For other languages, you might need to compile with specific flags, or have your build/CI system put symbol files into a specific location in order for symbolization to work.

If your code includes coverage instrumentation (whether from an Antithesis instrumentor or the language compiler) Antithesis expects to find symbol files, so if it doesn’t find any, it will report a failing property in the triage report under the “No Antithesis session errors” group to remind you to add them.

Please consult the language-specific documentation for detailed instructions on enabling symbolization.

Symbols are placed in the image containing the instrumented software. Antithesis will search the root of every container image you push for a directory named /symbols and automatically extract any symbol files it finds there. When searching for symbol files, Antithesis will follow symlinks, so you can place a symlink in the /symbols directory instead of a symbol file, which you might want to do if, for instance, your symbols are normally part of the same binary as your code.

Validation

You can confirm that the instrumentation process worked correctly by looking at your triage report.

Under the Setup property group, there is a default property called Software was instrumented. If this property is passing, then your code was instrumented successfully and we were able to symbolize it as well. Each example listed under this property is a different binary, program, or module that was successfully instrumented. The details section for the examples will list the name of the module and the number of locations within it that were instrumented.