Coverage Listener Mode (Application Under Test)

Using the C++ Agent in Coverage Listener Mode

Coverage Listener Mode is used when you want to instrument your C++ application to collect code coverage data during testing. The agent monitors your application and reports which lines of code are executed, providing insights into test coverage and code quality.

Overview

The basic workflow for instrumenting your application with the SeaLights C++ Agent involves three basic steps:

1. Configuration - Set up agent parameters and generate a Build Session ID
2. Scan and Instrument - Analyze your code and add instrumentation markers
3. Deploy - Run your instrumented application to collect coverage data

These steps are described in more detail below.

---

Steps for Instrumenting an Application (AUT) with SeaLights C++ Agent

Prerequisites

Build the target application with these required compilers flags:

-g
-rdynamic
-finstrument-functions
-finstrument-functions-exclude-file-list=/usr/include
-ftest-coverage

Example: Makefile

Add the required flags to your CXXFLAGS:

CXXFLAGS = -g -Wall -std=c++2a -lm -rdynamic \
           -finstrument-functions \
           -finstrument-functions-exclude-file-list=/usr/include \
           -ftest-coverage

Example: CMake

Add the required flags to the C++ compiler configuration:

# Enable compilation flags required by the SeaLights C++ Agent
set(CMAKE_CXX_FLAGS "-g -Wall -rdynamic -finstrument-functions -finstrument-functions-exclude-file-list=/usr/include -ftest-coverage")

⚠️ IMPORTANT: Ensure these flags are applied during the compilation of the target application binaries so that the SeaLights tracer can collect runtime coverage and test execution data.

1

Configuration and Build Session ID Generation

The first step configures the agent and generates a Build Session ID (BSID) that uniquely identifies this build in the SeaLights system, using the command ./SL.Agent.Cpp config ...

Minimum Required Parameters for this command:

• --token or --tokenFile - Your SeaLights authentication token or path to token file
• --appName - Name of your application as it should appear in SeaLights
• --branchName - Git branch name (defaults to "unspecified" if not specified)
• --buildName - Build identifier (auto-generated timestamp if not specified)
• --include - Path to source code folder

TIP: We also recommend setting the --labId parameter on your Application. This can be set at application runtime, using an environment variable, or it can be set up at this configuration stage.

You can set these parameters in three different ways: CLI flags, environment variables, or configuration file (lowest priority). The examples below demonstrate each approach, using the minimum recommended parameters. For additional configuration options, see the C++ Agent Parameter Reference Table.

Example Configurations:

CLI

Example 1: Using parameters as CLI flags

./SL.Agent.Cpp config \
  --token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --appName="shopping-cart-service" \
  --branchName="feature-checkout" \
  --buildName="v1.2.3-build-456" \
  --labId="shoppingcart.dev.qa-blue" \
  --include="<source_folder_path>"

Environment variables

Configuration file

What this command generates:

• Build Session ID (BSID) - Unique identifier linking this build to SeaLights
• build.json file - Contains all configuration that will be used in the following scan step
• Console output - Confirmation of successful configuration and the generated BSID

2

Scan and Instrument the Application Code

This step analyzes your project structure and adds instrumentation markers to track method execution during testing.

Command:

./SL.Agent.Cpp scan

Minimum Required Parameters for this command:

• --token or --tokenFile - Your SeaLights authentication token or path to token file
• --buildSessionIdFile - Path to the buildSessionId.txt file generated by the ./SL.Agent.Cpp config command
• --binDir - Path to the directory with .gcno files generated during compilation
• --include - Comma-separated list of files or patterns to include for scanning. Examples, --include="src/*.cpp,include/*.h,main.cpp" and --inlude="*Core.cpp,mySrc.c??,Api*Client.cpp"

What this command does:

• Scans your project structure and reports it to SeaLights
• Instruments your C++ source code with lightweight tracking markers
• Preserves original code logic while adding coverage collection capabilities
• Creates instrumented versions of your source files

Output: The command will show progress as it processes files and adds instrumentation. You'll see output indicating which files are being scanned and instrumented.

3

Run Unit Tests (Optional)

If you have unit tests, run them now using your normal test commands.

4

Deploy the Instrumented Application Code

To run the target application, set the LD_PRELOAD environment variable to point to the appropriate C++ tracer library.

Example (Linux x86-64)

LD_PRELOAD=<path_to_cpp_agent>/libSL.Cpp.TracerLib.Linux_x64.so ./<your_application>

Replace:

• <path_to_cpp_agent> with the full path to the extracted C++ Agent directory
• <your_application> with the executable you want to run

Tracer Libraries by Platform

Use the tracer library that matches your target platform:

Platform	Tracer Library
Linux x86-64	libSL.Cpp.TracerLib.Linux_x64.so
Linux x86	libSL.Cpp.TracerLib.Linux_x86.so
Linux ARMv7	libSL.Cpp.TracerLib.Linux_armv7.so
Linux ARM64	libSL.Cpp.TracerLib.Linux_arm64.so

Verification: After deployment, verify that your application is correctly reporting to SeaLights:

1. Log into the SeaLights web interface
2. Navigate to "Cockpit" → "Live Agents Monitor"
3. Look for your application name in the list of active agents
4. Confirm that the status shows your agent as "Connected" or "Active"

If your application appears in the Live Agents Monitor, the integration is working correctly. Coverage data will now be collected when a test execution is opened with SeaLights.

---

Troubleshooting

Common Issues:

• "Input params validation failed. Token is empty" validation error: Ensure your token parameter is set correctly and the token file exists
• Network connectivity issues: Check firewall settings and proxy configuration
• "No tests captured by test listener" warning
• Application not appearing in Live Agents Monitor: Verify network connectivity and check application logs for SeaLights-related errors