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

You can set parameters on the slgoagent config command 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..." 

Environment variables

Configuration file

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

3

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.

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

Example Configuration

Recommended

Example 1: Configure the SeaLights Runtime Agent behavior on the runtime environment

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

via CLI flag

Step 3-B. 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 What are Agent "Usage Modes"?

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