Ginkgo

Using the Go Agent with Ginkgo

The Go Agent provides special support for the Ginkgo BDD test framework. When enabled, the agent automatically integrates with Ginkgo's test lifecycle to track test execution and support Test Impact Analysis (TIA) features.

The configuration described here supplements Step 1: Configuration found in the Steps for Instrumenting a Test Runner with SeaLights Go Agent

Configuration

To use the Go Agent with Ginkgo tests, simply add the --enableGinkgo parameter when following the Steps for Instrumenting a Test Runner with SeaLights Go Agent (Default Usage - Go Test)

Example configuration

Like most other parameters, you can add the Ginkgo parameter in three different ways: CLI flags, environment variables, or configuration file. The examples below demonstrate each approach, using the minimum recommended parameters for a Ginkgo Test Runner. For additional configuration options, see the Go Agent Parameter Reference Table.

CLI flags

Example 1: All parameters as CLI flags

./slgoagent config \
  --token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  --enableGinkgo

Environment variables

Example 2: Using environment variables

export SL_TOKEN="./sltoken.txt"
export SL_ENABLE_GINKGO=true

./slgoagent config

Example 2b: Using environment variables with CLI flags

export SL_TOKEN=****************

./slgoagent config \
--enableGinkgo

Configuration file

Example 3: Using configuration file

Create .slconfig.yaml in your project root:

enableGinkgo: true

Then run:

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

How It Works

When Ginkgo support is enabled, the agent:

1. Generates Ginkgo Loader: Creates a special ginkgo_loader.go file during instrumentation
2. Hooks into Ginkgo Lifecycle: Automatically integrates with Ginkgo's BeforeEach and AfterEach hooks
3. Tracks Test Execution: Monitors individual Ginkgo specs (test cases) including:

   • Test start and end times
   • Test results (passed/failed/skipped)
   • Test names

Test Names Reported to SeaLights

By default, SeaLights records each Ginkgo test using the short text from the It(...) block — for example, "should return the correct sum". No extra parameter is required; this is the behavior whenever Ginkgo support is enabled.

Optional — fullTestName: If you prefer SeaLights to use the full BDD-style title for each test (the whole Describe / Context / It chain as one string), enable the optional fullTestName parameter. That changes how the test is labeled — for example, "Addition Operation when adding two positive numbers should return the correct sum" instead of only "should return the correct sum". This only applies to Ginkgo test runners (configured with enableGinkgo: true).

You can enable fullTestName in three ways:

1. CLI flag on the config command — pass --fullTestName when you run slgoagent config on your test runner:

# config command
./slgoagent config \
  --token="./sltoken.txt" \
  --testRunner \
  --enableGinkgo \
  --fullTestName
# instrument the test runner
./slgoagent instrument
# the fullTestName setting will be persisted to the embedded agent configuration.

1. Configuration file passed to config — add fullTestName: true to .slconfig.yaml (alongside your other settings), then run slgoagent config as usual:

testsRunner: true
enableGinkgo: true
fullTestName: true

Then run slgoagent config with your token, for example:

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

1. Environment variable at test run time — set SL_FULL_TEST_NAME or SEALIGHTS_FULL_TEST_NAME when you execute tests. This applies at test runner runtime and does not require re-instrumenting:

export SL_FULL_TEST_NAME=true
./your-ginkgo-test-runner.sh

Enabling or changing fullTestName affects Test Impact Analysis; see the warning in Test Impact Analysis (TIA) Support below.

Test Impact Analysis (TIA) Support

The Ginkgo integration includes full TIA support:

Full hierarchical test names (fullTestName): Using this parameter functionally changes the test names reported to SeaLights. This means existing TIA history will not match the new names until enough runs have been recorded under the new scheme—so TIA can behave as if prior history no longer applies. Only enable or change fullTestName if you have not started relying on TIA yet, or if you accept losing the practical value of TIA data collected up to this point.

• Automatic Test Skipping: Tests identified by TIA as unnecessary will be automatically skipped
• Proper Reporting: Skipped tests are correctly reported to SeaLights with skip status

When a test is skipped by TIA, you'll see output like:

Sealights agent marked this test 'MyTestName' as skipped.

Compatibility

• Ginkgo Version: Supports Ginkgo v2+ (github.com/onsi/ginkgo/v2)
• Go Versions: Compatible with Go 1.24+ (same as standard Go Agent requirements)
• Test Patterns: Works with all Ginkgo patterns (Describe, Context, It, etc.)

Usage Steps

1. Configure, following the steps detailed for "Default Usage - Go Test", adding the --enable-ginkgo parameter
2. Instrument your test code using ./slgoagent instrument
3. Run your Ginkgo tests normally - the agent integration is automatic

No changes to your existing Ginkgo test code are required. The agent integration happens automatically through the generated loader file.

Notes

• Ginkgo support works alongside standard Go test support in the same project
• Test reporting includes Ginkgo-specific test names and hierarchy