Test Runner Mode (Test Framework)

Using the C++ Agent in Test Runner Mode

Test Runner Mode is used when you want to instrument your C++ test framework to send test execution details to SeaLights. The agent tracks test execution (start/end times, results, durations) and reports this data to SeaLights for analysis and correlation with coverage data.

Important: Test Runner Mode is designed to work in conjunction with Coverage Listener Mode. Your test framework (instrumented with SeaLights Agent in Test Runner Mode) must run tests against an application that is also instrumented and running with SeaLights Agent in Coverage Listener Mode. This allows SeaLights to correlate test execution data with coverage data from the application under test.

Overview

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

1. Configuration - Set up agent parameters

2. Instrument - Add instrumentation markers to your test framework code

3. Run Tests - Execute your instrumented tests

These steps are described in more detail below.

---

Steps for Configuring a Google Test (GTest) with SeaLights C++ Agent

1

Configuration

The first step configures the agent with the details it needs to run in Test Runner Mode, using the command ./SL.Agent.Cpp startExecution ...

Minimum Required Parameters for this command:

• --token - Your SeaLights authentication token or path to token file

• --buildSessionIdFile - Enables Test Runner Mode

• --testStage - Name of the test stage (e.g., "integration", "e2e", "unit")

• --labId - The Lab ID configured on the Application you are testing

Command:

SL.Agent.Cpp startExecution \
  --testStage <UnitTests> \
  --buildSessionIdFile <bsid_path> \
  --tokenFile <token_path>

What this command does

• Opens a test execution stage in SeaLights

• Prepares the agent to receive test execution and coverage data

2

Start the Coverage Listener

Start the background coverage listener to collect runtime coverage information from the C++ tracer.

Command:

SL.Agent.Cpp startBackgroundTestListener \
  --buildSessionIdFile <bsid_path> \
  --tokenFile <token_path> \
  --testListenerSessionKey <someID>

Optional Parameter

--agentAddress - use this parameter if the C++ tracer will connect from another machine.

Example:

--agentAddress "0.0.0.0"

What this command does

• Starts a background listener that receives coverage data

• Opens a session used by the tracer to stream execution data

3

Run the Instrumented Tests

Run your Google Test binary while loading the SeaLights C++ tracer library using LD_PRELOAD.

Example:

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

Replace:

• <path_to_cpp_agent> with the directory containing the C++ Agent

• <your_test_binary> with the compiled Google Test executable

Tracer Libraries by Architecture

Use the tracer that matches your platform:

Platform	Tracer Library
x64	libSL.Cpp.TracerLib.Linux_x64.so
x86	libSL.Cpp.TracerLib.Linux_x86.so
ARMv7	libSL.Cpp.TracerLib.Linux_armv7.so
ARM64	libSL.Cpp.TracerLib.Linux_arm64.so

What happens during test execution

• The SeaLights tracer attaches to the running test process

• Test execution data is collected for supported test frameworks

• Coverage information is captured and streamed to the background listener

4

Stop the Coverage Listener

After the tests complete, stop the background coverage listener.

Command:

SL.Agent.Cpp stopBackgroundTestListener \
  --buildSessionIdFile <bsid_path> \
  --tokenFile <token_path> \
  --testListenerSessionKey <someID>

What this command does

• Stops the coverage collection session

• Finalizes coverage data processing

5

End the Test Execution

Finally, close the SeaLights test execution stage.

Command:

SL.Agent.Cpp endExecution \
  --buildSessionIdFile <bsid_path> \
  --tokenFile <token_path>

What this command does

• Closes the test stage in SeaLights

• Finalizes test execution reporting

---

Troubleshooting

Common Issues:

• "token is required" error: Ensure your token parameter is set correctly and the token file exists

• "cannot initialize as test runner, missing SEALIGHTS_TEST_STAGE env var" error: Ensure the --test-stage parameter is provided

• "cannot initialize as test runner, missing SEALIGHTS_LAB_ID env var" error: Ensure the --lab-id parameter is provided and matches the Lab ID from your Coverage Listener Mode setup

• "no test functions were instrumented, this might cause the agent to not run in Unit Test mode" warning: This occurs when your tests use Go build tags but the buildTags parameter is not configured. Add the --build-tags parameter to your config command with the appropriate tags (e.g., --build-tags="integration,e2e")