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.

Configuration

To use the Go Agent with Ginkgo tests, simply add the --enable-ginkgo 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..." \
  --tests-runner \
  --test-stage="component" \
  --enable-ginkgo \
  --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="component"
export SEALIGHTS_ENABLE_GINKGO=true
export SEALIGHTS_LAB_ID="shoppingcart.dev.qa-blue"

./slgoagent config

Example 2b: Using environment variables with CLI flags

export SEALIGHTS_ENABLE_GINKGO=true

./slgoagent config \
--token="your-token" \
--tests-runner \
--test-stage="component" \
--lab-id="your-lab-id"

Configuration file

Example 3: Using configuration file

Create .slconfig.yaml in your project root:

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

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 and descriptions

Test Impact Analysis (TIA) Support

The Ginkgo integration includes full TIA support:

• 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.22+ (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

• The --enable-ginkgo parameter is only used in Test Runner Mode

• Ginkgo support works alongside standard Go test support in the same project

• Test reporting includes Ginkgo-specific test names and hierarchy