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)

1

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

• --tests-runner - Enables Test Runner Mode

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

• --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.

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

Example Configurations:

CLI flags

Example 1: All parameters as CLI flags

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

Environment variables

Example 2: Using environment variables

export SEALIGHTS_TOKEN="./sltoken.txt"
export SEALIGHTS_TESTS_RUNNER="true"
export SEALIGHTS_TEST_STAGE="integration"
export SEALIGHTS_LAB_ID="shoppingcart.dev.qa-blue"

./slgoagent config

Configuration file

Example 3: Using configuration file

Create .slconfig.yaml in your project root:

testsRunner: true
testStage: "integration"
labId: "shoppingcart.dev.qa-blue"

Then run:

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

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

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

2

Instrument the Test Code

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

Command:

./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.

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 --build-tags parameter to your config command with the appropriate tags (e.g., --build-tags="integration,e2e").

3

Run the Instrumented Tests

Run your test commands as normal. The instrumented tests will automatically report test execution details to SeaLights.

# 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 [PLACEHOLDER LINK TO EXPLANATION OF HOW THE COVERAGE LISTENER AND TEST RUNNER MODES WORK TOGETHER].

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

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

---

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