> 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/go-agent/go-agent-v2/go-agent-how-to-use/test-runner-mode-test-framework.md).

# Test Runner Mode (Test Framework)

## Using the Go Agent in Test Runner Mode

Test Runner Mode is used when you want to instrument your Go 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 Go 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 Instrumenting a Test Runner with SeaLights Go Agent (Default Usage - Go Test)

{% stepper %}
{% step %}

#### Configuration

The first step configures the agent with the details it needs to run in Test Runner Mode, using the command `./slgoagent config ...`

**Minimum Required Parameters for this command:**

* `--token` - Your SeaLights authentication token or path to token file

You can set parameters on the `slgoagent config` command in three different ways: [CLI flags, environment variables, or configuration file](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/agent-configuration-parameters.md#ways-to-configure-agent-parameters). The examples below demonstrate each approach, using the minimum recommended parameters. For additional configuration options, see the [Go Agent Parameter Reference Table](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/agent-configuration-parameters/go-agent-parameter-reference-table.md).

**Example Configurations:**

{% tabs %}
{% tab title="CLI flags" %}
**Example 1: All parameters as CLI flags**

```bash
./slgoagent config \
  --token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." 
```

{% endtab %}

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

```bash
export SEALIGHTS_TOKEN="./sltoken.txt"

./slgoagent config
```

{% endtab %}

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

Create `.slconfig.yaml` in your project root:

```yaml
# Note: the Agent Token parameter cannot be added to the .slconfig.yaml
# add non-mandatory parameters in yaml format
# For example:
buildTags: "e2e"
```

Then run:

```bash
./slgoagent config --token="./sltoken.txt"
```

{% hint style="info" %}
HINT: Add your SeaLights Agent token in a file named `sltoken.txt` to the root of the project. The agent will find and use it automatically and your command can be shortened to `./slgoagent config`
{% endhint %}
{% endtab %}
{% endtabs %}

**What this command generates:**

* **build.json file** - Contains configuration that the agent will use in the following instrument step
* **Console output** - Confirmation of successful configuration
  {% endstep %}

{% step %}

#### Instrument the Test Code

This step adds instrumentation markers to your test framework code to track test execution.

**Command:**

```bash
./slgoagent instrument
```

**What this command does:**

* **Instruments** your Go test files with tracking markers
* **Preserves** original test logic while adding execution monitoring capabilities
* **Prepares** tests to report start/end times and results to SeaLights

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

{% hint style="info" %}
**Note about build tags:** If your tests use Go build tags (e.g., `go test -tags=integration,e2e -v ./tests/`), you must configure the `buildTags` parameter. Add the `--tags` parameter to your config command with the appropriate tags (e.g., `--tags="integration,e2e"`).
{% endhint %}
{% endstep %}

{% step %}

#### Run the Instrumented Tests

**Step 3-A.** *Minimum Required Parameters* for the SeaLights Go Agent in Test Runner Mode at *runtime*:

* `SL_TESTS_RUNNER` - Enables Test Runner Mode
* `SL_TEST_STAGE` - Name of the test stage (e.g., "integration", "e2e", "unit")
* `SL_LAB_ID` - The Lab ID configured on the Application you are testing
  * **⚠️ IMPORTANT:** If the Application you are testing was not configured with a Lab ID, you must use the BSID from the build you wish to test.

{% hint style="info" %}
**Mandatory Parameters for the SeaLights Go Runtime Agent**

These parameters are required for the **runtime agent on a test runner**. 

If your workflow does not allow you to set environment variables on the runtime environment†, you must set these params using the corresponding CLI flags found [Go Agent Parameter Reference Table](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/agent-configuration-parameters/go-agent-parameter-reference-table.md)so that the configuration can be included in the instrumentation of the test runner.\
\
†**Best Practice:** We recommend setting these parameters via environment variable in the *runtime environment*.
{% endhint %}

**Example Configuration**

{% tabs %}
{% tab title="Recommended" %}
**Example 1: Configure the SeaLights Runtime Agent behavior on the runtime environment**

```bash
# On the runtime environment
export SL_TESTS_RUNNER="true"
export SL_TEST_STAGE="integration"
export SL_LAB_ID="shoppingcart.dev.qa-blue"
```

{% endtab %}

{% tab title="via CLI flag" %}
**Example 2: Configure the SeaLights Runtime Agent behavior during "Step 1: Configuration"**

```bash
./slgoagent config \
  --token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --tests-runner \
  --test-stage="integration" \
  --lab-id="shoppingcart.dev.qa-blue"
```

{% endtab %}
{% endtabs %}

**Step 3-B. Run your test commands as normal.** 

The instrumented tests will automatically report test execution details to SeaLights.

```bash
# Run your tests as normal
go test ./...
# or with specific tags
go test -tags=integration -v ./tests/
# or your specific test command
```

**What happens during your test run:**

1. **Test execution opens** - A test stage is automatically opened with SeaLights
2. **Tests run and report** - Individual test names, durations, and results are sent to SeaLights
3. **Test execution closes** - The test stage is automatically closed when tests complete

For more information on how Test Runner Mode and Coverage Listener Mode work together, see [What are Agent "Usage Modes"?](https://github.com/Sealights/gitbook.setupandconfiguration/blob/master/sealights-agents-and-plugins/getting-started/what-are-agent-usage-modes.md)
{% endstep %}
{% endstepper %}

### Using Other Supported Frameworks

SeaLights Go agent supports integration with Ginkgo and Godog.

Use with Ginkgo requires an additional parameter during the configuration of your test runner (`--enableGinkgo`). More detailed information about using the Go Agent with Ginkgo can be found here: [Ginkgo](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/go-agent-how-to-use/test-runner-mode-test-framework/ginkgo.md)

Similarly, use with Godog requires an additional parameter `--enableGodog` during the configuration of your test runner. More information about using the Go Agent with Godog can be found here: [Godog](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/go-agent-how-to-use/test-runner-mode-test-framework/godog.md)

***

### 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 `--testStage` parameter is provided
* **"cannot initialize as test runner, missing SEALIGHTS\_LAB\_ID env var" error**: Ensure the `--labId` 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 `--tags` parameter to your config command with the appropriate tags (e.g., `--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/go-agent/go-agent-v2/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.