> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/go-agent-how-to-use/test-runner-mode-test-framework.md).

# 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

{% stepper %}
{% step %}

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

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

{% step %}

#### Start the Coverage Listener

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

**Command:**

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

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

{% step %}

#### Run the Instrumented Tests

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

Example:

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

{% step %}

#### Stop the Coverage Listener

After the tests complete, stop the background coverage listener.

**Command:**

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

{% step %}

### End the Test Execution

Finally, close the SeaLights test execution stage.

**Command:**

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

**What this command does**

* Closes the test stage in SeaLights
* Finalizes test execution reporting
  {% endstep %}
  {% endstepper %}

***

### 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"`)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/go-agent-how-to-use/test-runner-mode-test-framework.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.