# 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)](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/..#step-1-configuration)

**Example configuration**

Like most other parameters, you can add the Ginkgo parameter in three different ways: [CLI flags, environment variables, or configuration file](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/agent-configuration-parameters#ways-to-configure-agent-parameters). 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/agent-configuration-parameters/go-agent-parameter-reference-table).

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

```bash
./slgoagent config \
  --token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --testRunner \
  --testStage="component" \
  --enable-ginkgo \
  --labId="shoppingcart.dev.qa-blue"
```

{% endtab %}

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

```bash
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**

{% code overflow="wrap" %}

```bash
export SEALIGHTS_ENABLE_GINKGO=true

./slgoagent config \
--token="your-token" \
--testRunner \
--testStage="component" \
--labId="your-lab-id"
```

{% endcode %}
{% endtab %}

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

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

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

Then run:

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

{% endtab %}
{% endtabs %}

### 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:

```bash
# 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.
```

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

```yaml
testsRunner: true
enableGinkgo: true
fullTestName: true
```

Then run `slgoagent config` with your token, for example:

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

3. **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:

```bash
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](#test-impact-analysis-tia-support) below.

### Test Impact Analysis (TIA) Support

The Ginkgo integration includes full TIA support:

{% hint style="warning" %}
**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.
{% endhint %}

* **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",](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/..#steps-for-instrumenting-a-test-runner-with-sealights-go-agent-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