# 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[^1]) 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`:

```make
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:

```cmake
# 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.

{% stepper %}
{% step %}

#### 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

{% hint style="info" %}
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.
{% endhint %}

You can set these parameters in three different ways: [CLI flags, environment variables, or configuration file](https://docs.sealights.io/knowledgebase/setup-and-configuration/go-agent/go-agent-v2/agent-configuration-parameters#ways-to-configure-agent-parameters) (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:**

{% tabs %}
{% tab title="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>"
```

{% endtab %}

{% tab title="Environment variables" %}
**Example 2: Using environment variables**

```
export SL_APPNAME="shopping-cart-service"
export SL_BRANCHNAME="feature-checkout"
export SL_BUILDNAME="v1.2.3-build-456"
export SL_LABID="shoppingcart.dev.qa-blue"
export SL_INCLUDE="<source_folder_path>"

./SL.Agent.Cpp config
```

{% endtab %}

{% tab title="Configuration file" %}
**Example 3: Using settings.json configuration file**

```json
{
    "general": {
        "command": "run",
        "appName": "shopping-cart-service",
        "branchName": "feature-checkout",
        "buildName": "v1.2.3-build-456"
    },
    "session":{
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "LabId": "shoppingcart.dev.qa-blue"
    },
    "scan": {
        "binDir": "bin",
        "include": [
            "src/*.cpp,include/*.h,main.cpp"
        ]
    }
}
```

{% endtab %}
{% endtabs %}

**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
  {% endstep %}

{% step %}

#### Scan and Instrument the Application Code

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

**Command:**

```bash
./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.
{% endstep %}

{% step %}

#### Run Unit Tests (Optional)

If you have unit tests, run them now using your normal test commands.
{% endstep %}

{% step %}

#### 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)**

```bash
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.
{% endstep %}
{% endstepper %}

***

### 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

[^1]: Application Under Test